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 (opens in a new tab).

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.
`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.

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.

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.
}

The query above returns JSON structured like this:

{
  "data": {
    "clients": {
      "nodes": [
        {
          "id": "id_123",
          "name": "sample",
          "surname": "sample",
          "phone": "+12025550123",
          "externalClientId": "sample",
          "createdAt": "2026-03-16T00:00:00.000Z"
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "cursor_123",
        "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,"conversationId":"sample","email":"[email protected]","name":"sample","surname":"sample","code":"sample","city":"sample","country":"sample","phone":"+12025550123","externalClientId":"sample","tags":["sample"],"stageId":"sample","isDeleted":true}},"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`	Client stage.
`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/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.
  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": "id_123",
      "name": "sample",
      "surname": "sample",
      "phone": "+12025550123",
      "externalClientId": "sample",
      "createdAt": "2026-03-16T00:00: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":"sample","surname":"sample","phone":"+12025550123","code":"sample","city":"sample","country":"sample","address":"sample","stage":"sample","defaultAgentId":"id_123","externalClientId":"sample","tags":["sample"]}},"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/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": "id_123",
      "name": "sample",
      "surname": "sample",
      "phone": "+12025550123",
      "externalClientId": "sample",
      "createdAt": "2026-03-16T00:00: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":"sample","surname":"sample","phone":"+12025550123","code":"sample","city":"sample","country":"sample","address":"sample","defaultAgentId":"id_123","externalClientId":"sample","tags":["sample"]}},"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/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.

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/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}"}'

Channels Agents