openapi: 3.2.0
info:
title: BPCC Task Routing API
version: 1.0.0
description: 'The Bright Pattern Contact Center (BPCC) Task Routing API v1 is a RESTful API that enables external systems (such as CRMs) to create, route, modify, cancel, and query tasks in BPCC.
Features
The Task Routing API v1 supports the following:
Queue Task: Create and queue a new task, associating it with a case and a contact.
Cancel Task: Remove a specific task from the queue and set its disposition.
Cancel Service Tasks: Cancel all queued tasks associated with a particular service.
Update Task: Modify attributes of a queued task, such as its service or priority.
Query Task: Retrieve the status and queue information for a specific task.
Support for external identifiers: Entities can be referenced using either internal (automatically generated by BPCC) or external (user provided) identifiers.
Entities
This API interacts with the following core objects within Bright Pattern Contact Center:
Task: A discrete unit of work representing a specific action or activity to be completed by an agent. Tasks are always associated with a case and contact. When a task is queued, it may be associated with an external identifier. Existing tasks may be canceled, updated, and queried by their internal or external identifiers.
Case: A grouping of communications and information related to a specific customer request. Cases are always associated with a contact. When a case is created via API, it may be linked with an external identifier. When a task is queued, an existing case may be associated with the task using the case''s external identifier.
Contact: A customer or individual involved in interactions. When a contact is created via API, it may be linked with an external identifier. When a task is queued, a contact can be associated with the task using the contact''s external identifier.
Endpoint Prefix
The Task Routing API v1 endpoint prefix is as follows:
https://<tenant_url>/taskroutingapi/v1/
Audience
This documentation is intended for IT personnel and developers responsible for integrating external systems with Bright Pattern Contact Center. Readers should have some familiarity of REST APIs, JSON data structures, and contact center concepts like services, queues, and dispositions. Experience with scripting or programming is recommended for implementing integrations using this API.
Usage
This documentation includes examples for each API method. These examples can serve as a starting point for developing your integrations. You can load these API descriptions into the Postman API Development Environment to interact with the API using your own access tokens.
Task Routing requests and responses may carry a JSON-encoded body of type application/json. Successful response bodies differ by method. Failed responses return the following:
{
"errorCode": [integer number],
"errorMessage": "[string with error description]"
}
Authorization
Users must be granted the Use Task Routing API privilege in order to use the following API methods. Administrators can grant this privilege in the Contact Center under Roles > Service and Campaign Administration
For more information, refer to the Administration Configuration Guide.'
contact:
name: Bright Pattern
url: https://www.brightpattern.com/contact/
x-origin:
- format: postman
url: https://documenter.getpostman.com/view/31590362/2sA3XTfLhk
version: '2.1'
x-evidence:
fetched: '2026-08-08'
source: https://documenter.gw.postman.com/api/collections/31590362/2sA3XTfLhk?segregateAuth=true&versionTag=latest
http_status: 200
method: derived-from-published-postman-collection
note: Mechanically converted from the Postman collection Bright Pattern publishes as its public API reference. No operations, paths, parameters or examples were invented.
servers:
- url: https://{tenant_url}
description: Bright Pattern is multi-tenant; the base host is the customer contact-center tenant domain.
variables:
tenant_url:
default: example.brightpattern.com
description: Your Bright Pattern Contact Center tenant hostname.
security:
- bearerAuth: []
tags:
- name: Task Routing
description: The following methods allow tasks within Bright Pattern Contact Center to be queued, canceled, updated, and queried.
paths:
/taskroutingapi/v1/task:
post:
operationId: queueTask
summary: Queue Task
description: "Queue a task and associate it with a case and contact.\n\nOptionally, you may provide external IDs to associate with the task, case, or contact to prevent duplicates. When external IDs are provided:\n\nBPCC checks for existing records linked with the provided External IDs for the task, case, or contact.\n\nIf a match is found for an External ID, the corresponding existing record in BPCC is used.\n\nIf no match is found for an External ID, a new record (task, case, or contact) is created in BPCC and associated with that External ID.\n\nFinally, the task (whether found or newly created) is linked to the case and contact entities (whether found or newly created) and queued in the indicated service.\n\nRequest Body\n\nProperty\nDescription\n\nextTaskId\nUnique identifier from an external system such as a CRM or database. \n- If an existing task in BPCC is already linked with extTaskId, any data in taskInfo, caseInfo and contactInfo are ignored, and the linked task is queued. \n- If a task linked with extTaskId does not exist in BPCC, a new task will be created with data from taskInfo and linked with the provided extTaskId. \n- If no extTaskId is provided, a new task will be created and queued with data from taskInfo. \nOptional.\n\nextCaseId\nUnique identifier from an external system such as a CRM or database. \n- If an existing case in BPCC is linked with extCaseId, the case is associated with the queued task and any data in caseInfo and contactInfo are ignored. \n- If a case linked to extCaseId does not exist, a new case is created with data from taskInfo, linked to extCaseId, and associated with the queued task. \n- If no extCaseId is provided, a new case is created with data from taskInfo and associated with the queued task. \nOptional.\n\nextContactId\nUnique identifier from an external system such as a CRM or database. \n- If an existing BPCC contact is linked with extContactId, the contact is associated with the queued task's case, and contactInfo is ignored. \n- If a contact linked with extContactId does not exist, a BPCC contact is created with data from contactInfo, linked with extContactId, and associated with the queued task's case,. \n- If no extContactId is provided, a contact is created with data from contactInfo and associated with the queued task's case. \nOptional.\n\nserviceName\nName of the Service where the task will be queued. Overrides the service specified by the scenario entry indicated by taskLaunchPointId. \n- Optional if taskLaunchPointId is provided. \n- Required if taskLaunchPointId is omitted\n\nscreenpop\nThe CRM screen pop URL or regular web URL screen pop to associated with the task. Example formats: SHOW_OBJECT:5551212:task or https://brightpattern.com \nCRM screen pops can only be displayed to agents using the BPCC widget in a CRM. To configure multiple screen pops, use the screenpopData property. \nOptional.\n\nscreenpopData\nArray of screenpopData objects. \n- Multiple web URL screen pops can be displayed if the agent is using the Agent Desktop. \n- A CRM screen pop will only be displayed to an agent using the Agent Desktop widget embedded in the corresponding CRM application. \n- Only a single CRM screen pop can be displayed to an agent. If multiple CRM screen pops of a single type appear in the array, the last one will be used. \nAvailable properties are described below. \nOptional\n\nwebScreenpopShowInTab\nBoolean specifying if a web URL screenpop should be opened in a new browser tab. Default is false. \n- When true the screenpop is opened in a new tab. \n- When false the screenpop is opened in the Agent Desktop. \n- Must be true in order to display a web URL screenpop to an agent using the BPCC widget in a CRM. If false, the screenpop can not be displayed \n- Ignored if screenpop is a CRM screenpop URL. \nOptional.\n\nscreenpopShowUponAnswer\nBoolean specifying if web screenpop should be opened when the agent accepts the task. Default value is false \n- When true, the screenpop will be displayed after the user answers (accepts) the task. \n- When false, the screenpop will display immediately as the task is assigned to an agent. \nThe value of screenpopShowUponAnswer sets the flag popUponAnswer to the Agent Desktop Client-Side JavaScript callback onWebScreenPopCustom. \nOptional.\n\npriority\nTask priority expressed as a number between 0.01 and 100, inclusive. A higher value will cause a task to move through the queue faster than tasks with a lower value, following the logic of Priority Value in the Set Priority scenario block. \nIf provided, overrides the priority defined by the Scenario Entry indicated by taskLaunchPointId. \nIf both priority and taskLaunchPointId are omitted, default value is 1 \nOptional.\n\norder\nQueue order of the task. Default is fifo. \n- fifo indicates 'First in, first out', meaning that the task will be assigned to an agent before any subsequently-queued tasks are assigned. \n- lifo indicates 'Last in, first out', meaning that the task will be assigned to an agent only after all previously-queued tasks are assigned. The priority value will be ignored for tasks with lifo ordering. \nOptional.\n\ncontactInfo\nUsed to create a contact. Required if extContactId is not provided or if no internal contact is associated with the provided extContactId. Available properties are listed below. \nOptional.\n\ncaseInfo\nUsed to create a case. Required if extCaseId is not provided or if no internal case is linked with extCaseId. Available properties are listed below. \nOptional.\n\ntaskInfo\nUsed to create a task. Required if extTaskId is not provided, or if no task is linked with extTaskId. Available properties are listed below. \nOptional.\n\ntaskLaunchPointId\nIndicate the Unique Identifier of the Task Scenario Entry that should be used when queuing the task. \nTask Scenario Entries provide a default Service with which to associate the task, and may define a default Priority. \n- The default Service defined by the Scenario Entry can be overridden by indicating a different Service with the s…"
tags:
- Task Routing
requestBody:
required: true
content:
application/json:
schema:
type: object
example:
extTaskId: task_id_12345_external_crm
extCaseId: case_id_67890_external_crm
extContactId: contact_id_6789_external_crm
serviceName: Task Service
screenpop: SHOW_OBJECT:192837465:task
screenpopData:
- type: web
url: https://www.brightpattern.com
label: The Title
webScreenpopShowInTab: true
- type: web
url: https://www.someotherurl.com
label: A different title that doesn't matter, since it's not opened in a tab
webScreenpopShowInTab: false
- type: dynamicscrm
url: SHOW_OBJECT:5551212:task
screenpopShowUponAnswer: true
webScreenpopShowInTab: true
screenpopShowUponAnswer: false
priority: 2
taskLaunchPointId: 952e8dc2e0469c349cb9c02c9b31f9150b7afd7a
order: fifo
contactInfo:
firstName: John
lastName: Doe
title: Senior Manager
position: Head of Engineering
summary: Experienced leader in software development.
segment: High Value Customer
dob: '1980-05-10T00:00:00.000Z'
emails:
- type: PRIMARY
address: john.doe@example.com
- type: BUSINESS
address: john.doe.business@example.com
addresses:
- type: PRIMARY
postcode: '90210'
state: CA
city: Beverly Hills
addressLine1: 123 Main Street
addressLine2: Suite 456
country: USA
custom_signup_source: Website
caseInfo:
category: Technical Support
priority: 1
custom_related_knowledge_base_article: KB-12345
taskInfo:
subject: Follow up on customer issue
custom_task_notes: Offer a reduced subscription price if customer is not satisfied by the resolution.
responses:
'200':
description: Queue Task
content:
application/json:
example:
taskId: 66bb3a68bf36507742b4c612
caseId: 66bb3a68bf36507742b4c611
contactId: 66bb3a68bf36507742b4c610
security:
- bearerAuth: []
/taskroutingapi/v1/task/{taskid}:
delete:
operationId: cancelTask
summary: Cancel Task
description: 'Removes the queued task specified by the taskId path variable from the queue and sets its disposition to dispositionName. Canceling a task is possible only while the task is still in the service queue or an agent''s personal queue.
Use the external query parameter to specify whether taskId is an internal or external identifier.
Request Body
Parameter
Description
note
An optional note to be added to the task as it is canceled, providing context for the action.
dispositionName
The name of the disposition to be applied to the canceled task, indicating the outcome or reason for closure. Default is Abandoned
Response Body Parameters
None'
tags:
- Task Routing
parameters:
- name: taskid
in: path
required: true
schema:
type: string
- name: external
in: query
required: false
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
example:
note: Cancelled per user request
dispositionName: Abandoned
responses:
'204':
description: Cancel Task
security:
- bearerAuth: []
patch:
operationId: updateTask
summary: Update Task
description: 'Modify the priority or associated service of the queued task specified by the taskID path variable.
Use the external query parameter to specify whether taskId is an internal or external identifier.
Request Body
Parameter
Description
serviceName
The name of the service to which the task should be moved. If different from the current service, the task will be re-queued to the new service.
priority
The new priority for the task. This only applies to tasks being routed using the lifo order.
Body Parameters
None'
tags:
- Task Routing
parameters:
- name: taskid
in: path
required: true
schema:
type: string
- name: external
in: query
required: false
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
example:
priority: 100
serviceName: New service
responses:
'200':
description: Update Task
security:
- bearerAuth: []
get:
operationId: queryTask
summary: Query Task
description: 'Retrieves information about the task specified by the taskId path variable.
Use the external query parameter to specify whether taskId is an internal or external identifier.
Request Body
None
Response Body
Parameter
Description
taskStatus
Task''s current status (CREATED, QUEUED, DEFERRED, COMPLETED).
serviceName
Name of the service with which the task is associated.
priority
Task queue priority.
order
Task queue order (FIFO/LIFO).
dispositionName
Disposition name for completed tasks. Empty if task is still queued.'
tags:
- Task Routing
parameters:
- name: taskid
in: path
required: true
schema:
type: string
- name: external
in: query
required: false
schema:
type: string
responses:
'200':
description: Query Task
content:
application/json:
example:
taskStatus: DEFERRED
priority: 5
serviceName: New Task Processing Service
order: fifo
dispositionName: Abandoned
security:
- bearerAuth: []
/taskroutingapi/v1/service:
delete:
operationId: cancelServiceTasks
summary: Cancel Service Tasks
description: 'Cancel all currently queued tasks associated with the service specified by serviceName. The disposition designated by dispositionName and the note specified by note is applied to each canceled task.
Request Body
Parameter
Description
serviceName
The name of the service for which all associated queued tasks should be canceled.
note
An optional note to be added to each task as it is canceled.
dispositionName
The name of the disposition to apply to each canceled tasks.
Response Body
Parameter
Description
count
The count of tasks canceled by the operation.
taskIds
Array of objects indicating the extTaskId and taskId of each canceled task.'
tags:
- Task Routing
requestBody:
required: true
content:
application/json:
schema:
type: object
example:
note: This service is no longer being offered.
serviceName: Example Service
dispositionName: Abandoned
responses:
'204':
description: Cancel Service Tasks
content:
application/json:
example:
count: 2
taskIds:
- extTaskId: '12345'
taskId: '5432321'
- extTaskId: '12346'
taskId: '5432322'
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: 'OAuth 2.0 access token issued by the Bright Pattern token endpoint, sent as `Authorization: Bearer <token>`.'
oauth2ClientCredentials:
type: oauth2
description: OAuth 2.0 client-credentials grant against the Bright Pattern tenant token endpoint.
flows:
clientCredentials:
tokenUrl: https://{tenant_url}/configapi/v2/oauth/token
scopes: {}