Submit a bounded asynchronous batch
curl --request PUT \
--url https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/batches/{externalBatchId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"records": [
{
"recordId": "r1",
"kind": "customer",
"externalId": "CUS_123",
"body": {
"contacts": [
{
"address": {
"countryCode": "IE",
"line1": "1 Example Street",
"line2": "Example Building",
"locality": "Dublin",
"postalCode": "D02 X285",
"region": "Dublin",
"type": "home"
},
"email": {
"address": "avery@example.test",
"type": "personal"
},
"externalContactId": "CON_7F3K2Q",
"fullName": "Avery Example",
"isCustomerSelf": true,
"isMain": true,
"phone": {
"number": "+35315550123",
"type": "mobile"
}
}
],
"name": {
"firstName": "Avery",
"lastName": "Example"
},
"sourceReference": "member-ref-example",
"type": "person"
}
},
{
"recordId": "r2",
"kind": "receivable",
"externalId": "REC_123",
"dependsOn": [
"r1"
],
"body": {
"financialType": "loan_balance",
"sourceRevision": 1,
"balanceBreakdown": {
"costs": {
"amount": "0.00",
"currency": "EUR"
},
"fees": {
"amount": "50.00",
"currency": "EUR"
},
"interest": {
"amount": "200.00",
"currency": "EUR"
},
"principal": {
"amount": "1000.00",
"currency": "EUR"
}
},
"creditUnion": {
"arrearsAmount": {
"amount": "1250.00",
"currency": "EUR"
},
"contractualInstalment": {
"amount": {
"amount": "125.00",
"currency": "EUR"
},
"frequency": "monthly"
},
"defaultDate": "2026-07-01",
"loanAccountReference": "loan-ref-example",
"loanType": "personal_loan",
"totalOutstandingAmount": {
"amount": "4000.00",
"currency": "EUR"
}
},
"dueDate": "2026-08-01",
"recoverableAmount": {
"amount": "1250.00",
"currency": "EUR"
},
"responsibleCustomers": [
{
"externalCustomerId": "CUS_123",
"role": "primary"
}
],
"sourceReference": "receivable-ref-example"
}
},
{
"recordId": "r3",
"kind": "payment_observation",
"externalId": "PAY_123",
"dependsOn": [
"r2"
],
"body": {
"allocations": [
{
"amount": {
"amount": "250.00",
"currency": "EUR"
},
"externalReceivableId": "REC_123"
}
],
"amount": {
"amount": "300.00",
"currency": "EUR"
},
"effectiveAt": "2026-08-29T11:45:00Z",
"externalCustomerId": "CUS_123",
"method": "bank_transfer",
"sourceReference": "payment-ref-example",
"type": "payment"
}
}
]
}
'{
"externalBatchId": "BATCH_2026_10_15",
"status": "partially_succeeded",
"bookCompleteness": "not_declared",
"submittedAt": "2026-10-15T02:00:00.000Z",
"completedAt": "2026-10-15T02:00:07.000Z",
"counts": {
"total": 3,
"pending": 0,
"succeeded": 1,
"failed": 1,
"dependencyFailed": 1
},
"records": [
{
"position": 1,
"recordId": "r1",
"kind": "customer",
"externalId": "CUS_123",
"status": "succeeded",
"httpStatus": 201
},
{
"position": 2,
"recordId": "r2",
"kind": "receivable",
"externalId": "REC_123",
"status": "failed",
"httpStatus": 422,
"problem": {
"type": "profile_mismatch"
}
},
{
"position": 3,
"recordId": "r3",
"kind": "payment_observation",
"externalId": "PAY_123",
"status": "dependency_failed",
"blockedBy": "r2"
}
]
}
Batches
Submit a bounded asynchronous batch
Requires the write scope of every kind in the batch (customers:write, receivables:write, payment_observations:write, financial_corrections:write). Queues up to 100 records, each the exact body of its synchronous operation, for asynchronous processing in array order. 202 acknowledges queued work only: it does not mean any record was accepted. Each record runs through the same authorization, schema and canonical operation as its synchronous route, with grants rechecked when it runs. A record whose declared dependency did not succeed is never attempted. A retry with the same identifier and an identical body returns the current state with 200 and queues nothing new, so a lost acknowledgement is safe to retry. A batch never declares a complete book.
PUT
/
v1
/
clients
/
{clientCode}
/
batches
/
{externalBatchId}
Submit a bounded asynchronous batch
curl --request PUT \
--url https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/batches/{externalBatchId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"records": [
{
"recordId": "r1",
"kind": "customer",
"externalId": "CUS_123",
"body": {
"contacts": [
{
"address": {
"countryCode": "IE",
"line1": "1 Example Street",
"line2": "Example Building",
"locality": "Dublin",
"postalCode": "D02 X285",
"region": "Dublin",
"type": "home"
},
"email": {
"address": "avery@example.test",
"type": "personal"
},
"externalContactId": "CON_7F3K2Q",
"fullName": "Avery Example",
"isCustomerSelf": true,
"isMain": true,
"phone": {
"number": "+35315550123",
"type": "mobile"
}
}
],
"name": {
"firstName": "Avery",
"lastName": "Example"
},
"sourceReference": "member-ref-example",
"type": "person"
}
},
{
"recordId": "r2",
"kind": "receivable",
"externalId": "REC_123",
"dependsOn": [
"r1"
],
"body": {
"financialType": "loan_balance",
"sourceRevision": 1,
"balanceBreakdown": {
"costs": {
"amount": "0.00",
"currency": "EUR"
},
"fees": {
"amount": "50.00",
"currency": "EUR"
},
"interest": {
"amount": "200.00",
"currency": "EUR"
},
"principal": {
"amount": "1000.00",
"currency": "EUR"
}
},
"creditUnion": {
"arrearsAmount": {
"amount": "1250.00",
"currency": "EUR"
},
"contractualInstalment": {
"amount": {
"amount": "125.00",
"currency": "EUR"
},
"frequency": "monthly"
},
"defaultDate": "2026-07-01",
"loanAccountReference": "loan-ref-example",
"loanType": "personal_loan",
"totalOutstandingAmount": {
"amount": "4000.00",
"currency": "EUR"
}
},
"dueDate": "2026-08-01",
"recoverableAmount": {
"amount": "1250.00",
"currency": "EUR"
},
"responsibleCustomers": [
{
"externalCustomerId": "CUS_123",
"role": "primary"
}
],
"sourceReference": "receivable-ref-example"
}
},
{
"recordId": "r3",
"kind": "payment_observation",
"externalId": "PAY_123",
"dependsOn": [
"r2"
],
"body": {
"allocations": [
{
"amount": {
"amount": "250.00",
"currency": "EUR"
},
"externalReceivableId": "REC_123"
}
],
"amount": {
"amount": "300.00",
"currency": "EUR"
},
"effectiveAt": "2026-08-29T11:45:00Z",
"externalCustomerId": "CUS_123",
"method": "bank_transfer",
"sourceReference": "payment-ref-example",
"type": "payment"
}
}
]
}
'{
"externalBatchId": "BATCH_2026_10_15",
"status": "partially_succeeded",
"bookCompleteness": "not_declared",
"submittedAt": "2026-10-15T02:00:00.000Z",
"completedAt": "2026-10-15T02:00:07.000Z",
"counts": {
"total": 3,
"pending": 0,
"succeeded": 1,
"failed": 1,
"dependencyFailed": 1
},
"records": [
{
"position": 1,
"recordId": "r1",
"kind": "customer",
"externalId": "CUS_123",
"status": "succeeded",
"httpStatus": 201
},
{
"position": 2,
"recordId": "r2",
"kind": "receivable",
"externalId": "REC_123",
"status": "failed",
"httpStatus": 422,
"problem": {
"type": "profile_mismatch"
}
},
{
"position": 3,
"recordId": "r3",
"kind": "payment_observation",
"externalId": "PAY_123",
"status": "dependency_failed",
"blockedBy": "r2"
}
]
}
Authorizations
Integration-owned environment-specific API key. Never paste a production key into documentation tools.
Path Parameters
Stable non-sensitive Client code authorized by the Integration grant.
Pattern:
^[A-Za-z0-9_-]{1,128}$Caller-assigned identifier of this batch submission. Reusing it with an identical body is a safe retry.
Pattern:
^[A-Za-z0-9_-]{1,128}$Body
application/json
One uncompressed resource representation, limited to 256 KiB.
Processed in array order, at most 100 per batch. Each record is the exact body of the synchronous operation for its kind.
Required array length:
1 - 100 elements- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
Show child attributes
Show child attributes
Response
Identical safe retry; current progress.
Pattern:
^[A-Za-z0-9_-]{1,128}$queued and running mean work is outstanding; submission never implies acceptance. succeeded: every record succeeded. partially_succeeded: some records did not succeed. failed: no record succeeded.
Available options:
queued, running, succeeded, partially_succeeded, failed A batch never declares a complete book, and no missing-record processing follows from any batch outcome, however it finishes. Completeness is declared only through a separate verified complete-book declaration.
Allowed value:
"not_declared"Pattern:
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$Show child attributes
Show child attributes
Maximum array length:
100Show child attributes
Show child attributes
Pattern:
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$