Skip to Content

Client APIs

Overview

Manage contacts and import contacts data.

A contact is a person or entity that represents a client (Customer). You can manage contacts directly from the Contacts page.

Entity properties

PropertyTypeDescription
workspaceIdnumber

The workspace ID.

idstring

The contact ID.

namestring

The contact first name.

surnamestring

The contact surname.

phonestring

The contact phone number.

emailstring

The contact email.

addressstring

The contact address.

codestring

The contact code, you can use it to identify the contact in your system.

citystring

The contact city.

countrystring

The contact country.

avatarUrlstring

Profile picture URL from the external channel, when available at contact creation.

externalClientIdstring

The external contact ID (For WhatsApp it can be either the phone number or the BSUID).

tagsstring[]

The contact tags.

stageIdstring

The contact stage ID.

defaultAgentIdstring

The default agent ID used for auto-assignment.

createdAtDateTime

The created timestamp.

deletedAtDateTime

The archived timestamp.

archivedBystring

The user id or SYSTEM that archived the contact.

blacklistedAtDateTime

The timestamp when the contact was blacklisted (blocked). Empty when the contact isn't blacklisted.

blacklistedBystring

The ID of the user or agent who blacklisted the contact.

whatsappBsuidstring

The Meta business-scoped user ID (BSUID) of the contact. It stays the same when the contact adopts a WhatsApp username and stops sharing a phone number.

whatsappUsernamestring

The contact's WhatsApp username, when they have adopted one. It is a display value and can change over time.

Fields populated at NEW_CLIENT (per channel)

Contact fields are set once at first creation from the inbound message / provider profile. Later inbound messages do not backfill empty fields. Manual or API edits (patchClient / putClient) fire CLIENT_UPDATED.

Legend: ✓ usually populated · ~ sometimes · — not auto-populated by that channel.

FieldWhatsAppWA GupshupFacebookInstagramTelegram
name✓ (profile name)✓✓✓ (display name or username)✓ (first_name)
surname✓ (parsed from profile)~✓—~ (may be empty)
phone✓ if E.164 sender; — for BSUID-only✓———
email—————
country✓ (from phone / BSUID / locale hints)✓~ (from Meta locale, e.g. en_US → US)——
city / address / code—————
avatarUrl——✓ when profile fetch succeeds✓✓ when photo available
externalClientId✓ (phone or BSUID)✓✓ (PSID)✓ (IGSID)✓ (Telegram user id)

NEW_CLIENT also includes integrationId and integrationType (channel context). See Webhooks.

UI guidance: show fields that are usually populated for that channel; hide or defer empty ones (e.g. hide phone/email for Instagram leads).

List Contacts API

List the contacts in the workspace. Next are the available filters to list the contacts.

This endpoint supports pagination. See Pagination for more information.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

conversationIdstring

Conversation ID filter.

emailstring

Filter by the email.

namestring

Name filter.

surnamestring

Surname filter.

codestring

Code filter.

citystring

City filter.

countrystring

Country filter.

phonestring

Filter by the client phone number.

externalClientIdstring

External client ID filter.

tagsstring[]

Filter by the tags.

stageIdstring

Filter by the stage ID.

isDeletedboolean

Include archived contacts only when true.

isBlacklistedboolean

Return only blacklisted contacts when true, archived ones included (isDeleted is ignored). Blacklisted contacts are excluded when false or omitted.

activeInLastDaysnumber

Return only contacts who opened a conversation in the last X days.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query clients($input: ClientsInput!) { clients(input: $input) { nodes { id name surname phone externalClientId createdAt } pageInfo { hasNextPage endCursor count } } } input ClientsInput { workspaceId: Int! # Workspace ID. conversationId: String # Conversation ID filter. email: String # Email filter. name: String # Name filter. surname: String # Surname filter. code: String # Code filter. city: String # City filter. country: String # Country filter. phone: String # Phone filter. externalClientId: String # External client ID filter. tags: [String!] # Tags filter. stageId: String # Stage filter. isDeleted: Boolean # Include deleted clients only when true. isBlacklisted: Boolean # Only blacklisted clients when true; excluded otherwise. activeInLastDays: Int # Clients who opened a conversation in the last X days. }

The query above returns JSON structured like this:

{ "data": { "clients": { "nodes": [ { "id": "client_123", "name": "Omar", "surname": "Khalil", "phone": "12025550123", "externalClientId": "12025550123", "createdAt": "2026-03-16T10:15:00.000Z" } ], "pageInfo": { "hasNextPage": false, "endCursor": "2026-03-16T10:15:00.000Z", "count": 1 } } } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"clients","variables":{"input":{"workspaceId":12,"email":"[email protected]","name":"Omar","surname":"Khalil","code":"CUST-1042","city":"Washington","country":"US","phone":"12025550123","externalClientId":"12025550123","tags":["vip"],"stageId":"stage_123","activeInLastDays":30}},"query":"query clients($input: ClientsInput!) {\n clients(input: $input) {\n nodes {\n id\n name\n surname\n phone\n externalClientId\n createdAt\n }\n pageInfo {\n hasNextPage\n endCursor\n count\n }\n }\n}"}'

Create Client API

Create a client.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

emailstring

Client email.

namestring

The name.

surnamestring

Client surname.

phonestring

The client phone number.

codestring

Client code.

citystring

Client city.

countrystring

Client country.

addressstring

Client address.

stagestring

The name of the client stage to put the client in. If the workspace has no client stage with exactly this name (case-sensitive), one is created: it then appears among the workspace's client stages, and in the Tags API as type clientStage. Names starting with bc: are rejected.

defaultAgentIdstring

Default agent ID for auto-assignment.

externalClientIdstring

Required. External client ID.

tagsstring[]

The tags.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation createClient($input: ClientCreateInput!) { createClient(input: $input) { id name surname phone externalClientId createdAt } } input ClientCreateInput { workspaceId: Int! # Workspace ID. email: String # Client email. name: String # Client first name. surname: String # Client surname. phone: String # Client phone. code: String # Client code. city: String # Client city. country: String # Client country. address: String # Client address. stage: String # Client stage name. defaultAgentId: ID # Default agent ID for auto-assignment. externalClientId: String! # External client ID. tags: [String!] # Client tags. }

The mutation above returns JSON structured like this:

{ "data": { "createClient": { "id": "client_123", "name": "Omar", "surname": "Khalil", "phone": "12025550123", "externalClientId": "12025550123", "createdAt": "2026-03-16T10:15:00.000Z" } } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"createClient","variables":{"input":{"workspaceId":12,"email":"[email protected]","name":"Omar","surname":"Khalil","phone":"12025550123","code":"CUST-1042","city":"Washington","country":"US","address":"1600 Pennsylvania Ave NW","stage":"Qualified","defaultAgentId":"agent_123","externalClientId":"12025550123","tags":["vip"]}},"query":"mutation createClient($input: ClientCreateInput!) {\n createClient(input: $input) {\n id\n name\n surname\n phone\n externalClientId\n createdAt\n }\n}"}'

Put Client API

Put a client (update if exists, create if not).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

emailstring

The contact email.

namestring

The name.

surnamestring

The contact surname.

phonestring

The contact phone number.

codestring

The contact code.

citystring

The contact city.

countrystring

The contact country.

addressstring

The contact address.

defaultAgentIdstring

Default agent ID for auto-assignment.

externalClientIdstring

Required. External client ID.

tagsstring[]

The tags.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation putClient($input: ClientPutInput!) { putClient(input: $input) { id name surname phone externalClientId createdAt } } input ClientPutInput { workspaceId: Int! # Workspace ID. email: String # Client email. name: String # Client first name. surname: String # Client surname. phone: String # Client phone. code: String # Client code. city: String # Client city. country: String # Client country. address: String # Client address. defaultAgentId: ID # Default agent ID for auto-assignment. externalClientId: String! # External client ID. tags: [String!] # Client tags. }

The mutation above returns JSON structured like this:

{ "data": { "putClient": { "id": "client_123", "name": "Omar", "surname": "Khalil", "phone": "12025550123", "externalClientId": "12025550123", "createdAt": "2026-03-16T10:15:00.000Z" } } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"putClient","variables":{"input":{"workspaceId":12,"email":"[email protected]","name":"Omar","surname":"Khalil","phone":"12025550123","code":"CUST-1042","city":"Washington","country":"US","address":"1600 Pennsylvania Ave NW","defaultAgentId":"agent_123","externalClientId":"12025550123","tags":["vip"]}},"query":"mutation putClient($input: ClientPutInput!) {\n putClient(input: $input) {\n id\n name\n surname\n phone\n externalClientId\n createdAt\n }\n}"}'

Validate Bulk Import Contacts API

Validate a bulk import contacts CSV file before importing.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

fileNamestring

Required. CSV file name in blob storage.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query validateBulkImportContacts($input: ValidateBulkImportContactsInput!) { validateBulkImportContacts(input: $input) { totalRows validRows invalidRows errors { row message } } } input ValidateBulkImportContactsInput { workspaceId: Int! # Workspace ID. fileName: String! # CSV file name in blob storage. }

The query above returns JSON structured like this:

{ "data": { "validateBulkImportContacts": { "totalRows": 10, "validRows": 8, "invalidRows": 2, "errors": [ { "row": 4, "message": "Phone number is invalid" } ] } } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"validateBulkImportContacts","variables":{"input":{"workspaceId":12,"fileName":"contacts.csv"}},"query":"query validateBulkImportContacts($input: ValidateBulkImportContactsInput!) {\n validateBulkImportContacts(input: $input) {\n totalRows\n validRows\n invalidRows\n errors {\n row\n message\n }\n }\n}"}'

Bulk Import Contacts API

Bulk import contacts from a CSV file stored in blob storage. Returns a job ID to track progress.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

fileNamestring

Required. CSV file name in blob storage.

skipErrorsboolean

Skip invalid rows and continue.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation bulkImportContacts($input: BulkImportContactsInput!) { bulkImportContacts(input: $input) { jobId } } input BulkImportContactsInput { workspaceId: Int! # Workspace ID. fileName: String! # CSV file name in blob storage. skipErrors: Boolean # Skip invalid rows and continue. }

The mutation above returns JSON structured like this:

{ "data": { "bulkImportContacts": { "jobId": "job_123" } } }
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"bulkImportContacts","variables":{"input":{"workspaceId":12,"fileName":"contacts.csv","skipErrors":true}},"query":"mutation bulkImportContacts($input: BulkImportContactsInput!) {\n bulkImportContacts(input: $input) {\n jobId\n }\n}"}'

Get Client API

Get a single client by ID. Archived and blacklisted clients are returned too: check deletedAt and blacklistedAt to tell them apart.

Access: Any role on the workspace. Callers without MANAGE_CLIENTS (the Agent role) receive email, phone and externalClientId masked. Works with workspace API keys and agent API keys, which both receive unmasked data.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The client ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query client($input: ClientInput!) { client(input: $input) { id name surname phone email externalClientId tags stageId defaultAgentId createdAt deletedAt blacklistedAt } } input ClientInput { workspaceId: Int! # Workspace ID. id: ID! # Client ID. }

The query above returns JSON structured like this:

{ "data": { "client": { "id": "client_123", "name": "John", "surname": "Doe", "phone": "12025550123", "email": "[email protected]", "externalClientId": "12025550123", "tags": [ "lead", "vip" ], "stageId": "stage_123", "defaultAgentId": "agent_123", "createdAt": "2026-10-17T09:30:00.000Z", "deletedAt": null, "blacklistedAt": null } } }

Masking. When the caller’s role does not have MANAGE_CLIENTS (the Agent role), these fields are masked in the response:

FieldStored valueReturned value
email[email protected]jo******@example.com
phone1202555012312******123
externalClientId1202555012312******123

The email keeps its first two characters and the domain. For phone and externalClientId, digits 3 to 8 of the first run of 11 consecutive digits are replaced with ******; a value with fewer than 11 consecutive digits is returned unchanged. Other fields are never masked. The same rule applies to List Contacts API.

ErrorCause
Target client does not existNo client with this ID in the workspace.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"client","variables":{"input":{"workspaceId":12,"id":"client_123"}},"query":"query client($input: ClientInput!) {\n client(input: $input) {\n id\n name\n surname\n phone\n email\n externalClientId\n tags\n stageId\n defaultAgentId\n createdAt\n deletedAt\n blacklistedAt\n }\n}"}'

Get Client By Phone API

Find a client by its exact phone number. Archived clients are not returned; blacklisted clients are. Phone numbers are stored as digits only, without + or a leading 00, so send them the same way.

Access: MANAGE_CLIENTS (Owner, Admin, Manager, Agent+). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

phonestring

Required. The phone number, digits only (for example 12025550123). It must match the stored value exactly.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query clientByPhone($input: ClientByPhoneInput!) { clientByPhone(input: $input) { id name surname phone externalClientId tags createdAt } } input ClientByPhoneInput { workspaceId: Int! # Workspace ID. phone: String! # Phone number, digits only. }

The query above returns JSON structured like this:

{ "data": { "clientByPhone": { "id": "client_123", "name": "John", "surname": "Doe", "phone": "12025550123", "externalClientId": "12025550123", "tags": [ "lead", "vip" ], "createdAt": "2026-10-17T09:30:00.000Z" } } }

Unlike Get Client API, contact details are never masked here: callers without MANAGE_CLIENTS are rejected instead. If several non-archived clients share the phone number, one of them is returned.

ErrorCause
Target client does not existNo non-archived client with this exact phone number in the workspace.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"clientByPhone","variables":{"input":{"workspaceId":12,"phone":"12025550123"}},"query":"query clientByPhone($input: ClientByPhoneInput!) {\n clientByPhone(input: $input) {\n id\n name\n surname\n phone\n externalClientId\n tags\n createdAt\n }\n}"}'

Patch Client API

Update some fields of a client. Only the fields you send change; send null to clear a field. Fires the CLIENT_UPDATED webhook event.

Access: MANAGE_CLIENTS (Owner, Admin, Manager, Agent+). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The client ID.

namestring

The first name.

surnamestring

The surname.

emailstring

The email.

phonestring

The phone number, digits only and not starting with 00. Ignored without an error when the client has a conversation on a WhatsApp or WA Gupshup Channel.

addressstring

The address.

codestring

Your own code for the client.

citystring

The city.

countrystring

ISO 3166-1 alpha-2 country code, for example US (case-insensitive).

stagestring

The name of the client stage to put the client in. If the workspace has no client stage with exactly this name (case-sensitive), one is created: it then appears among the workspace's client stages, and in the Tags API as type clientStage. Names starting with bc: are rejected. Send null or an empty string to remove the client's stage.

defaultAgentIdstring

Agent that new conversations started by this client are auto-assigned to, when the Channel has auto assignment enabled. Send null or an empty string to remove it.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation patchClient($input: ClientPatchInput!) { patchClient(input: $input) { id name surname email country stageId defaultAgentId } } input ClientPatchInput { workspaceId: Int! # Workspace ID. id: ID! # Client ID. stage: String # Stage name; null or "" removes the stage. email: String # Email. name: String # First name. surname: String # Surname. code: String # Your own client code. city: String # City. country: String # ISO 3166-1 alpha-2 code. phone: String # Digits only, not starting with 00. address: String # Address. defaultAgentId: ID # Agent for auto-assignment; null or "" removes it. }

The mutation above returns JSON structured like this:

{ "data": { "patchClient": { "id": "client_123", "name": "John", "surname": "Doe", "email": "[email protected]", "country": "US", "stageId": "stage_123", "defaultAgentId": "agent_123" } } }

Archived clients cannot be patched: restore them with Undelete Client API first. Patching an archived client, or an ID that does not exist in the workspace, fails with a database record-not-found error. The phone of a client that has a WhatsApp or WA Gupshup conversation is left unchanged, because it identifies the contact on that Channel.

ErrorCause
Invalid phone number: <phone>, it should contain only numbers and not start with 00phone has a non-digit character (such as +) or starts with 00.
Invalid country code: <country>country is not an ISO 3166-1 alpha-2 code.
Target agent does not existdefaultAgentId is not an active agent of the workspace.
Tags starting with "bc:" are reserved and cannot be created or appliedstage starts with bc:.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"patchClient","variables":{"input":{"workspaceId":12,"id":"client_123","name":"John","surname":"Doe","email":"[email protected]","country":"US","stage":"Qualified","defaultAgentId":"agent_123"}},"query":"mutation patchClient($input: ClientPatchInput!) {\n patchClient(input: $input) {\n id\n name\n surname\n email\n country\n stageId\n defaultAgentId\n }\n}"}'

Tag Client API

Add a tag to a client. A new tag is also saved to the workspace’s client tags (see Tag APIs). Fires the CLIENT_UPDATED webhook event.

Access: Any role on the workspace. Callers without MANAGE_CLIENTS (the Agent role) receive email, phone and externalClientId masked. Works with workspace API keys and agent API keys, which both receive unmasked data.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

clientIdstring

Required. The client ID.

tagstring

Required. The tag to add. Tags starting with bc: are reserved.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation tagClient($input: ClientTagInput!) { tagClient(input: $input) { id tags } } input ClientTagInput { workspaceId: Int! # Workspace ID. clientId: ID! # Client ID. tag: String! # Tag to add or remove. }

The mutation above returns JSON structured like this:

{ "data": { "tagClient": { "id": "client_123", "tags": [ "lead", "vip" ] } } }

The tag is appended to the end of tags.

ErrorCause
Tags starting with "bc:" are reserved and cannot be created or appliedtag starts with bc:.
Target client does not existNo client with this ID in the workspace.
Target client is already tagged with <tag>The client already has this tag.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"tagClient","variables":{"input":{"workspaceId":12,"clientId":"client_123","tag":"vip"}},"query":"mutation tagClient($input: ClientTagInput!) {\n tagClient(input: $input) {\n id\n tags\n }\n}"}'

Untag Client API

Remove a tag from a client. Removing a tag the client does not have is not an error. Fires the CLIENT_UPDATED webhook event, even when nothing changed.

Access: Any role on the workspace. Callers without MANAGE_CLIENTS (the Agent role) receive email, phone and externalClientId masked. Works with workspace API keys and agent API keys, which both receive unmasked data.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

clientIdstring

Required. The client ID.

tagstring

Required. The tag to remove.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation untagClient($input: ClientTagInput!) { untagClient(input: $input) { id tags } } input ClientTagInput { workspaceId: Int! # Workspace ID. clientId: ID! # Client ID. tag: String! # Tag to add or remove. }

The mutation above returns JSON structured like this:

{ "data": { "untagClient": { "id": "client_123", "tags": [ "vip" ] } } }

Unlike Tag Client API, any tag can be removed, including reserved tags that start with bc:. The tag stays in the workspace’s tag list.

ErrorCause
Target client does not existNo client with this ID in the workspace.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"untagClient","variables":{"input":{"workspaceId":12,"clientId":"client_123","tag":"lead"}},"query":"mutation untagClient($input: ClientTagInput!) {\n untagClient(input: $input) {\n id\n tags\n }\n}"}'

Delete Client API

Archive a client (soft delete). The client, its conversations and its messages are kept: deletedAt is set to the current time and archivedBy to the caller’s ID (user, agent or API key). Restore it with Undelete Client API, or remove it for good with Bulk Permanent Delete Clients API. No webhook event fires.

Access: MANAGE_CLIENTS (Owner, Admin, Manager, Agent+). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The client ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation deleteClient($input: ClientInput!) { deleteClient(input: $input) { id deletedAt archivedBy } } input ClientInput { workspaceId: Int! # Workspace ID. id: ID! # Client ID. }

The mutation above returns JSON structured like this:

{ "data": { "deleteClient": { "id": "client_123", "deletedAt": "2026-10-17T09:30:00.000Z", "archivedBy": "user_123" } } }

An archived client:

Archiving an already archived client refreshes deletedAt and archivedBy. An ID that does not exist in the workspace fails with a database record-not-found error (not Target client does not exist).

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"deleteClient","variables":{"input":{"workspaceId":12,"id":"client_123"}},"query":"mutation deleteClient($input: ClientInput!) {\n deleteClient(input: $input) {\n id\n deletedAt\n archivedBy\n }\n}"}'

Delete Client By External ID API

Archive (soft delete) the client with this externalClientId, the channel-side identifier from Entity properties (for WhatsApp, the phone number or the BSUID). The effects are the same as Delete Client API. No webhook event fires.

Access: MANAGE_CLIENTS (Owner, Admin, Manager, Agent+). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

externalClientIdstring

Required. The external client ID, matched exactly. For WhatsApp, the phone number in digits only (for example 12025550123) or the BSUID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation deleteClientByExternalId($input: ClientDeleteByExternalIdInput!) { deleteClientByExternalId(input: $input) { id externalClientId deletedAt archivedBy } } input ClientDeleteByExternalIdInput { workspaceId: Int! # Workspace ID. externalClientId: String! # External client ID (channel-side identifier). }

The mutation above returns JSON structured like this:

{ "data": { "deleteClientByExternalId": { "id": "client_123", "externalClientId": "12025550123", "deletedAt": "2026-10-17T09:30:00.000Z", "archivedBy": "user_123" } } }
ErrorCause
Target client does not existNo non-archived client with this externalClientId in the workspace. A client that is already archived returns this error too.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"deleteClientByExternalId","variables":{"input":{"workspaceId":12,"externalClientId":"12025550123"}},"query":"mutation deleteClientByExternalId($input: ClientDeleteByExternalIdInput!) {\n deleteClientByExternalId(input: $input) {\n id\n externalClientId\n deletedAt\n archivedBy\n }\n}"}'

Undelete Client API

Restore an archived client: deletedAt and archivedBy are cleared and the client shows up again in List Contacts API and broadcast audiences, unless it is blacklisted. Fires the CLIENT_UPDATED webhook event.

Access: MANAGE_CLIENTS (Owner, Admin, Manager, Agent+). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The client ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation undeleteClient($input: ClientInput!) { undeleteClient(input: $input) { id name deletedAt archivedBy } } input ClientInput { workspaceId: Int! # Workspace ID. id: ID! # Client ID. }

The mutation above returns JSON structured like this:

{ "data": { "undeleteClient": { "id": "client_123", "name": "John", "deletedAt": null, "archivedBy": null } } }
ErrorCause
Target client does not exist or is not deletedNo client with this ID in the workspace, or the client is not archived.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"undeleteClient","variables":{"input":{"workspaceId":12,"id":"client_123"}},"query":"mutation undeleteClient($input: ClientInput!) {\n undeleteClient(input: $input) {\n id\n name\n deletedAt\n archivedBy\n }\n}"}'

Undelete Client By External ID API

Restore the archived client with this externalClientId. The effects are the same as Undelete Client API. Fires the CLIENT_UPDATED webhook event.

Access: MANAGE_CLIENTS (Owner, Admin, Manager, Agent+). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

externalClientIdstring

Required. The external client ID, matched exactly. For WhatsApp, the phone number in digits only or the BSUID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation undeleteClientByExternalId($input: ClientDeleteByExternalIdInput!) { undeleteClientByExternalId(input: $input) { id externalClientId deletedAt } } input ClientDeleteByExternalIdInput { workspaceId: Int! # Workspace ID. externalClientId: String! # External client ID (channel-side identifier). }

The mutation above returns JSON structured like this:

{ "data": { "undeleteClientByExternalId": { "id": "client_123", "externalClientId": "12025550123", "deletedAt": null } } }

If more than one archived client has this externalClientId, only one of them is restored.

ErrorCause
Target client does not exist or is not deletedNo archived client with this externalClientId in the workspace.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"undeleteClientByExternalId","variables":{"input":{"workspaceId":12,"externalClientId":"12025550123"}},"query":"mutation undeleteClientByExternalId($input: ClientDeleteByExternalIdInput!) {\n undeleteClientByExternalId(input: $input) {\n id\n externalClientId\n deletedAt\n }\n}"}'

Blacklist Client API

Blacklist (block) a client: blacklistedAt is set to the current time and blacklistedBy to the caller’s ID. Fires the CLIENT_UPDATED webhook event.

Access: MANAGE_CLIENTS (Owner, Admin, Manager, Agent+). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The client ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation blacklistClient($input: ClientInput!) { blacklistClient(input: $input) { id blacklistedAt blacklistedBy } } input ClientInput { workspaceId: Int! # Workspace ID. id: ID! # Client ID. }

The mutation above returns JSON structured like this:

{ "data": { "blacklistClient": { "id": "client_123", "blacklistedAt": "2026-10-17T09:30:00.000Z", "blacklistedBy": "user_123" } } }

While a client is blacklisted:

  • its inbound messages are dropped: no conversation or message is created;
  • it is left out of broadcast audiences;
  • Start Conv API fails with Cannot start conversation with a blacklisted contact;
  • it is hidden from List Contacts API unless you send isBlacklisted: true.

Get Client API and Get Client By Phone API still return it. Blacklisting an already blacklisted client refreshes blacklistedAt and blacklistedBy. An ID that does not exist in the workspace fails with a database record-not-found error (not Target client does not exist).

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"blacklistClient","variables":{"input":{"workspaceId":12,"id":"client_123"}},"query":"mutation blacklistClient($input: ClientInput!) {\n blacklistClient(input: $input) {\n id\n blacklistedAt\n blacklistedBy\n }\n}"}'

Unblacklist Client API

Remove a client from the blacklist: blacklistedAt and blacklistedBy are cleared and the client is handled normally again. Messages dropped while it was blacklisted are not recovered. Fires the CLIENT_UPDATED webhook event.

Access: MANAGE_CLIENTS (Owner, Admin, Manager, Agent+). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The client ID.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation unblacklistClient($input: ClientInput!) { unblacklistClient(input: $input) { id blacklistedAt blacklistedBy } } input ClientInput { workspaceId: Int! # Workspace ID. id: ID! # Client ID. }

The mutation above returns JSON structured like this:

{ "data": { "unblacklistClient": { "id": "client_123", "blacklistedAt": null, "blacklistedBy": null } } }
ErrorCause
Target client does not exist or is not blacklistedNo client with this ID in the workspace, or the client is not blacklisted.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"unblacklistClient","variables":{"input":{"workspaceId":12,"id":"client_123"}},"query":"mutation unblacklistClient($input: ClientInput!) {\n unblacklistClient(input: $input) {\n id\n blacklistedAt\n blacklistedBy\n }\n}"}'

Bulk Delete Clients API

Archive (soft delete) several clients at once. Each client gets the same changes as with Delete Client API. No webhook event fires.

Access: MANAGE_CLIENTS (Owner, Admin, Manager, Agent+). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idsstring[]

Required. The IDs of the clients to archive.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation bulkDeleteClients($input: BulkPermanentDeleteClientsInput!) { bulkDeleteClients(input: $input) { deletedCount } } input BulkPermanentDeleteClientsInput { workspaceId: Int! # Workspace ID. ids: [ID!]! # Client IDs. }

The mutation above returns JSON structured like this:

{ "data": { "bulkDeleteClients": { "deletedCount": 2 } } }

All bulk client operations take BulkPermanentDeleteClientsInput and return BulkPermanentDeleteClientsResult. Despite the type names, only Bulk Permanent Delete Clients API deletes anything permanently. deletedCount is the number of clients the operation changed, whatever the operation.

Here, clients that are already archived are skipped and not counted. IDs that do not exist in the workspace are skipped without an error, and an empty ids list returns 0. Core does not cap the number of IDs per call.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"bulkDeleteClients","variables":{"input":{"workspaceId":12,"ids":["client_123","client_456"]}},"query":"mutation bulkDeleteClients($input: BulkPermanentDeleteClientsInput!) {\n bulkDeleteClients(input: $input) {\n deletedCount\n }\n}"}'

Bulk Undelete Clients API

Restore several archived clients at once: deletedAt and archivedBy are cleared. Unlike Undelete Client API, no webhook event fires.

Access: MANAGE_CLIENTS (Owner, Admin, Manager, Agent+). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idsstring[]

Required. The IDs of the clients to restore.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation bulkUndeleteClients($input: BulkPermanentDeleteClientsInput!) { bulkUndeleteClients(input: $input) { deletedCount } } input BulkPermanentDeleteClientsInput { workspaceId: Int! # Workspace ID. ids: [ID!]! # Client IDs. }

The mutation above returns JSON structured like this:

{ "data": { "bulkUndeleteClients": { "deletedCount": 2 } } }

deletedCount is the number of clients restored. Clients that are not archived are skipped and not counted. IDs that do not exist in the workspace are skipped without an error, and an empty ids list returns 0. Core does not cap the number of IDs per call.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"bulkUndeleteClients","variables":{"input":{"workspaceId":12,"ids":["client_123","client_456"]}},"query":"mutation bulkUndeleteClients($input: BulkPermanentDeleteClientsInput!) {\n bulkUndeleteClients(input: $input) {\n deletedCount\n }\n}"}'

Bulk Blacklist Clients API

Blacklist several clients at once: blacklistedAt is set to the current time and blacklistedBy to the caller’s ID. The effects are the same as Blacklist Client API, but no webhook event fires.

Access: MANAGE_CLIENTS (Owner, Admin, Manager, Agent+). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idsstring[]

Required. The IDs of the clients to blacklist.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation bulkBlacklistClients($input: BulkPermanentDeleteClientsInput!) { bulkBlacklistClients(input: $input) { deletedCount } } input BulkPermanentDeleteClientsInput { workspaceId: Int! # Workspace ID. ids: [ID!]! # Client IDs. }

The mutation above returns JSON structured like this:

{ "data": { "bulkBlacklistClients": { "deletedCount": 2 } } }

deletedCount is the number of clients blacklisted. Clients that are already blacklisted are skipped and not counted. IDs that do not exist in the workspace are skipped without an error, and an empty ids list returns 0. Core does not cap the number of IDs per call.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"bulkBlacklistClients","variables":{"input":{"workspaceId":12,"ids":["client_123","client_456"]}},"query":"mutation bulkBlacklistClients($input: BulkPermanentDeleteClientsInput!) {\n bulkBlacklistClients(input: $input) {\n deletedCount\n }\n}"}'

Bulk Unblacklist Clients API

Remove several clients from the blacklist at once: blacklistedAt and blacklistedBy are cleared. Unlike Unblacklist Client API, no webhook event fires.

Access: MANAGE_CLIENTS (Owner, Admin, Manager, Agent+). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idsstring[]

Required. The IDs of the clients to remove from the blacklist.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation bulkUnblacklistClients($input: BulkPermanentDeleteClientsInput!) { bulkUnblacklistClients(input: $input) { deletedCount } } input BulkPermanentDeleteClientsInput { workspaceId: Int! # Workspace ID. ids: [ID!]! # Client IDs. }

The mutation above returns JSON structured like this:

{ "data": { "bulkUnblacklistClients": { "deletedCount": 2 } } }

deletedCount is the number of clients removed from the blacklist. Clients that are not blacklisted are skipped and not counted. IDs that do not exist in the workspace are skipped without an error, and an empty ids list returns 0. Core does not cap the number of IDs per call.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"bulkUnblacklistClients","variables":{"input":{"workspaceId":12,"ids":["client_123","client_456"]}},"query":"mutation bulkUnblacklistClients($input: BulkPermanentDeleteClientsInput!) {\n bulkUnblacklistClients(input: $input) {\n deletedCount\n }\n}"}'

Bulk Permanent Delete Clients API

Permanently delete clients by ID, together with all their conversations and messages. Archived and blacklisted clients are deleted too. No webhook event fires.

Access: MANAGE_WORKSPACE (Owner, Admin). Works with workspace API keys. Agent API keys are rejected.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idsstring[]

Required. The IDs of the clients to delete permanently.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation bulkPermanentDeleteClients($input: BulkPermanentDeleteClientsInput!) { bulkPermanentDeleteClients(input: $input) { deletedCount } } input BulkPermanentDeleteClientsInput { workspaceId: Int! # Workspace ID. ids: [ID!]! # Client IDs. }

The mutation above returns JSON structured like this:

{ "data": { "bulkPermanentDeleteClients": { "deletedCount": 2 } } }

This cannot be undone. The clients’ messages and conversations are deleted first, then the clients. To hide a client and keep its history, use Bulk Delete Clients API instead.

deletedCount is the number of clients removed. IDs that do not exist in the workspace are skipped without an error, and an empty ids list returns 0. Core does not cap the number of IDs per call. If a deleted contact writes to the workspace again, a new client is created and NEW_CLIENT fires.

ErrorCause
You do not have permission to access this resource with your current role assignmentThe caller’s role is below Admin, or the request uses an agent API key.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"bulkPermanentDeleteClients","variables":{"input":{"workspaceId":12,"ids":["client_123","client_456"]}},"query":"mutation bulkPermanentDeleteClients($input: BulkPermanentDeleteClientsInput!) {\n bulkPermanentDeleteClients(input: $input) {\n deletedCount\n }\n}"}'

Bulk Permanent Delete Clients By Filter API

Permanently delete every client in the workspace that matches a tag and/or stage filter, together with their conversations and messages. Archived and blacklisted clients that match are deleted too. No webhook event fires.

Access: MANAGE_WORKSPACE (Owner, Admin). Works with workspace API keys. Agent API keys are rejected.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

tagsstring[]

Tags filter. A client matches only when it has all of these tags.

stageIdstring

Stage filter. A client matches only when it is in this stage.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
mutation bulkPermanentDeleteClientsByFilter($input: BulkPermanentDeleteClientsByFilterInput!) { bulkPermanentDeleteClientsByFilter(input: $input) { deletedCount } } input BulkPermanentDeleteClientsByFilterInput { workspaceId: Int! # Workspace ID. tags: [String!] # Clients must have all of these tags. stageId: String # Clients must be in this stage. }

The mutation above returns JSON structured like this:

{ "data": { "bulkPermanentDeleteClientsByFilter": { "deletedCount": 37 } } }

This cannot be undone. Send at least one of tags and stageId; when you send both, a client must match both. List Contacts API is not an exact preview: its tags filter matches clients with any of the tags, and it hides archived and blacklisted clients.

deletedCount is the number of clients removed; it is 0 when nothing matches. If a deleted contact writes to the workspace again, a new client is created and NEW_CLIENT fires.

ErrorCause
Either tags or stageId must be providedNeither tags (non-empty) nor stageId was sent.
You do not have permission to access this resource with your current role assignmentThe caller’s role is below Admin, or the request uses an agent API key.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"bulkPermanentDeleteClientsByFilter","variables":{"input":{"workspaceId":12,"tags":["test-import"],"stageId":"stage_123"}},"query":"mutation bulkPermanentDeleteClientsByFilter($input: BulkPermanentDeleteClientsByFilterInput!) {\n bulkPermanentDeleteClientsByFilter(input: $input) {\n deletedCount\n }\n}"}'

Bulk Import Contacts Job Status API

Get the progress of a job started with Bulk Import Contacts API. Poll it with the returned jobId until status is completed or failed. Returns null when the job is unknown in this workspace or its status has expired (statuses are kept for 2 days after their last update).

Access: MANAGE_CLIENTS (Owner, Admin, Manager, Agent+). Works with workspace API keys and agent API keys.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

jobIdstring

Required. The jobId returned by Bulk Import Contacts API.

Request & Response

POST https://gateway.bcrumbs.net/core/gq
query bulkImportContactsJobStatus($input: BulkImportContactsJobStatusInput!) { bulkImportContactsJobStatus(input: $input) { status processedCount totalCount totalProcessed success errors skipped error startedAt completedAt } } input BulkImportContactsJobStatusInput { workspaceId: Int! # Workspace ID. jobId: String! # Job ID returned by bulkImportContacts. }

The query above returns JSON structured like this:

{ "data": { "bulkImportContactsJobStatus": { "status": "completed", "processedCount": 250, "totalCount": 250, "totalProcessed": 250, "success": 245, "errors": 0, "skipped": 5, "error": null, "startedAt": "2026-10-17T09:30:00.000Z", "completedAt": "2026-10-17T09:31:12.000Z" } } }
statusMeaningFields set
pendingQueued, not started yet.processedCount (0)
processingRows are being imported.startedAt, totalCount (rows in the CSV), processedCount (updated every 100 rows)
completedAll rows were handled.Adds totalProcessed, success, errors, skipped and completedAt
failedThe job stopped, for example because the file could not be read.Adds error (the reason) and completedAt

success counts rows that created a client or updated an existing one (matched by phone as externalClientId). Invalid rows never stop the job: they count as skipped when the import was started with skipErrors: true, and as errors otherwise. Rows for existing clients with nothing to change also count as skipped. Clients created or updated by an import do not fire NEW_CLIENT or CLIENT_UPDATED.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/core/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"bulkImportContactsJobStatus","variables":{"input":{"workspaceId":12,"jobId":"job_123"}},"query":"query bulkImportContactsJobStatus($input: BulkImportContactsJobStatusInput!) {\n bulkImportContactsJobStatus(input: $input) {\n status\n processedCount\n totalCount\n totalProcessed\n success\n errors\n skipped\n error\n startedAt\n completedAt\n }\n}"}'