Contacts¶

Contacts are optional Collections-only resources. They supply supplementary contact details for an account — additional email addresses, phone numbers, or alternative points of contact for Collections outreach.

Note

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

POST /contacts/{reference}¶

Creates a new contact.

Path Parameters¶

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

Request Body¶

Field	Type	Required	Description
account_number	string	Conditional	Account this contact belongs to. Required for Collections workflows — without this the contact cannot be linked for reminders or call lists.
name	string	No	Full name. Mutually exclusive with `first_name` / `last_name`.
first_name	string	No	First name. Mutually exclusive with `name`.
last_name	string	No	Last name. Mutually exclusive with `name`.
function	string	No	Contact's role or function (e.g. `accountant`).
email	string	No	Email address.
phone	string	No	Phone number.
mobile_phone	string	No	Mobile number.
fax	string	No	Fax number.
title	string	No	Job title.
department	string	No	Department.
contact_type	string	No	Classification code or label.
language	string (ISO 639-1)	No	Used in Collections communications directed to this contact.
address1	string	No	Street address line 1.
address2	string	No	Street address line 2.
city	string	No	City.
state	string	No	State / province.
zip	string	No	Postal code.
country	string	No	Country (ISO 3166-1 alpha-2).
notes	string	No	Free-text notes about this contact.
is_primary	boolean	No	True = primary contact. Phone and email are used when Collections sends reminders or places calls.
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/contacts/CONTACT-001 \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "ACCT-001",
    "first_name": "John",
    "last_name": "Doe",
    "email": "jdoe@acmecorp.com",
    "phone": "404-555-0100",
    "is_primary": true
  }'

PUT /contacts/{reference}¶

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

Request Body¶

Same fields as POST.

GET /contacts/{reference}¶

Retrieves a contact.

Status Codes¶

Status	Description
200	Contact found.
404	Not found.

Example Request¶

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

PATCH /contacts/{reference}¶

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

Status Codes¶

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

Example Request¶

curl -X PATCH https://ext.arc-aegis.billtrust.com/api/v1/ingest/contacts/CONTACT-001 \
  -H "X-API-Key: <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jdoe.new@acmecorp.com"
  }'