Contacts

Retrieve all contacts

get

Retrieve all contacts.

Authorizations

cookie

ambit_access-tokenstringRequired

Query parameters

emailstringOptional

The email of the contact to retrieve.

Example: [e-mail]

Responses

200

The collection of contacts.

application/json

401

The user is not authenticated.

403

The user does not have permission to perform this operation.

get

/contacts

HTTPcURLJavaScriptPython

GET /api/v1/contacts HTTP/1.1
Host: 
Accept: */*

[
  {
    "id": "981ba079-62a6-442c-8dfb-a72af6e96b8c",
    "email": "[e-mail]",
    "name": "John Doe",
    "status": "ACTIVE",
    "custom_fields": {
      "profession": "Career consultant",
      "company": "Acme Inc."
    },
    "tags": [
      {
        "id": "981ba079-62a6-442c-8dfb-a72af6e96b8c",
        "name": "Tag Name",
        "color": "BLUE",
        "created_at": "2025-01-01T00:00:00.000Z",
        "updated_at": "2025-01-01T00:00:00.000Z"
      }
    ]
  }
]

Create a contact

post

Create a contact.

Authorizations

cookie

ambit_access-tokenstringRequired

Body

application/json

emailstringRequired

The contact's email.

Example: [e-mail]

namestringRequired

The contact's name.

Example: John Doe

statusstring · enumRequired

The contact's status.

Possible values:

customFieldsobjectRequired

Custom field data for the contact.

Example: {"profession":"Career consultant","company_name":"Acme Inc."}

tagsstring[]Required

The IDs of tags to assign to the contact.

Example: ["db07bb52-1d59-48a8-8a0d-03005c997543","5ab65d05-1f7d-43a2-878e-90c69d6ad840","319d26ed-4e92-447b-b8f0-e84aba066dd1"]

Responses

201

The contact that was created.

application/json

401

The user is not authenticated.

403

The user does not have permission to perform this operation.

409

A contact already exists with the supplied email.

post

/contacts

HTTPcURLJavaScriptPython

POST /api/v1/contacts HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 270

{
  "email": "[e-mail]",
  "name": "John Doe",
  "status": "ACTIVE",
  "customFields": {
    "profession": "Career consultant",
    "company_name": "Acme Inc."
  },
  "tags": [
    "db07bb52-1d59-48a8-8a0d-03005c997543",
    "5ab65d05-1f7d-43a2-878e-90c69d6ad840",
    "319d26ed-4e92-447b-b8f0-e84aba066dd1"
  ]
}

{
  "id": "981ba079-62a6-442c-8dfb-a72af6e96b8c",
  "email": "[e-mail]",
  "name": "John Doe",
  "status": "ACTIVE",
  "custom_fields": {
    "profession": "Career consultant",
    "company": "Acme Inc."
  },
  "tags": [
    {
      "id": "981ba079-62a6-442c-8dfb-a72af6e96b8c",
      "name": "Tag Name",
      "color": "BLUE",
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Retrieve a single contact

get

Retrieve a single contact by their ID.

Authorizations

cookie

ambit_access-tokenstringRequired

Path parameters

contactIdstringRequired

The ID of the contact to retrieve.

Example: 981ba079-62a6-442c-8dfb-a72af6e96b8c

Responses

200

The contact.

application/json

401

The user is not authenticated.

404

The requested resource was not found.

get

/contacts/{contactId}

HTTPcURLJavaScriptPython

GET /api/v1/contacts/{contactId} HTTP/1.1
Host: 
Accept: */*

{
  "id": "981ba079-62a6-442c-8dfb-a72af6e96b8c",
  "email": "[e-mail]",
  "name": "John Doe",
  "status": "ACTIVE",
  "custom_fields": {
    "profession": "Career consultant",
    "company": "Acme Inc."
  },
  "tags": [
    {
      "id": "981ba079-62a6-442c-8dfb-a72af6e96b8c",
      "name": "Tag Name",
      "color": "BLUE",
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Update a contact

patch

Update a contact by their ID.

Authorizations

cookie

ambit_access-tokenstringRequired

Path parameters

contactIdstringRequired

The ID of the contact to retrieve.

Example: 981ba079-62a6-442c-8dfb-a72af6e96b8c

Body

application/json

emailstringOptional

The contact's email.

Example: [e-mail]

namestringOptional

The contact's name.

Example: John Doe

statusstring · enumOptional

The contact's status.

Possible values:

customFieldsobjectOptional

Custom field data for the contact.

Example: {"profession":"Career consultant","company_name":"Acme Inc."}

tagsstring[]Optional

The IDs of tags to assign to the contact.

Example: ["db07bb52-1d59-48a8-8a0d-03005c997543","5ab65d05-1f7d-43a2-878e-90c69d6ad840","319d26ed-4e92-447b-b8f0-e84aba066dd1"]

Responses

200

The updated contact.

application/json

401

The user is not authenticated.

403

The user does not have permission to perform this operation.

409

A contact already exists with the supplied email.

patch

/contacts/{contactId}

HTTPcURLJavaScriptPython

PATCH /api/v1/contacts/{contactId} HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 270

{
  "email": "[e-mail]",
  "name": "John Doe",
  "status": "ACTIVE",
  "customFields": {
    "profession": "Career consultant",
    "company_name": "Acme Inc."
  },
  "tags": [
    "db07bb52-1d59-48a8-8a0d-03005c997543",
    "5ab65d05-1f7d-43a2-878e-90c69d6ad840",
    "319d26ed-4e92-447b-b8f0-e84aba066dd1"
  ]
}

{
  "id": "981ba079-62a6-442c-8dfb-a72af6e96b8c",
  "email": "[e-mail]",
  "name": "John Doe",
  "status": "ACTIVE",
  "custom_fields": {
    "profession": "Career consultant",
    "company": "Acme Inc."
  },
  "tags": [
    {
      "id": "981ba079-62a6-442c-8dfb-a72af6e96b8c",
      "name": "Tag Name",
      "color": "BLUE",
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Delete a contact

delete

Delete a contact by their ID.

Authorizations

cookie

ambit_access-tokenstringRequired

Path parameters

contactIdstringRequired

The ID of the contact to retrieve.

Example: 981ba079-62a6-442c-8dfb-a72af6e96b8c

Responses

200

The deleted contact.

application/json

401

The user is not authenticated.

403

The user does not have permission to perform this operation.

delete

/contacts/{contactId}

HTTPcURLJavaScriptPython

DELETE /api/v1/contacts/{contactId} HTTP/1.1
Host: 
Accept: */*

{
  "id": "981ba079-62a6-442c-8dfb-a72af6e96b8c",
  "email": "[e-mail]",
  "name": "John Doe",
  "status": "ACTIVE",
  "custom_fields": {
    "profession": "Career consultant",
    "company": "Acme Inc."
  },
  "tags": [
    {
      "id": "981ba079-62a6-442c-8dfb-a72af6e96b8c",
      "name": "Tag Name",
      "color": "BLUE",
      "created_at": "2025-01-01T00:00:00.000Z",
      "updated_at": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Assign a tag to a contact

post

Assign a tag to a contact by their ID.

Authorizations

cookie

ambit_access-tokenstringRequired

Path parameters

contactIdstringRequired

The ID of the contact to retrieve.

Example: 981ba079-62a6-442c-8dfb-a72af6e96b8c

Query parameters

tagIdstringRequired

The ID of the tag.

Example: 981ba079-62a6-442c-8dfb-a72af6e96b8c

Responses

200

Tag assigned successfully.

No content

401

The user is not authenticated.

403

The user does not have permission to perform this operation.

post

/contacts/{contactId}/assign-tag

HTTPcURLJavaScriptPython

POST /api/v1/contacts/{contactId}/assign-tag?tagId=text HTTP/1.1
Host: 
Accept: */*

No content

Unassign a tag from a contact

post

Unassign a tag from a contact by their ID.

Authorizations

cookie

ambit_access-tokenstringRequired

Path parameters

contactIdstringRequired

The ID of the contact to retrieve.

Example: 981ba079-62a6-442c-8dfb-a72af6e96b8c

Query parameters

tagIdstringRequired

The ID of the tag.

Example: 981ba079-62a6-442c-8dfb-a72af6e96b8c

Responses

200

Tag unassigned successfully.

No content

401

The user is not authenticated.

403

The user does not have permission to perform this operation.

post

/contacts/{contactId}/unassign-tag

HTTPcURLJavaScriptPython

POST /api/v1/contacts/{contactId}/unassign-tag?tagId=text HTTP/1.1
Host: 
Accept: */*

No content

Retrieve a contact note

get

Retrieve a contact note by their ID.

Authorizations

cookie

ambit_access-tokenstringRequired

Path parameters

contactIdstringRequired

The ID of the contact to retrieve.

Example: 981ba079-62a6-442c-8dfb-a72af6e96b8c

Responses

200

The contact note.

application/json

401

The user is not authenticated.

404

The requested resource was not found.

get

/contacts/{contactId}/note

HTTPcURLJavaScriptPython

GET /api/v1/contacts/{contactId}/note HTTP/1.1
Host: 
Accept: */*

{
  "contact_id": "981ba079-62a6-442c-8dfb-a72af6e96b8c",
  "content": {},
  "updated_at": "2025-01-01T00:00:00.000Z"
}

Update a contact note

patch

Update a contact note by their ID.

Authorizations

cookie

ambit_access-tokenstringRequired

Path parameters

contactIdstringRequired

The ID of the contact to retrieve.

Example: 981ba079-62a6-442c-8dfb-a72af6e96b8c

Body

application/json

contentobjectRequired

The content of the note.

Responses

200

The updated contact note.

No content

401

The user is not authenticated.

403

The user does not have permission to perform this operation.

patch

/contacts/{contactId}/note

HTTPcURLJavaScriptPython

PATCH /api/v1/contacts/{contactId}/note HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 14

{
  "content": {}
}

No content