External Workspace Items

External Workspace Items¶

Workspace items that should be executed by an external process¶

By default, BT Collections is perfectly capable to perform the procedure steps (e.g. Send a reminder, perform a phonecall, ...). But sometimes you want to offload the execution of these actions to an external process and wait for feedback before you can continue with the procedure. This endpoint gives all such actions.

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Collections%20API%201.6.8#/Collection/getExternalWorkspaceItems

Permission / Auth¶

Bearer token with collection scope (read).

Header: Authorization: Bearer <token>

Query Parameters¶

Name	In	Required	Type	Description
`companyId`	query	No	string	Optional parameter to filter on a specific company. Ignored when "cursor" is provided. Fetch the list of available companies from the "/companies" endpoint.
`modifiedSince`	query	No	string (date-time)	Optional parameter to filter the data on modification date. Ignored when "cursor" is provided. All data with "modified at date" greater or equal than the provided date will be returned. The date should be in RFC 3339 format (e.g. "2000-01-21T13:40:30+02:00").
`cursor`	query	No	string	Optional parameter that allows you to retrieve the next batch of a request. When provided, the "companyId" and "modifiedSince" parameters will be ignored. See "Fetching data incrementally in batches" for more info.

Example Request¶

curl -X GET 'https://{your-collections-platform-host}/api/v1/external-workspace-items' \
    -H 'accept: application/json' \
    -H 'Authorization: Bearer <token>'

Example Response¶

{
  "data": [
    {
      "id": 1,
      "created_at": "2024-01-15T12:00:00+00:00",
      "modified_at": "2024-01-15T12:00:00+00:00",
      "running_procedure_id": 1,
      "debtor_id": 1,
      "code": "string",
      "external_reference": "string",
      "is_acknowledged": false,
      "acknowledged_at": "2024-01-15T12:00:00+00:00",
      "is_processed": false,
      "processed_at": "2024-01-15T12:00:00+00:00",
      "metadata": "string"
    }
  ],
  "next_batch_url": null,
  "next_batch_cursor": null,
  "resume_url": "https://{your-collections-platform-host}/api/v1/example?cursor=opaque-resume-cursor",
  "resume_cursor": "opaque-resume-cursor"
}

Batch envelope¶

Field	Description
`data`	Array of entities in this batch (max 100).
`next_batch_cursor` / `next_batch_url`	Pass cursor on the next request until empty.
`resume_cursor` / `resume_url`	Available when the full set is exhausted; use later for incremental sync.

`ExternalWorkspaceItem` fields¶

Field	Type	Description
`id`	integer (int64)	Id of the action
`created_at`	string (date-time)	The time this action is created.
`modified_at`	string (date-time)	The time this action is modified.
`running_procedure_id`	integer (int64)	The id for the 'running procedure' for which this action is created.
`debtor_id`	integer (int64)	The debtor that was linked to the action.
`code`	string	A code indicating the action that needs to be performed. This code should be known by the external processing party.
`external_reference`	string	The identification as which this action is known by the external processing party.
`is_acknowledged`	boolean	The action has been acknowledged (seen) by the external party.
`acknowledged_at`	string (date-time)	The time when this action was acknowledged.
`is_processed`	boolean	The action has been processed by the external party.
`processed_at`	string (date-time)	The time of processing.
`metadata`	string	A free-text field (max size: 2048 bytes) that can be written by the external process to ‘safeguard’ some data that is created during the process. This payload can be used for post-processing by the external party. Be aware: BT Collections will not be able to use this metadata in its own processes.

Edit fields of an External Workspace Item¶

When an External Workspace Item is processed by the external party, this endpoint can be used to provide feedback to BT Collections

Swagger Page¶

https://swagger-ui.aws-prod.billtrust.com/?urls.primaryName=Collections%20API%201.6.8#/Collection/patchExternalWorkspaceItem

Permission / Auth¶

Bearer token with collection scope (write).

Header: Authorization: Bearer <token>

Query Parameters¶

Name	In	Required	Type	Description
`id`	query	Yes	integer	Required : The ID of the external workspace item you want to edit

Request Body¶

Referenced body: PatchBody (JSON Patch array).

Writable fields (JSON Patch `path`)¶

Path	Type	Description
`/external_reference`	string (nullable)	External process identifier for this action.
`/is_acknowledged`	boolean	Mark the action as seen/acknowledged by the external party.
`/is_processed`	boolean	Mark the action as processed by the external party.
`/metadata`	string (nullable, max 2048 bytes)	Opaque payload the external process may store for later use.

[
  {
    "op": "replace",
    "path": "/is_acknowledged",
    "value": true
  },
  {
    "op": "replace",
    "path": "/is_processed",
    "value": true
  },
  {
    "op": "replace",
    "path": "/external_reference",
    "value": "EXT-12345"
  },
  {
    "op": "replace",
    "path": "/metadata",
    "value": "{\"jobId\":\"abc\"}"
  }
]

Example Request¶

curl -X PATCH 'https://{your-collections-platform-host}/api/v1/external-workspace-items?id={id}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <token>' \
    -d '[{"op": "replace", "path": "/is_processed", "value": true}, {"op": "replace", "path": "/external_reference", "value": "EXT-12345"}]'

Example Response¶

HTTP 204 No Content on success.