Collections Schemas¶

All fields applicable to the Collections product. Representatives, Contacts, and Notes are Collections-only resources and do not exist for other products.

For shared schemas (Currency Models, Address, Custom Fields, etc.) see Shared Schemas & Currency Models.

Account¶

Core Fields¶

Field	Type	Required	Description
reference	string	Yes	Caller-defined unique identifier. Used as `display_reference` if none provided.
display_reference	string	No	Display account number shown in the UI.
name	string	Yes	Customer name.
language	string (ISO 639-1)	Conditional	Required for Collections — used to translate reminder and notification communications.
currency	ISO 4217	Yes	Required for Collections. All account totals displayed in this currency.
vat	string	No	VAT registration number.
company_registration_number	string	No	Statutory company registration number.
billing_address	Address object	No	See Shared Schemas.
phone	string	No	Primary phone number.
mobile_phone	string	No	Mobile / cell phone number.
fax	string	No	Fax number.
email	string	No	Primary email. Used for Collections reminders and communications.
credit_limit	denomination	No	Credit limit amount.
account_group	string	No	Group this account belongs to. Accounts in the same group are displayed together in Collections with navigation links between them.
description	string	No	Free-text account description.
parent_account_number	string	No	Groups accounts into a parent-child hierarchy. All accounts sharing the same value are grouped together.
is_parent_account	numeric boolean	No	`1` identifies this account as the parent. Required when `parent_account_number` is set.

Custom Fields¶

Collections supports an unlimited number of typed custom fields at the account level. Values are retained when omitted from subsequent updates — submit with an empty value to clear. See Custom Fields Object.

Credit Provider Identifiers¶

Field	Type	Description
data_providers	object	Object containing third-party credit provider identifiers.
data_providers.ggs_id	string	CreditSafe identifier
data_providers.duns_number	string	D&B DUNS number
data_providers.graydon_enterprise_id	string	Graydon enterprise ID
data_providers.tbi_id	string	TBI identifier
data_providers.coface_easynumber	string	Coface easy number

Document¶

Core Fields¶

Field	Type	Required	Description
account_number	string	Yes	Account this document belongs to.
invoice_num	string	Conditional	Display invoice number. If omitted, the URL path `document_number` is used.
document_type	string	Yes	`invoice` or `credit_note`
applies_to_invoice	string	Conditional	Required when `document_type` is `credit_note`.
invoice_date	date (ISO 8601)	Yes	Document issue date.
due_date	date (ISO 8601)	Yes	Payment due date.
is_archived	boolean	No	True marks the document as archived.
journal	string	No	Journal / ledger identifier.
description	string	No	Free-text description. May appear in Collections communications with buyer contacts.
comment	string	No	Free-text internal comment. Visible to Collections users only.
paid_at_date	date	No	Date the document was paid in full. Triggers automatic close and archive.
grouping	string	No	Caller-defined grouping code. Documents with the same grouping on an account are visually grouped in Collections.
payment_reference	string	No	Remittance reference for EU-style payment matching.
external_hyperlink	string	No	URL to the document in the caller's system.

Custom Fields¶

Collections supports an unlimited number of typed custom fields at the document level. See Custom Fields Object.

Financial Fields — Basic Currency Model¶

All three fields must be provided together.

Field	Type	Required	Description
currency	ISO 4217	Conditional*	ISO 4217 currency code. *All three Basic fields must be provided together.
original_denomination	denomination	Conditional*	Original gross amount. Does not change when partially paid. Must be negative for credit notes.
denomination	denomination	Conditional*	Current open balance. When 0, document is automatically closed.

Financial Fields — Extended Currency Model¶

All six core fields must be provided together. Extended takes precedence over Basic if both are present.

Field	Type	Required	Description
original_currency	ISO 4217	Conditional*	Original transaction currency (e.g. EUR).
base_currency	ISO 4217	Conditional*	ERP / accounting system reporting currency (e.g. USD).
original_denomination_in_original_currency	denomination	Conditional*	Original gross amount in `original_currency`. Does not change when partially paid.
original_denomination_in_base_currency	denomination	Conditional*	Original gross amount in `base_currency`.
denomination_in_original_currency	denomination	Conditional*	Current open balance in `original_currency`.
denomination_in_base_currency	denomination	Conditional*	Current open balance in `base_currency`. When 0, document is automatically closed.
original_tax_amount	string	No	Tax amount in `original_currency`.
base_tax_amount	string	No	Tax amount in `base_currency`.
original_freight_amount	string	No	Freight amount in `original_currency`.
base_freight_amount	string	No	Freight amount in `base_currency`.

Closure¶

Field	Type	Required	Description
closure_reason	string	Yes	One of: `paid`, `write_off`, `contra`, `adjustment`, `other`
closure_date	date (ISO 8601)	No	Date of closure. Defaults to current date if absent.
notes	string	No	Free-text notes on the closure.

Representative¶

Optional. Representatives are internal contacts configured as escalation recipients in Collections reminder workflows.

Core Fields¶

Field	Type	Required	Description
reference	string	Yes (in URL)	Caller-defined unique identifier.
name	string	No	Representative full name.
language	string (ISO 639-1)	No	Used in Collections escalation communications.
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.
representative_type	string	No	Classification code or label.
supervisor_representative_reference	string	No	Reference of this rep's supervisor. Must also be a representative.
extra_info	string	No	Additional free-text information.

Custom Fields¶

Same structure as Account custom fields. See Custom Fields Object.

Contact¶

Optional. Contacts supply supplementary contact details for an account for Collections outreach.

Field	Type	Required	Description
reference	string	Yes (in URL)	Caller-defined unique identifier.
account_number	string	Conditional	Required for Collections workflows.
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 (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–zip, country	string	No	Contact address fields.
notes	string	No	Free-text notes.
is_primary	boolean	No	True = primary contact. Phone and email used for reminders and calls.

Note¶

Optional. Notes are immutable once created (SOX requirement). Commonly used for bulk historical import of collections notes before go-live.

Field	Type	Required	Description
reference	string	Yes	Caller-defined unique identifier. Must be unique across all notes within the tenant.
subject	string	No	Note subject line.
body	string	Yes	Note body text.
note_type	string	No	Caller-defined classification code.
effective_date	date (ISO 8601)	No	Date effective. Defaults to submission date if absent.