Skip to main content

FAQ: Integration and the Client API

How do I authenticate to the Receive Client API?​

The Client API uses OAuth 2.0 client credentials.

  1. Find your App Client ID and App Client Secret in the Backoffice under Configuration > API Credentials. Users with that permission can reveal, copy and regenerate them. Regenerating stops the old credentials working immediately.
  2. Request a token with POST /v1/oauth2/token, using Basic authentication with the base64-encoded clientId:clientSecret, Content-Type: application/x-www-form-urlencoded and the body grant_type=client_credentials.
  3. Send the returned access_token as it is in the Authorization header of each request. Do not add a Bearer prefix; a prefixed token is rejected with 403. Reuse the token until it expires (expires_in seconds).

See Authentication.

How do I create many claims or accounts at once in Receive?​

Use the Client API batch endpoints, such as import_claims, create_claims, update_claims and create_accounts. Each request body is an object keyed by your claim reference (or account reference). Items are processed in parallel, up to 30 per request. With ?sequential=true they are processed one after another, up to 5 per request. Items over the limit are answered individually with success: false, and each item in the response has its own result. import_claims creates a claim or updates it if it already exists; create_claims fails for an existing claim. See Create claims.

File-based import over SFTP is also possible, but it is set up per client by the Receive team, with a file format agreed for that client. Contact the team if you need it.

What is the difference between claimReference, externalClaimRef and accountReference?​

  • claimReference is your identifier for a claim, used as the key of each entry in a claim request. It must be unique within your client. Sending the same reference again addresses the same claim.
  • externalClaimRef is the same value under the name used in some responses, webhooks and endpoints.
  • externalClaimReferences is a list of claim references, for example the claims an instalment plan covers.
  • accountReference is your identifier for an account, unique within your client. Several claims can share it.
  • debtorReference is your identifier for the debtor.

See Account claims.

What is the minimum data needed to create a claim?​

Each claim needs amount (an integer in cents), originalDueDate and currentDueDate (YYYY-MM-DD), and either:

  • currency (ISO 4217, for example EUR) and a primaryDebtor, or
  • the accountReference of an existing account, whose debtor and currency are then used.

A primaryDebtor needs a debtorReference, contactInformation.country (ISO 3166-1 alpha-2), and firstName and lastName for a person or companyName for a company. See Account claims.

Is there a limit on claim metadata?​

There is no limit on the number of meta fields, but a claim should stay under 200 KB in total, and under 50 KB is recommended. Updates merge at the top level: keys you send are added or overwritten, and keys you leave out are kept. A nested object is replaced as a whole when you update it, so keep metadata flat where you can. See Metadata.

Can I read all claims with their current strategy through the API?​

Yes. Call GET /account/v1/{clientId}/get_claims with fields=strategy to include each claim's strategy and its status. fields is a repeated parameter (fields=a&fields=b), not a comma-separated list. Active and resolved claims are returned by default; add status=ACTIVE to narrow the results. Keep requesting with the returned paginationId until it is absent; a page can hold fewer items than limit while more remain.