Debtor Custom Fields

Debtor Custom Fields¶

Debtor custom fields¶

A customizable field that can be added to a debtor. These fields can be visualized in the BT Collections UI.

Swagger Page¶

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

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/debtor-custom-fields' \
    -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",
      "debtor_id": 1,
      "is_deleted": false,
      "label": "string",
      "type": "string",
      "value_boolean": false,
      "value_date": "2024-01-15",
      "value_date_time": "2024-01-15T12:00:00+00:00",
      "value_double": 1.0,
      "value_integer": 1,
      "value_string": "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.

`DebtorCustomField` fields¶

Field	Type	Description
`id`	integer (int64)	Unique ID. Uniqueness is only guaranteed for all entities within this endpoint.
`created_at`	string (date-time)	The time this entity is created.
`modified_at`	string (date-time)	Last modification date of this entity.
`debtor_id`	integer (int64)	Internal BT Collections ID of the debtor of this custom field.
`is_deleted`	boolean	Indicates whether the custom field has been deleted or not.
`label`	string	The name of the custom field.
`type`	string	The type of the custom field. Can be either: boolean, date, date_time, double, integer, string.
`value_boolean`	boolean	The boolean value of the custom field with type "boolean". Can be null for deleted values or other field types.
`value_date`	string (date)	The date value of the custom field with type "date". Can be null for deleted values or other field types.
`value_date_time`	string (date-time)	The date/time value of the custom field with type "date_time". Can be null for deleted values or other field types.
`value_double`	number (float)	The double value of the custom field with type "double". Can be null for deleted values or other field types.
`value_integer`	integer (int64)	The integer value of the custom field with type "integer". Can be null for deleted values or other field types.
`value_string`	string	The string value of the custom field with type "string". Can be null for deleted values or other field types.

Create or update Debtor custom fields¶

Enable creating or updating custom fields for a debtor. Add either the debtorId param or the companyId and debtorSourceReference params together with the custom fields you would like to create or update

Swagger Page¶

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

Permission / Auth¶

Bearer token with collection scope (write).

Header: Authorization: Bearer <token>

Query Parameters¶

Name	In	Required	Type	Description
`debtorId`	query	No	string	Optional parameter that corresponds with the internal ID of the debtor you want to create or update custom fields for.
`companyId`	query	No	string	Optional parameter that corresponds with the internal ID of the company of the customer you want to create or update custom fields for.
`debtorSourceReference`	query	No	string	Optional parameter that corresponds with the source reference of the debtor you want to create or update custom fields for.

Request Body¶

The custom fields to create or update.

[
  {
    "label": "Custom field label",
    "value": "Custom field value"
  }
]

Identify the debtor with either:

debtorId, or
companyId and debtorSourceReference together

Example Request¶

curl -X POST 'https://{your-collections-platform-host}/api/v1/debtor-custom-fields-bulk-update?debtorId={debtorId}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <token>' \
    -d '[{"label": "Custom field label", "value": "Custom field value"}]'

Alternate identity (company + source reference):

curl -X POST 'https://{your-collections-platform-host}/api/v1/debtor-custom-fields-bulk-update?companyId={companyId}&debtorSourceReference={debtorSourceReference}' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <token>' \
    -d '[{"label": "Custom field label", "value": "Custom field value"}]'

Example Response¶

{
  "data": {
    "message": "Custom fields have been created/updated for the debtor."
  }
}

Response fields¶

Field	Type	Description
`data`	object	Success response containing a message that custom debtor fields were created/updated.