Contacts API

Manage your workspace's contacts: create, search, update, and delete contact records programmatically using the Contacts API endpoints.

---

📋 Contact Endpoints

Method	Path	Description
GET	/v1/contacts	Search contacts
POST	/v1/contacts	Create a new contact
GET	/v1/contacts/{contactId}	Get a contact by ID
PUT	/v1/contacts/{contactId}	Update a contact by ID
DELETE	/v1/contacts/{contactId}	Delete a contact by ID
POST	/v1/contacts/{contactId}/tags/add	Add tags to a contact
POST	/v1/contacts/{contactId}/tags/remove	Remove tags from a contact

---

---

Contacts API

Manage your workspace's contacts: create, search, update, and delete contact records programmatically using the Contacts API endpoints.

---

Endpoints

1. Search Contacts

GET /v1/contacts

• Description: Search for contacts with filtering, pagination, and search options.
• Authentication: Requires x-api-key header.

Query Parameters:

Name	In	Type	Required	Description
limit	query	string	No	Max number of results
tags	query	string	No	Filter by tags
workspaceId	query	string	No	Filter by workspace
page	query	string	No	Page number for pagination
channel	query	string	No	Filter by channel
searchText	query	string	No	Free text search
x-api-key	header	string	Yes	API authentication key

Response: [200 OK] - Contacts

---

2. Create New Contact

POST /v1/contacts

• Description: Create a new contact.
• Authentication: Requires x-api-key header.

Request Body: Contact (application/json)

Response: [200 OK] - Contact

---

3. Get Contact by ID

GET /v1/contacts/{contactId}

• Description: Retrieve a contact by its unique ID.
• Authentication: Requires x-api-key header.

Path Parameters:

Name	In	Type	Required	Description
contactId	path	string	Yes	Contact unique ID
x-api-key	header	string	Yes	API authentication key

Response: [200 OK] - Contact

---

4. Update Contact by ID

PUT /v1/contacts/{contactId}

• Description: Update an existing contact by ID.
• Authentication: Requires x-api-key header.

Path Parameters:

Name	In	Type	Required	Description
contactId	path	string	Yes	Contact unique ID
x-api-key	header	string	Yes	API authentication key

Request Body: Contact (application/json)

Response: [200 OK] - Contact

---

5. Delete Contact by ID

DELETE /v1/contacts/{contactId}

• Description: Delete a contact by ID.
• Authentication: Requires x-api-key header.

Path Parameters:

Name	In	Type	Required	Description
contactId	path	string	Yes	Contact unique ID
x-api-key	header	string	Yes	API authentication key

Response: [200 OK] - DeleteResponse

---

6. Add Tags to Contact

POST /v1/contacts/{contactId}/tags/add

• Description: Add tags to a contact.
• Authentication: Requires x-api-key header.

Path Parameters:

Name	In	Type	Required	Description
contactId	path	string	Yes	Contact unique ID
x-api-key	header	string	Yes	API authentication key

Response: [200 OK] - TagResponse

---

7. Remove Tags from Contact

POST /v1/contacts/{contactId}/tags/remove

• Description: Remove tags from a contact.
• Authentication: Requires x-api-key header.

Path Parameters:

Name	In	Type	Required	Description
contactId	path	string	Yes	Contact unique ID
x-api-key	header	string	Yes	API authentication key

Response: [200 OK] - TagResponse

---

Schemas

Contact Schema

{
  "id": "string",
  "name": "string",
  "phoneNumber": "string",
  "workspace": {
    "id": "string",
    "title": "string"
  },
  "stage": "Subscriber | Engaged | Lead | Marketing qualified lead (MQL) | Sales qualified lead (SQL) | Opportunity | Follow-up Required | Customer | Evangelist | Other | Lost | Inactive",
  "notes": "string",
  "customFields": { },
  "tags": ["string"]
}

TagResponse Schema

{
  "id": "string",
  "tags": ["string"]
}

DeleteResponse Schema

{
  "success": true
}

---

Tip: See the OpenAPI schema for detailed request/response models and required fields for each operation.