curl --request PUT \
--url https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/recovery-instructions/{externalInstructionId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"effectiveAt": "2026-10-15T09:00:00Z",
"revision": 1,
"scope": {
"externalReceivableId": "LOAN_5521_INST_07",
"type": "receivable"
},
"state": "authorized"
}
'{
"effectiveAt": "2026-10-15T09:00:00Z",
"externalInstructionId": "RI_2026_000184",
"holds": [],
"recordedAt": "2026-10-15T09:00:04Z",
"recoveryEntryMode": "explicit_instruction",
"recoveryHeld": false,
"revision": 1,
"scope": {
"externalReceivableId": "LOAN_5521_INST_07",
"type": "receivable"
},
"state": "authorized"
}Record a recovery instruction
Requires recovery_instructions:write, a scope separate from receivables:write. Available only to a connection whose recovery entry mode is explicit_instruction; a connection using approved_rules receives recovery_mode_mismatch. Importing or updating a Receivable never starts recovery: an authorized instruction lets PayPathIQ begin recovery for that one Receivable, still subject to current source restrictions, Disputes, source freshness, collection activation and every other protection, all checked again when each action is attempted. An authorized instruction cannot be accepted while the Source holds a restriction or Dispute on the Receivable or its Customers. If the Source later raises one, the instruction becomes suspended and a new revision is required; clearing the restriction alone never resumes recovery. A withdrawn instruction holds recovery again. Revisions start at 1 and increase by exactly 1. An identical retry returns 200 and changes nothing.
curl --request PUT \
--url https://api.sandbox.paypathiq.com/v1/clients/{clientCode}/recovery-instructions/{externalInstructionId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"effectiveAt": "2026-10-15T09:00:00Z",
"revision": 1,
"scope": {
"externalReceivableId": "LOAN_5521_INST_07",
"type": "receivable"
},
"state": "authorized"
}
'{
"effectiveAt": "2026-10-15T09:00:00Z",
"externalInstructionId": "RI_2026_000184",
"holds": [],
"recordedAt": "2026-10-15T09:00:04Z",
"recoveryEntryMode": "explicit_instruction",
"recoveryHeld": false,
"revision": 1,
"scope": {
"externalReceivableId": "LOAN_5521_INST_07",
"type": "receivable"
},
"state": "authorized"
}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.
^[A-Za-z0-9_-]{1,128}$Caller-assigned, opaque identifier of this recovery instruction. One instruction governs one Receivable.
^[A-Za-z0-9_-]{1,128}$Body
One uncompressed resource representation, limited to 256 KiB.
A scoped, revisioned recovery instruction. It is separate from financial writes and requires the recovery_instructions:write scope.
The Receivable this instruction governs.
Show child attributes
Show child attributes
authorized lets PayPathIQ begin recovery for the Receivable, still subject to every current protection. withdrawn holds recovery again.
authorized, withdrawn Starts at 1 and increases by exactly 1 with each changed instruction. Repeat the same revision and content to retry safely.
1 <= x <= 2147483647When the Source issued this instruction.
^(?:(?:\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))$Response
Identical safe retry.
The accepted instruction and whether recovery for its Receivable is currently held.
^[A-Za-z0-9_-]{1,128}$The Receivable this instruction governs.
Show child attributes
Show child attributes
suspended means PayPathIQ withdrew the authority because the Source raised a restriction or Dispute after the instruction. Send a new revision to authorize again once the Source has cleared it.
authorized, withdrawn, suspended 1 <= x <= 9007199254740991^(?:(?:\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))$^(?:(?:\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))$"explicit_instruction"True while any hold prevents recovery for the Receivable right now.
Closed categories of the holds currently preventing recovery. An authorized instruction never clears any of them.
recovery_not_authorized, collection_not_enabled, source_restriction, dispute, source_stale, other_protection, reconciliation_hold