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
| Property | Type | Description |
|---|---|---|
workspaceId | number | The workspace ID. |
id | string | The contact ID. |
name | string | The contact first name. |
surname | string | The contact surname. |
phone | string | The contact phone number. |
email | string | The contact email. |
address | string | The contact address. |
code | string | The contact code, you can use it to identify the contact in your system. |
city | string | The contact city. |
country | string | The contact country. |
avatarUrl | string | Profile picture URL from the external channel, when available at contact creation. |
externalClientId | string | The external contact ID (For WhatsApp it can be either the phone number or the BSUID). |
tags | string[] | The contact tags. |
stageId | string | The contact stage ID. |
defaultAgentId | string | The default agent ID used for auto-assignment. |
createdAt | DateTime | The created timestamp. |
deletedAt | DateTime | The archived timestamp. |
archivedBy | string | The user id or SYSTEM that archived the contact. |
blacklistedAt | DateTime | The timestamp when the contact was blacklisted (blocked). Empty when the contact isn't blacklisted. |
blacklistedBy | string | The ID of the user or agent who blacklisted the contact. |
whatsappBsuid | string | 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. |
whatsappUsername | string | 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.
| Field | WA Gupshup | Telegram | |||
|---|---|---|---|---|---|
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
conversationId | string | Conversation ID filter. |
email | string | Filter by the email. |
name | string | Name filter. |
surname | string | Surname filter. |
code | string | Code filter. |
city | string | City filter. |
country | string | Country filter. |
phone | string | Filter by the client phone number. |
externalClientId | string | External client ID filter. |
tags | string[] | Filter by the tags. |
stageId | string | Filter by the stage ID. |
isDeleted | boolean | Include archived contacts only when true. |
isBlacklisted | boolean | Return only blacklisted contacts when true, archived ones included ( |
activeInLastDays | number | Return only contacts who opened a conversation in the last X days. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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
}
}
}
}Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
email | string | Client email. |
name | string | The name. |
surname | string | Client surname. |
phone | string | The client phone number. |
code | string | Client code. |
city | string | Client city. |
country | string | Client country. |
address | string | Client address. |
stage | string | 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 |
defaultAgentId | string | Default agent ID for auto-assignment. |
externalClientId | string | Required. External client ID. |
tags | string[] | The tags. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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"
}
}
}Programming language examples
cURL
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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
email | string | The contact email. |
name | string | The name. |
surname | string | The contact surname. |
phone | string | The contact phone number. |
code | string | The contact code. |
city | string | The contact city. |
country | string | The contact country. |
address | string | The contact address. |
defaultAgentId | string | Default agent ID for auto-assignment. |
externalClientId | string | Required. External client ID. |
tags | string[] | The tags. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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"
}
}
}Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
fileName | string | Required. CSV file name in blob storage. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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"
}
]
}
}
}Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
fileName | string | Required. CSV file name in blob storage. |
skipErrors | boolean | Skip invalid rows and continue. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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"
}
}
}Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The client ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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:
| Field | Stored value | Returned value |
|---|---|---|
email | [email protected] | jo******@example.com |
phone | 12025550123 | 12******123 |
externalClientId | 12025550123 | 12******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.
| Error | Cause |
|---|---|
Target client does not exist | No client with this ID in the workspace. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
phone | string | Required. The phone number, digits only (for example |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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.
| Error | Cause |
|---|---|
Target client does not exist | No non-archived client with this exact phone number in the workspace. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The client ID. |
name | string | The first name. |
surname | string | The surname. |
email | string | The email. |
phone | string | The phone number, digits only and not starting with |
address | string | The address. |
code | string | Your own code for the client. |
city | string | The city. |
country | string | ISO 3166-1 alpha-2 country code, for example |
stage | string | 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 |
defaultAgentId | string | Agent that new conversations started by this client are auto-assigned to, when the Channel has auto assignment enabled. Send |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
| Error | Cause |
|---|---|
Invalid phone number: <phone>, it should contain only numbers and not start with 00 | phone 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 exist | defaultAgentId is not an active agent of the workspace. |
Tags starting with "bc:" are reserved and cannot be created or applied | stage starts with bc:. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
clientId | string | Required. The client ID. |
tag | string | Required. The tag to add. Tags starting with |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
| Error | Cause |
|---|---|
Tags starting with "bc:" are reserved and cannot be created or applied | tag starts with bc:. |
Target client does not exist | No client with this ID in the workspace. |
Target client is already tagged with <tag> | The client already has this tag. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
clientId | string | Required. The client ID. |
tag | string | Required. The tag to remove. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
| Error | Cause |
|---|---|
Target client does not exist | No client with this ID in the workspace. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The client ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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:
- is hidden from List Contacts API unless you send
isDeleted: true, and from Get Client By Phone API; - is left out of broadcast audiences;
- is still returned by Get Client API;
- cannot be changed with Patch Client API until it is restored;
- still receives inbound messages. When the
autoUnarchiveOnMessageworkspace setting is on, its next inbound message restores it automatically.
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).
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
externalClientId | string | Required. The external client ID, matched exactly. For WhatsApp, the phone number in digits only (for example |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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"
}
}
}| Error | Cause |
|---|---|
Target client does not exist | No non-archived client with this externalClientId in the workspace. A client that is already archived returns this error too. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The client ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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
}
}
}| Error | Cause |
|---|---|
Target client does not exist or is not deleted | No client with this ID in the workspace, or the client is not archived. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
externalClientId | string | 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/gqmutation 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.
| Error | Cause |
|---|---|
Target client does not exist or is not deleted | No archived client with this externalClientId in the workspace. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The client ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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).
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The client ID. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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
}
}
}| Error | Cause |
|---|---|
Target client does not exist or is not blacklisted | No client with this ID in the workspace, or the client is not blacklisted. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
ids | string[] | Required. The IDs of the clients to archive. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
ids | string[] | Required. The IDs of the clients to restore. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
ids | string[] | Required. The IDs of the clients to blacklist. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
ids | string[] | Required. The IDs of the clients to remove from the blacklist. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
ids | string[] | Required. The IDs of the clients to delete permanently. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
| Error | Cause |
|---|---|
You do not have permission to access this resource with your current role assignment | The caller’s role is below Admin, or the request uses an agent API key. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
tags | string[] | Tags filter. A client matches only when it has all of these tags. |
stageId | string | Stage filter. A client matches only when it is in this stage. |
Request & Response
POST https://gateway.bcrumbs.net/core/gqmutation 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.
| Error | Cause |
|---|---|
Either tags or stageId must be provided | Neither tags (non-empty) nor stageId was sent. |
You do not have permission to access this resource with your current role assignment | The caller’s role is below Admin, or the request uses an agent API key. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
jobId | string | Required. The |
Request & Response
POST https://gateway.bcrumbs.net/core/gqquery 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"
}
}
}status | Meaning | Fields set |
|---|---|---|
pending | Queued, not started yet. | processedCount (0) |
processing | Rows are being imported. | startedAt, totalCount (rows in the CSV), processedCount (updated every 100 rows) |
completed | All rows were handled. | Adds totalProcessed, success, errors, skipped and completedAt |
failed | The 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.
Programming language examples
cURL
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}"}'