Scopes and endpoints: contacts, labels, custom attributes, canned responses

Last updated: 11 November 2026 · 13 min read

Steps

1. 1

   How to read this article

   • Paths follow https://api.clomni.ai/v1: GET /v1/agents means https://api.clomni.ai/v1/agents. Paths have no workspace ID, because a token belongs to one workspace.
   • Every request carries the Authorization: Bearer clomni_pat_xxx header. How to get a token: Tokens and authentication in the Developer API.
   • Risk: low (no personal data), medium (reads customer data or changes internal data), high (sends to customers, deletes, bulk exports, changes live settings).
   • Every scope goes through review, in public apps too. More: Review: checking scopes and rejection reasons.
   • "Also grants": write and manage grant the read of the same resource. send, delete, publish, assign and run grant nothing.
   • When an endpoint lists several scopes, any one of them is enough. Without the scope the API answers 403 insufficient_scope with required_scopes in the body.
   • Every POST takes an Idempotency-Key header, so a repeated request is not run twice.
2. 2

   Read contacts (contacts:read)

   Reads contacts: name, phone, email, identifier (the ID in your system), custom attributes, labels, notes. List, search, filter, contacts online now, possible duplicates, the inboxes that can reach a contact and sync (/v1/sync/contacts) use it. The contact.* webhooks need it too.

   • Risk: medium.
   • Review: goes through review. Say exactly which data you use with it, when and why.
   • Also grants: nothing else.

   Endpoints:

   • GET /v1/companies: List companies
   • GET /v1/companies/search: Search companies
   • GET /v1/companies/{company_id}: Get a company
   • POST /v1/contact_inboxes/filter: Find a contact inbox by source ID
   • GET /v1/contacts: List contacts
   • GET /v1/contacts/active: List contacts online now
   • POST /v1/contacts/filter: Filter contacts
   • GET /v1/contacts/search: Search contacts
   • GET /v1/contacts/{contact_id}: Get a contact
   • GET /v1/contacts/{contact_id}/contactable_inboxes: List inboxes that can reach a contact
   • GET /v1/contacts/{contact_id}/labels: List a contact's labels
   • GET /v1/contacts/{contact_id}/merge_suggestions: List possible duplicates of a contact
   • GET /v1/contacts/{contact_id}/notes: List notes
   • GET /v1/contacts/{contact_id}/notes/{note_id}: Get a note
   • GET /v1/search/contacts: Search contacts (global search)
   • GET /v1/sync/contacts: Sync contacts

   Example:

   curl "https://api.clomni.ai/v1/contacts/search?q=crm-10422" \
     -H "Authorization: Bearer clomni_pat_xxx"

   curl "https://api.clomni.ai/v1/sync/contacts?updated_since=2026-11-10T00:00:00Z&limit=100" \
     -H "Authorization: Bearer clomni_pat_xxx"

3. 3

   Edit contacts (contacts:write)

   Creates and updates contacts, merges two contacts, writes labels and notes, links a contact to an inbox. In PATCH, custom_attributes are merged with the existing ones; keys you do not send are kept. Deleting needs contacts:delete.

   • Risk: medium.
   • Review: goes through review. Say exactly which data you use with it, when and why.
   • Also grants: contacts:read.

   Endpoints:

   • POST /v1/actions/contact_merge: Merge two contacts
   • POST /v1/companies: Create a company
   • PATCH /v1/companies/{company_id}: Update a company
   • POST /v1/contacts: Create a contact
   • PATCH /v1/contacts/{contact_id}: Update a contact
   • DELETE /v1/contacts/{contact_id}/avatar: Remove a contact's avatar
   • POST /v1/contacts/{contact_id}/contact_inboxes: Link a contact to an inbox
   • POST /v1/contacts/{contact_id}/destroy_custom_attributes: Remove custom attributes from a contact
   • POST /v1/contacts/{contact_id}/labels: Set a contact's labels
   • POST /v1/contacts/{contact_id}/notes: Create a note
   • PATCH /v1/contacts/{contact_id}/notes/{note_id}: Update a note
   • DELETE /v1/contacts/{contact_id}/notes/{note_id}: Delete a note

   Example:

   curl -X POST "https://api.clomni.ai/v1/contacts" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"name": "Leyla Hasanova", "email": "[email protected]", "phone_number": "+994501234567", "identifier": "crm-10422", "custom_attributes": {"customer_tier": "gold"}}'

   curl -X PATCH "https://api.clomni.ai/v1/contacts/981" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"custom_attributes": {"customer_tier": "platinum"}}'

4. 4

   Import contacts (contacts:import)

   Bulk imports contacts from a CSV file: the file goes as multipart/form-data in the import_file field and the import runs in the background. To create contacts one by one, contacts:write is enough.

   • Risk: medium.
   • Review: goes through review. Say exactly which data you use with it, when and why.
   • Also grants: nothing else.

   Endpoints:

   • POST /v1/contacts/import: Import contacts from a CSV file

   Example:

   curl -X POST "https://api.clomni.ai/v1/contacts/import" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -F "[email protected]"

5. 5

   Delete contacts (contacts:delete)

   Deletes a contact together with its conversations; it cannot be undone. Deleting a company also uses this scope.

   • Risk: high.
   • Review: goes through review and gets a closer look. A detailed explanation and a short video of the feature are needed; the target is 2 working days.
   • Also grants: nothing else.

   Endpoints:

   • DELETE /v1/companies/{company_id}: Delete a company
   • DELETE /v1/contacts/{contact_id}: Delete a contact

   Example:

   curl -X DELETE "https://api.clomni.ai/v1/contacts/981" \
     -H "Authorization: Bearer clomni_pat_xxx"

6. 6

   Read labels (labels:read)

   Reads the list of labels. For showing conversation and contact labels and building filters.

   • Risk: low.
   • Review: goes through review; low risk scopes are looked at quickly.
   • Also grants: nothing else.

   Endpoints:

   • GET /v1/labels: List labels
   • GET /v1/labels/{label_id}: Get a label

   Example:

   curl "https://api.clomni.ai/v1/labels" \
     -H "Authorization: Bearer clomni_pat_xxx"

7. 7

   Edit labels (labels:write)

   Creates, changes and deletes labels. Putting a label on a conversation or a contact is not this scope: that needs conversations:write or contacts:write.

   • Risk: low.
   • Review: goes through review; low risk scopes are looked at quickly.
   • Also grants: labels:read.

   Endpoints:

   • POST /v1/labels: Create a label
   • PATCH /v1/labels/{label_id}: Update a label
   • DELETE /v1/labels/{label_id}: Delete a label

   Example:

   curl -X POST "https://api.clomni.ai/v1/labels" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"title": "vip", "description": "Key customers", "color": "#ff9f1c", "show_on_sidebar": true}'

8. 8

   Read canned responses (canned_responses:read)

   Reads canned responses: short code and text. For offering agents canned responses in your own dashboard.

   • Risk: low.
   • Review: goes through review; low risk scopes are looked at quickly.
   • Also grants: nothing else.

   Endpoints:

   • GET /v1/canned_responses: List canned responses

   Example:

   curl "https://api.clomni.ai/v1/canned_responses" \
     -H "Authorization: Bearer clomni_pat_xxx"

9. 9

   Edit canned responses (canned_responses:write)

   Creates, changes and deletes canned responses. For example, keeping them up to date from your own knowledge system.

   • Risk: medium.
   • Review: goes through review. Say exactly which data you use with it, when and why.
   • Also grants: canned_responses:read.

   Endpoints:

   • POST /v1/canned_responses: Create a canned response
   • PATCH /v1/canned_responses/{canned_response_id}: Update a canned response
   • DELETE /v1/canned_responses/{canned_response_id}: Delete a canned response

   Example:

   curl -X POST "https://api.clomni.ai/v1/canned_responses" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"short_code": "hello", "content": "Hello! How can we help you?"}'

10. 10

    Read custom attributes (custom_attributes:read)

    Reads custom attribute definitions: key, name, type, allowed values, whether it is a contact or a conversation field. The values themselves come in the contact and conversation objects.

    • Risk: low.
    • Review: goes through review; low risk scopes are looked at quickly.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/custom_attribute_definitions: List custom attribute definitions
    • GET /v1/custom_attribute_definitions/{custom_attribute_definition_id}: Get a custom attribute definition

    Example:

    curl "https://api.clomni.ai/v1/custom_attribute_definitions?attribute_model=contact_attribute" \
      -H "Authorization: Bearer clomni_pat_xxx"

11. 11

    Edit custom attributes (custom_attributes:write)

    Creates, changes and deletes custom attributes. For example, adding a key in Clomni for a field from your CRM.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: custom_attributes:read.

    Endpoints:

    • POST /v1/custom_attribute_definitions: Create a custom attribute definition
    • PATCH /v1/custom_attribute_definitions/{custom_attribute_definition_id}: Update a custom attribute definition
    • DELETE /v1/custom_attribute_definitions/{custom_attribute_definition_id}: Delete a custom attribute definition

    Example:

    curl -X POST "https://api.clomni.ai/v1/custom_attribute_definitions" \
      -H "Authorization: Bearer clomni_pat_xxx" \
      -H "Content-Type: application/json" \
      -d '{"attribute_display_name": "Customer tier", "attribute_key": "customer_tier", "attribute_display_type": "list", "attribute_values": ["silver", "gold", "platinum"], "attribute_model": "contact_attribute"}'

12. 12

    About companies

    The company endpoints (/v1/companies) open with the contacts:* scopes and stay in the catalogue. The Companies section, however, is no longer in the dashboard since 5 November 2026, so do not build new integrations on it. Keeping company details in a contact custom attribute is safer.

13. 13

    Related articles

    • Which scopes you need: scopes and endpoints by what you want to do
    • Recipe: sync contacts with your CRM
    • Using Developer API endpoints: examples, pagination, idempotency