Representatives¶

Representatives are optional Collections-only resources. They model internal contacts (e.g. sales reps, account managers) who can be configured as escalation recipients in Collections reminder workflows. A representative can be linked to multiple accounts and multiple documents.

Note

Representatives are not used by Invoicing, Open Balance, or CashApp AR. Skip this section if Collections is not in scope.

POST /representatives/{reference}¶

Creates a new representative.

Path Parameters¶

Parameter	Description
`reference`	Caller-defined unique identifier for this representative within the tenant.

Request Body¶

Field	Type	Required	Description
name	string	No	Representative full name.
email	string	No	Email address.
phone	string	No	Phone number.
mobile_phone	string	No	Mobile number.
fax	string	No	Fax number.
language	string (ISO 639-1)	No	Used in Collections escalation communications.
title	string	No	Job title.
department	string	No	Department.
representative_type	string	No	Classification code or label.
supervisor_representative_reference	string	No	Reference of this rep's supervisor. The supervisor must also be a representative.
extra_info	string	No	Additional free-text information.
custom_fields	Custom Fields object	No	See Shared Schemas.

Status Codes¶

Status	Description
201	Created.
409	Reference already exists.
422	Validation failure.

Example Request¶

curl -X POST https://ext.arc-aegis.billtrust.com/api/v1/ingest/representatives/REP-001 \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Jane Smith",
    "email": "jsmith@yourcompany.com",
    "title": "Account Manager",
    "department": "Sales"
  }'

PUT /representatives/{reference}¶

Creates or replaces a representative. Returns 201 on create and 200 on replace. Safe to retry.

Request Body¶

Same fields as POST.

GET /representatives/{reference}¶

Retrieves a representative and its linked accounts and documents.

Status Codes¶

Status	Description
200	Representative found.
404	Not found.

Example Request¶

curl https://ext.arc-aegis.billtrust.com/api/v1/ingest/representatives/REP-001 \
  -H "X-API-Key: <your-api-key>"

PATCH /representatives/{reference}¶

Partially updates a representative. Only fields present in the request body are modified.

Status Codes¶

Status	Description
200	Updated. Returns the updated representative.
404	Not found.
422	Validation failure.

PUT /representatives/{reference}/accounts/{account_number}¶

Links a representative to an account. Idempotent — safe to call multiple times. Returns 200 even if already linked.

Status Codes¶

Status	Description
200	Linked (or already linked).
404	Representative or account not found.

Example Request¶

curl -X PUT https://ext.arc-aegis.billtrust.com/api/v1/ingest/representatives/REP-001/accounts/ACCT-001 \
  -H "X-API-Key: <your-api-key>"

PUT /representatives/{reference}/documents/{document_number}¶

Links a representative to a document. Idempotent.

Status Codes¶

Status	Description
200	Linked (or already linked).
404	Representative or document not found.

GET /representatives/{reference}/accounts¶

Returns a paginated list of account numbers linked to this representative.

Query Parameters¶

Parameter	Default	Description
page	1	Page number.
limit	100	Results per page. Maximum 100.

Status Codes¶

Status	Description
200	Success.
404	Representative not found.

GET /representatives/{reference}/documents¶

Returns a paginated list of document numbers linked to this representative.

Status Codes¶

Status	Description
200	Success.
404	Representative not found.