openapi: 3.0.3
info:
title: InDebted Receive API Documentation Account Claim API
description: 'This is the API definition for interacting with InDebted''s Receive debt servicing platform. For more details please visit the [Integration Documentation](https://docs.indebted.co/docs/receive/receive-knowledge-base).
**Using this spec in code generators, Postman, or other tooling?** Fetch the raw document at [https://receive-api.indebted.co/openapi/apiSchema.yaml](https://receive-api.indebted.co/openapi/apiSchema.yaml) — that is the canonical OpenAPI file. Prefer it over the in-page download button, which re-serialises the document and can alter value types (e.g. date-formatted strings).'
contact:
email: techteam@indebted.co
version: 1.53.1
servers:
- url: /
description: API base path
tags:
- name: Claim
description: A claim is an outstanding payment that is owed. You can always update this balance if multiple payments are missed and you want to aggregate the amounts.
externalDocs:
description: Account Claims
url: https://docs.indebted.co/docs/receive/integration/account-claims
paths:
/v1/{clientId}/get_account_claims:
get:
tags:
- Claim
summary: It retrieves the claims from a given account
description: 'The intetion of this endpoint is to fetch the Claims from a given Account.
For more details about the Account, and the relationship with the other entities please visit the [Account](https://docs.indebted.co/docs/receive/integration/account-claims) page.
'
operationId: getAccountClaims
parameters:
- $ref: '#/components/parameters/ClientIdParameter'
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/TriggerNameParameter'
- $ref: '#/components/parameters/AccountReferenceParameter'
- name: status
in: query
required: false
description: Claim Status filter
schema:
type: string
enum:
- ACTIVE
- RESOLVED
description: 'The Claim is either Active or Resolved, where Active means that there is an existing debt and Resolved means that the debt does not longer exist (there are multiple ways of resolving the Claim other than paying the claim, please refer to the Integration Documentation for further details).
'
- name: paginationId
in: query
required: false
description: Get the Account Claims by Pagination
schema:
type: string
description: 'The Pagination will be unique identifier to fetch and traverse the claims page wise with every new request and returns null when no claims founds in DB.
'
example: paginationId=eyJhY2NvdW50SWQiOiJBTExBVklOX0FDQ09VTlRfMDEyNyIsImNsaWVudElkIjoiM2QxMzJiMTgtNmI2Zi00ZjdjLWI0NjQtNmE4ZWU3Y2E1MjM1IiwiZXh0ZXJuYWxDbGFpbVJlZiI6IjAyOGZmNDM3LTc2NmItNDNjNC1iY2E4LWVlMTI4OWVhMDZjMCJ9
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 10000
description: amount of events per page, default is 1000
example: 1000
responses:
'200':
$ref: '#/components/responses/200SuccessGetAccountClaims'
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'429':
$ref: '#/components/responses/429LimitsReached'
'500':
$ref: '#/components/responses/500InternalError'
security:
- api_key: []
/v1/{clientId}/get_debtor_accounts_and_claims:
get:
tags:
- Claim
summary: It retrieves information about a debtor's accounts and claims
description: 'The intention of the endpoint is to retrieve information about a debtor''s accounts and claims.
'
operationId: getDebtorAccountsAndClaims
parameters:
- $ref: '#/components/parameters/ClientIdParameter'
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/TriggerNameParameter'
- name: debtorReference
in: query
required: true
description: Identifier of the debtor
schema:
type: string
responses:
'200':
$ref: '#/components/responses/200SuccessGetDebtorAccountsAndClaims'
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'429':
$ref: '#/components/responses/429LimitsReached'
'500':
$ref: '#/components/responses/500InternalError'
security:
- api_key: []
/v1/{clientId}/create_claims:
post:
tags:
- Claim
summary: Create claims in Receive
description: 'The intetion of this endpoint is to create Claims in Receive.
Notes:
- This endpoint throws an error if the Claim already exists (even if it was deleted).
- The claims created with this endpoint are not managed by the Ledger.
For more details about the Claim, and the relationship with the other entities please visit the [Account](https://docs.indebted.co/docs/receive/integration/account-claims) page.
'
operationId: createClaims
parameters:
- $ref: '#/components/parameters/ClientIdParameter'
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/TriggerNameParameter'
- $ref: '#/components/parameters/SequentialParameter'
- $ref: '#/components/parameters/AsyncParameter'
- $ref: '#/components/parameters/MinorVersionParameter'
requestBody:
required: true
content:
application/json:
schema:
type: object
description: ClaimReference as key and the Claim as value
additionalProperties:
$ref: '#/components/schemas/CreateClaimInput'
examples:
singleClaim:
summary: One claim on a new account
description: Minimal create for a debtor not yet in Receive. The map key (INV-2024-0042) is your own reference and is echoed back verbatim in the response so you can reconcile per claim.
value:
INV-2024-0042:
amount: 149900
currency: EUR
currentDueDate: '2024-05-01'
originalDueDate: '2024-05-01'
productReference: BROADBAND_PLAN_A
accountReference: ACC-DE-5567
totalFees: 0
primaryDebtor:
debtorReference: CUST-88213
firstName: Anke
lastName: Weber
contactInformation:
email: anke.weber@example.de
country: DE
batchTwoClaims:
summary: Several claims in one request
description: Add more keys to the map to upsert a batch. Each claim is processed independently and reported separately, so a batch can partially succeed.
value:
INV-2024-0042:
amount: 149900
currency: EUR
currentDueDate: '2024-05-01'
originalDueDate: '2024-05-01'
accountReference: ACC-DE-5567
primaryDebtor:
debtorReference: CUST-88213
firstName: Anke
lastName: Weber
contactInformation:
email: anke.weber@example.de
country: DE
INV-2024-0043:
amount: 52000
currency: EUR
currentDueDate: '2024-06-15'
originalDueDate: '2024-04-30'
accountReference: ACC-DE-5568
primaryDebtor:
debtorReference: CUST-88214
firstName: Bernd
lastName: Fischer
contactInformation:
email: bernd.fischer@example.de
country: DE
consolidatedClaim:
summary: Consolidated claim replacing instalment claims (acceleration)
description: After accelerating a loan, credit the individual instalment claims and place one claim for the enforceable balance. relatedClaims keeps the consolidation lineage queryable — it is metadata only; Receive does not resolve or modify the referenced claims.
value:
LOAN-2093-ACCEL:
amount: 390000
currency: EUR
currentDueDate: '2024-07-15'
originalDueDate: '2024-07-15'
accountReference: ACC-DE-5569
productReference: LOAN-2093
relatedClaims:
- type: REPLACES
claimReference: LOAN-2093-INST-07
- type: REPLACES
claimReference: LOAN-2093-INST-08
- type: REPLACES
claimReference: LOAN-2093-INST-09
primaryDebtor:
debtorReference: CUST-88215
firstName: Carlos
lastName: Norte
contactInformation:
email: carlos.norte@example.de
country: DE
responses:
'200':
$ref: '#/components/responses/200SuccessCreateClaims'
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'429':
$ref: '#/components/responses/429LimitsReached'
'500':
$ref: '#/components/responses/500InternalError'
security:
- api_key: []
/v1/{clientId}/recreate_claims:
post:
tags:
- Claim
summary: Recreate claims in Receive, applicable for already deleted claims.
description: 'The intetion of this endpoint is to recreate Claims in Receive.
Notes:
- This endpoint throws an error if the Claim is not deleted.
- The claims created with this endpoint are not managed by the Ledger.
- Recreating the claim will restart the claim lifecycle and the other related entities, this is specially important for the Collections Strategy, that will start from the beginning.
For more details about the Claim, and the relationship with the other entities please visit the [Account](https://docs.indebted.co/docs/receive/integration/account-claims) page.
'
operationId: recreateClaims
parameters:
- $ref: '#/components/parameters/ClientIdParameter'
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/TriggerNameParameter'
- $ref: '#/components/parameters/SequentialParameter'
- $ref: '#/components/parameters/AsyncParameter'
- $ref: '#/components/parameters/MinorVersionParameter'
requestBody:
required: true
content:
application/json:
schema:
type: object
description: ClaimReference as key and the Claim as value
additionalProperties:
$ref: '#/components/schemas/ClaimInput'
example:
CLAIM_REF_002_1:
amount: 1000
currency: EUR
currentDueDate: '2019-02-15'
originalDueDate: '2019-09-09'
productReference: PRODUCT_REFERENCE_002
accountReference: ACCOUNT_REFERENCE_002
portfolioReference: EXTERNAL_PORTFOLIO_REFERENCE_002
totalFees: 0
primaryDebtor:
debtorReference: EXTERNAL_DEBTOR_REF_002
firstName: F_N
lastName: L_N
contactInformation:
email: first.last@acme.com
country: DE
meta: {}
responses:
'200':
$ref: '#/components/responses/200SuccessRecreateClaims'
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'429':
$ref: '#/components/responses/429LimitsReached'
'500':
$ref: '#/components/responses/500InternalError'
security:
- api_key: []
/v1/{clientId}/update_claims:
post:
tags:
- Claim
summary: Update claims in the platform
description: 'The intetion of this endpoint is to update existing Claims in Receive.
Notes:
- This endpoint throws an error if the Claim does not exist.
- The claims updated with this endpoint are not managed by the Ledger. To update Claims related with the Ledger, use the Ledger related API endpoints.
- The payload is identical to other Claim related endpoints (like create_claims) but it can receive partial information, only the fields that are updated will be changed.
For more details about the Claim, and the relationship with the other entities please visit the [Account](https://docs.indebted.co/docs/receive/integration/account-claims) page.
'
operationId: updateClaims
parameters:
- $ref: '#/components/parameters/ClientIdParameter'
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/TriggerNameParameter'
- $ref: '#/components/parameters/SequentialParameter'
- $ref: '#/components/parameters/AsyncParameter'
- $ref: '#/components/parameters/MinorVersionParameter'
- name: forceAmountCheck
in: query
schema:
type: boolean
required: false
description: The force claim status update when amount is updated
requestBody:
required: true
content:
application/json:
schema:
type: object
description: ClaimReference as key and the Claim as value
additionalProperties:
$ref: '#/components/schemas/UpdateClaimInput'
examples:
updateAmount:
summary: Adjust a claim's outstanding amount
description: Partial upsert — only the fields you send change. Here the balance is raised to 5000 (cents) after a missed payment.
value:
INV-2024-0042:
amount: 5000
responses:
'200':
$ref: '#/components/responses/200Success'
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'429':
$ref: '#/components/responses/429LimitsReached'
'500':
$ref: '#/components/responses/500InternalError'
security:
- api_key: []
/v1/{clientId}/import_claims:
post:
tags:
- Claim
summary: Insert or Update Claims in the platform
description: 'The intetion of this endpoint is to create/update Claims in Receive.
It will create a new Claim if the Claim does not exist, or update the existing Claim if it already exists (abstraction over the create_claims and update_claims endpoints).
Notes:
- The claims updated with this endpoint are not managed by the Ledger. To update Claims related with the Ledger, use the Ledger related API endpoints.
- Notice that the payload is identical to other Claim related endpoints (like create_claims), and it requires the full Claim information in the payload, that will be used to upsert the Claim.
For more details about the Claim, and the relationship with the other entities please visit the [Account](https://docs.indebted.co/docs/receive/integration/account-claims) page.
'
operationId: importClaims
parameters:
- $ref: '#/components/parameters/ClientIdParameter'
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/TriggerNameParameter'
- $ref: '#/components/parameters/SequentialParameter'
- $ref: '#/components/parameters/AsyncParameter'
- $ref: '#/components/parameters/MinorVersionParameter'
requestBody:
required: true
content:
application/json:
schema:
type: object
description: A map of your claim references to claim payloads. Each key is YOUR reference for the claim (any string unique within your system) and is echoed back verbatim in the response so you can reconcile per-claim outcomes. Send several entries to upsert a batch in one call.
additionalProperties:
$ref: '#/components/schemas/ImportClaimInput'
examples:
newDebtorCreatesAccount:
summary: New overdue invoice — creates the Account and Claim in one call
description: No `accountReference` is supplied, so the `anyOf` on the claim requires `primaryDebtor` and `currency`. Receive creates the Account and the Claim together. The map key `INV-2024-0042` is your own reference and comes back unchanged in the response.
value:
INV-2024-0042:
amount: 149900
currency: EUR
originalDueDate: '2024-05-01'
currentDueDate: '2024-05-01'
productReference: BROADBAND_PLAN_A
primaryDebtor:
debtorReference: CUST-88213
firstName: Anke
lastName: Weber
contactInformation:
email: anke.weber@example.de
country: DE
mobileNumber: '+491701234567'
existingAccountWithFeesAndScore:
summary: Add to an existing Account, with fees, a risk score, and a forced balance check
description: 'Targets an existing `accountReference`, so `primaryDebtor` and `currency` are optional (inherited from the Account). `forceAmountCheck: true` makes Receive reject the call if `amount` does not equal ledger + fees — use it when you compute the balance yourself and want the API to guard against drift.'
value:
INV-2024-0043:
options:
forceAmountCheck: true
amount: 52000
totalFees: 2000
currency: EUR
originalDueDate: '2024-04-30'
currentDueDate: '2024-06-15'
accountReference: ACC-DE-5567
productReference: MOBILE_PLAN_M
fees:
- name: Late payment fee
amount: 2000
scores:
- type: INTERNAL
value: VERY_GOOD
primaryDebtor:
debtorReference: CUST-88214
firstName: Bernd
lastName: Fischer
contactInformation:
email: bernd.fischer@example.de
country: DE
movementsBreakdown:
summary: Ledger-driven import with a per-movement credit/debit breakdown
description: '`movements` is emit-only classification, not state: `amount` is still the source of truth for the claim balance and is NOT recomputed from `movements`. When present, Receive emits one typed credited/debited event per movement instead of a single net event. You are responsible for keeping `amount` consistent with the movements you send. Unknown `direction`/`type` values are rejected with a 400.'
value:
INV-2024-0044:
amount: 47000
currency: EUR
originalDueDate: '2024-04-30'
currentDueDate: '2024-06-15'
accountReference: ACC-DE-5567
productReference: MOBILE_PLAN_M
movements:
- direction: DEBIT
type: INTEREST
amount: 2000
sourceRef: LEDGER-ENTRY-0042
- direction: CREDIT
type: PAYMENT
amount: 5000
sourceRef: LEDGER-ENTRY-0043
responses:
'200':
description: A map keyed by the SAME claim references you sent. Each value reports that claim's outcome independently, so a batch can partially succeed — always inspect every entry's `success` flag.
headers:
Access-Control-Allow-Origin:
schema:
type: string
Access-Control-Allow-Methods:
schema:
type: string
Access-Control-Allow-Headers:
schema:
type: string
content:
application/json:
schema:
type: object
additionalProperties:
$ref: '#/components/schemas/ActionResponse'
examples:
newDebtorCreatesAccount:
summary: Response for the single-claim upsert
value:
INV-2024-0042:
success: true
messages:
- Successfully imported claim INV-2024-0042
messageIds:
- 7f257450-808c-4689-805f-6119cd8580ea
existingAccountWithFeesAndScore:
summary: Response for the fees + score upsert
value:
INV-2024-0043:
success: true
messages:
- Successfully imported claim INV-2024-0043
messageIds:
- 3d9b7c2a-1f4e-4a8b-9c6d-2e5f8a1b0c4d
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'429':
$ref: '#/components/responses/429LimitsReached'
'500':
$ref: '#/components/responses/500InternalError'
security:
- api_key: []
/v1/{clientId}/resolve_claims:
post:
tags:
- Claim
summary: Resolves Claims with a reason
description: 'The intetion of this endpoint is to resolve active Claims in Receive.
Notes:
- The claim state will change to resolved, but it will not affect other properties of the claim like the amount, due date, etc.
- To resolve the claim and update the amount to zero, please use the update_claims endpoint with the reason CLAIM_PAID as described in the Integration Documentation.
For more details about the Claim, and the relationship with the other entities please visit the [Account](https://docs.indebted.co/docs/receive/integration/account-claims) page.
'
operationId: resolveClaims
parameters:
- $ref: '#/components/parameters/ClientIdParameter'
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/TriggerNameParameter'
- $ref: '#/components/parameters/SequentialParameter'
- $ref: '#/components/parameters/AsyncParameter'
- $ref: '#/components/parameters/MinorVersionParameter'
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: object
properties:
ref:
type: string
example: CLAIM_REF_002
reason:
$ref: '#/components/schemas/ClaimResolutionReason'
examples:
resolvePaid:
summary: Resolve a single claim that was paid in full
description: Marks the claim resolved with reason CLAIM_PAID. Resolution changes state only — it does NOT zero the balance; use update_claims for that. reason is one of CLAIM_SOLD, CLAIM_PAID, FRAUDULENT, CLAIM_DISCARDED, CLAIM_DISCHARGED, CLAIM_INVALIDATED.
value:
- ref: INV-2024-0042
reason: CLAIM_PAID
resolveBatch:
summary: Resolve several claims with different reasons
value:
- ref: INV-2024-0042
reason: CLAIM_PAID
- ref: INV-2024-0043
reason: CLAIM_SOLD
responses:
'200':
$ref: '#/components/responses/200Success'
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'429':
$ref: '#/components/responses/429LimitsReached'
'500':
$ref: '#/components/responses/500InternalError'
security:
- api_key: []
/v1/{clientId}/credit_claims:
post:
tags:
- Claim
summary: Credit claims
description: "The intention of this endpoint is to credit claims in Receive.\nNotes:\n - Crediting the claim will decrease the amount of the claim.\n - If the claim amount is zero, the claim will be resolved.\n - When you provide fees as a number, it will reduce totalFees of the claim\n - When you provide fees as an array, we check\n - if a fee with same name already exists for the claim, if so, we substract incoming fee amount from existing fee amount and subtract fee.amount from totalFees of the claim\n - if a fee with same name does not exist, we ignore it\n - if you want to credit to fees only, set amount to 0.\n - if you want to credit to fees first, and then remaining amount to claim amount, do not send `fees` field (send `amount` only)\nFor more details about the Claim, and the relationship with the other entities please visit the [Account](https://docs.indebted.co/docs/receive/integration/account-claims) page.\n"
operationId: creditClaims
parameters:
- $ref: '#/components/parameters/ClientIdParameter'
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/TriggerNameParameter'
- $ref: '#/components/parameters/SequentialParameter'
- $ref: '#/components/parameters/AsyncParameter'
- $ref: '#/components/parameters/MinorVersionParameter'
requestBody:
required: true
content:
application/json:
schema:
type: object
description: claimReference as key and CreditClaimInput object as value
additionalProperties:
$ref: '#/components/schemas/CreditClaimInput'
example:
API_CLAIM_REF_002_1:
amount: 1000
currency: EUR
originator: DCA
date: 1647526514000
descriptionText: The claim received a partial payment through the DCA
paymentDistributionPriority: AMOUNT_FIRST
API_CLAIM_REF_002_2:
amount: 1000
fees: 500
currency: EUR
originator: DCA
date: 1647526514000
descriptionText: The claim received a partial payment through the DCA
paymentDistributionPriority: AMOUNT_FIRST
API_CLAIM_REF_002_3:
amount: 1000
fees:
- name: Processing Fee
amount: 25
- name: Late Fee
amount: 15
currency: EUR
originator: DCA
date: 1647526514000
descriptionText: The claim received a partial payment through the DCA
paymentDistributionPriority: AMOUNT_FIRST
responses:
'200':
$ref: '#/components/responses/200SuccessCreditClaim'
'400':
$ref: '#/components/responses/400BadRequest'
'401':
$ref: '#/components/responses/401Unauthorized'
'403':
$ref: '#/components/responses/403Forbidden'
'429':
$ref: '#/components/responses/429LimitsReached'
'500':
$ref: '#/components/responses/500InternalError'
security:
- api_key: []
/v1/{clientId}/debit_claims:
post:
tags:
- Claim
summary: Debit claims
description: "The intention of this endpoint is to debit claims in Receive.\nNotes:\n - Debiting the claim will increase the amount and/or totalFees of the claim.\n - When you provide fees as a number, it will be added to the totalFees of the claim\n - When you provide fees as an array, we check\n - if a fee with same name already exists for the claim, if so, we add incoming fee amount to existing fee amount and add fee.amount to totalFees of the claim\n - if a fee with same name does not exist, we create a new fee with the provided name and add fee.amount to totalFees of the claim\n - if you want to debit to fees only, set amount to 0.\nFor more details about the Claim, and the relationship with the other entities please visit the [Account](https://docs.indebted.co/docs/receive/integration/account-claims) page.\n"
operationId: debitClaims
parameters:
- $ref: '#/components/parameters/ClientIdParameter'
- $ref: '#/components/parameters/AuthorizationParameter'
- $ref: '#/components/parameters/TriggerNameParameter'
- $ref: '#/components/parameters/SequentialParameter'
- $ref: '#/components/parameters/AsyncParameter'
- $ref: '#/components/parameters/MinorVersionParameter'
requestBody:
required: true
content:
application/json:
schema:
type: object
description: claimReference as key and DebitClaimInput object as value
additionalProperties:
$ref: '#/components/schemas/DebitClaimInput'
examples:
debitAmountAndFees:
summary: Increase the amount and fees of active claims
value:
API_CLAIM_REF_002_1:
amount: 1000
currency: EUR
originator: CLIENT
date: 1647526514000
fees: 50
API_CLAIM_REF_002_2:
amount: 1500
currency: EUR
originator: CLIENT
date: 1647526514000
fees:
- name: Processing Fee
amount: 25
- name: Late Fee
amount: 15
chargebackReactivation:
summary: Payment reversal (chargeback) — restore the balance AND reactivate a resolved claim
description: 'A debit against a RESOLVED claim restores the balance but leaves the claim RESOLVED. Set `options.forceAmountCheck: true` to recompute the status from the resulting balance, reactivating the claim (and clearing its resolution reason) in the same call.'
value:
INV-2024-0042:
amount: 149900
currency: EUR
originator: CLIENT
date: 1647526514000
descriptionText: Chargeback of payment PSP-REF-8842
options:
forceAmountCheck: true
responses:
'200':
$ref: '#/components/responses/200SuccessDebitClaim'
'400':
$ref: '#/components/responses/400BadRequest'
'401':
# --- truncated at 32 KB (70 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/receeve/refs/heads/main/openapi/receeve-claim-api-openapi.yml