Available endpoints | Skarbe Help Center

Our API allows you to integrate with contacts, lead statuses, and user information. All endpoints require authentication using a secret key.

Authentication

All API endpoints require authentication using a secret key.

Contacts

Get Contacts

Retrieve a list of contacts from your organization with optional search functionality.

Endpoint: GET /api/connect/contacts

Query Parameters:

query (optional): Search term to filter contacts by first name, last name, or email

Response:

attributes: ['id', 'email', 'photo', 'firstName', 'lastName', 'fullName', 'jobTitle', 'companyName','phoneNumbers', 'facebookUrl', 'instagramUrl', 'linkedinUrl', 'note', 'lastActivityAt', 'createdAt'],

Returns an array of contact objects with the following fields:

id: Contact ID
email: Contact email address
photo: Profile photo URL
firstName: First name
lastName: Last name
fullName: Full name
jobTitle: Job title
companyName: Company name
phoneNumbers: Phone numbers
facebookUrl: Facebook profile URL
instagramUrl: Instagram profile URL
linkedinUrl: LinkedIn profile URL
note: Notes about the contact
lastActivityAt: Last activity timestamp
createdAt: Creation timestamp
leadStatus: Associated lead status object with id, label, and color

Example Request:

GET /api/connect/contacts?query=john

Example Response:

[ { "id": 1, "email": "[email protected]", "firstName": "John", "lastName": "Doe", "fullName": "John Doe", "jobTitle": "Developer", "companyName": "Acme Corp", "createdAt": "2023-01-15T10:00:00Z", "leadStatus": { "id": 1, "label": "New Lead", "color": "#3B82F6" } } ]

Create Contact

Create a new contact in your organization.

Endpoint: POST /api/connect/contacts

Request Body: At least one of email or firstName is required. Available fields:

[ 'email', 'firstName', 'lastName', 'jobTitle', 'companyName', 'phoneNumbers', 'facebookUrl', 'instagramUrl', 'linkedinUrl', 'twitterUrl', 'note', ];

Additional fields:

leadStatus: Lead status ID (optional)

Validation Rules:

email: Must be a valid email address if provided
firstName: Required if email is not provided
leadStatus: Must be a valid lead status ID for your organization

Example Request:

{ "email": "[email protected]", "firstName": "Jane", "lastName": "Smith", "jobTitle": "Marketing Manager", "companyName": "Tech Solutions Inc", "leadStatus": 1 }

Example Response:

{ "id": 2, "email": "[email protected]", "firstName": "Jane", "lastName": "Smith", "jobTitle": "Marketing Manager", "companyName": "Tech Solutions Inc", "createdAt": "2023-01-15T10:30:00Z" }

Error Responses:

400: Invalid request data

{ "error": "At least email or firstName is required" }

400: Invalid email format
```
{ "error": "Invalid email" }
```
400: Invalid lead status
```
{ "error": "Invalid lead status" }
```

Lead Statuses

Get Lead Statuses

Retrieve all available lead statuses for your organization.

Endpoint: GET /api/connect/contacts/lead-statuses

Response: Returns an array of lead status objects with the following fields:

id: Lead status ID
type: Status type (lead, qualified, or disqualified)
label: Display label
color: Color code for UI display
order: Sort order

Example Response:

[ { "id": 1, "type": "lead", "label": "New Lead", "color": "#3B82F6", "order": 1 }, { "id": 2, "type": "qualified", "label": "Qualified Lead", "color": "#10B981", "order": 2 } ]

User Information

Get Current User

Retrieve information about the current authenticated user and their workspace.

Endpoint: GET /api/connect/me

Response: Returns an object with user details and workspace information:

details: User information object
- name: User's full name
- email: User's email address
workspace: Organization information object
- name: Organization name

Example Response:

{ "details": { "name": "John Admin", "email": "[email protected]" }, "workspace": { "name": "Acme Corporation" } }

Error Handling

All endpoints return appropriate HTTP status codes:

200: Success
400: Bad Request (validation errors)
401: Unauthorized (invalid secret key)
500: Internal Server Error

Error responses include a JSON object with an error field containing the error message:

{ "error": "Error description" }