Contacts ​

Endpoints ​

GET /v1/contacts
GET /v1/contacts/:id
POST /v1/contacts
PATCH /v1/contacts/:id
DELETE /v1/contacts/:id

List contacts ​

GET /v1/contacts

Returns a page of contacts.

Parameters ​

Returns ​

A page of contact summary objects.

{
  "object": "array",
  "has_more": true,
  "next": "/v1/contacts?cursor=eyJzb3J0IjoibmFtZSIsIm9yZGVyIjoiY...",
  "limit": 5,
  "size": 5,
  "data": [
    {
      "object": "contact",
      "id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
      "external_id": "ABC-123",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com",
      "phone_number": "+12345678910",
      "urls": {
        "details": "/v1/contacts/937ccbe2-4cb5-4c76-96bf-29510b514dfa",
      },
    },
    {...},
    {...},
    {...},
    {...},
  ],
}

Retrieve a contact ​

GET /v1/contacts/:id

Gets the details of a single contact.

Parameters ​

If the external flag is set, the system searches for a contact whose external_id (instead of id) matches the id request parameter. You can supply the external parameter in the payload or as a query parameter like:

GET /v1/contacts/:id?external

Returns ​

A contact object.

{
  "object": "contact",
  "id": "937ccbe2-4cb5-4c76-96bf-29510b514dfa",
  "external_id": "ABC-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone_number": "+12345678910",
  "attributes": {
    "department": "Sales",
    "office": "Austin"
  },
  "urls": {
    "details": "/v1/contacts/937ccbe2-4cb5-4c76-96bf-29510b514dfa"
  }
}

{
  "error": "Contact with the given ID was not found."
}

{
  "error": {
    "external": ["must be a boolean"]
  }
}

Errors ​

Create a contact ​

POST /v1/contacts

Creates a new contact.

Parameters ​

{
  "external_id": "ABC-123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john@example.com",
  "phone_number": "+12345678910",
  "attributes": {
    "department": "Sales",
    "office": "Austin"
  }
}

Returns ​

A success message and a 201 status code if successful.

{
  "message": "Contact created successfully"
}

Errors ​

Update a contact ​

PATCH /v1/contacts/:id

Updates a contact.

Parameters ​

If the external flag is set, the system searches for a contact whose external_id (instead of id) matches the id request parameter. This differs from the external_id request parameter, which is used to set the external_id of a contact.

If you do not supply a parameter, its value will remain unchanged. If you attempt to update a contact that does not currently have an external_id, you must supply an external_id value in your request.

Keys in the attributes object will overwrite existing attributes for the contact, but will not change other attributes not specified in the request. To remove a key from a contact's attributes, you must supply a null value for that key.

{
  "first_name": "John",
  "last_name": "Doe",
  "attributes": {
    "department": "Sales",
    "office": null // Removes the office attribute from this contact
  }
}

Returns ​

A success message and a 200 status code if successful.

{
  "message": "Contact updated successfully"
}

Errors ​

Delete a contact ​

DELETE /v1/contacts/:id

Deletes a contact.

Parameters ​

If the external flag is set, the system searches for a contact whose external_id (instead of id) matches the id request parameter.

Returns ​

A success message and a 200 status code if successful.

{
  "message": "Contact deleted successfully"
}

Errors ​