> ## Documentation Index > Fetch the complete documentation index at: https://docs.paypathiq.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /generated/inbound-api-v1.openapi.json put /v1/clients/{clientCode}/recovery-instructions/{externalInstructionId} openapi: 3.1.0 info: description: >- Send Customers, Receivables, and Payment observations and related financial evidence from your source system to PayPathIQ, one record at a time or as bounded asynchronous batches, and read back changes. Every operation listed here is implemented; capabilities that are not implemented are not listed. Start in sandbox with a sandbox key and synthetic data. Every error type links to a page at https://docs.paypathiq.com/problems/{code}. title: PayPathIQ Inbound Receivables API version: 1.0.0 servers: - description: Sandbox url: https://api.sandbox.paypathiq.com - description: Production url: https://api.paypathiq.com security: - BearerAuth: [] tags: - description: >- PayPathIQ-owned delivery of receipts to the accounting Source, with acknowledgement kept separate. name: Receipt delivery - description: People and businesses that owe one Client. name: Customers - description: Independently recoverable Receivables. name: Receivables - description: Immutable evidence of external payments, refunds, and reversals. name: Payment observations - description: >- Ordered Source balance snapshots for transaction and snapshot-only connections. name: Balance snapshots - description: >- Bounded asynchronous ingestion of up to 100 records with exact per-record outcomes. name: Batches - description: >- Verified complete-book declarations that flag and hold Receivables missing from the book. name: Complete books - description: Durable, resumable record of committed Customer and Receivable changes. name: Changes - description: >- Optional signed, minimal notifications that a Customer or Receivable changed. name: Webhooks - description: >- Fixed-amount hosted payment pages through the Client's own payment provider merchant. name: Payment requests - description: >- Partner-owned delivery of confirmed Payments to accounting, kept separate from accounting acceptance. name: Payment delivery - description: Explicit Receivable pause and closure commands. name: Receivable lifecycle - description: >- Explicit, revisioned instructions that let PayPathIQ begin recovery for a Receivable. name: Recovery instructions - description: >- Permissioned working collection position, holds, commitments and action outcomes, separate from the Source representation. name: Collection summaries - description: Whether accepted source evidence is recent enough to act on. name: Source freshness - description: This machine-readable API contract. name: Specification paths: /v1/clients/{clientCode}/recovery-instructions/{externalInstructionId}: put: tags: - Recovery instructions summary: Record a recovery instruction description: >- 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. operationId: putRecoveryInstruction parameters: - description: >- Stable non-sensitive Client code authorized by the Integration grant. in: path name: clientCode required: true schema: $ref: '#/components/schemas/ExternalResourceId' - description: >- Caller-assigned, opaque identifier of this recovery instruction. One instruction governs one Receivable. in: path name: externalInstructionId required: true schema: $ref: '#/components/schemas/ExternalResourceId' requestBody: description: One uncompressed resource representation, limited to 256 KiB. content: application/json: example: effectiveAt: '2026-10-15T09:00:00Z' revision: 1 scope: externalReceivableId: LOAN_5521_INST_07 type: receivable state: authorized schema: $ref: '#/components/schemas/RecoveryInstruction' required: true responses: '200': content: application/json: example: 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 schema: $ref: '#/components/schemas/RecoveryInstructionResponse' description: Identical safe retry. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '201': content: application/json: example: 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 schema: $ref: '#/components/schemas/RecoveryInstructionResponse' description: >- Instruction, its effect on recovery entry and audit evidence committed atomically. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string Location: description: Canonical URL of the created Integration-facing resource. schema: type: string format: uri '400': content: application/problem+json: examples: malformed_json: value: detail: Request body is not valid JSON. requestId: 29400000-0000-4000-8000-000000000001 status: 400 title: Request body is not valid JSON. type: https://docs.paypathiq.com/problems/malformed_json schema: $ref: '#/components/schemas/Problem' description: Request body is not valid JSON. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '401': content: application/problem+json: examples: invalid_api_key: value: detail: >- API key is invalid, inactive, revoked, or for another environment. requestId: 29400000-0000-4000-8000-000000000001 status: 401 title: >- API key is invalid, inactive, revoked, or for another environment. type: https://docs.paypathiq.com/problems/invalid_api_key schema: $ref: '#/components/schemas/Problem' description: API key is invalid, inactive, revoked, or for another environment. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '403': content: application/problem+json: examples: client_scope_denied: value: detail: >- The Client code is unknown, the grant lacks the required scope, or the calling address is outside the grant's IP allowlist. requestId: 29400000-0000-4000-8000-000000000001 status: 403 title: >- The Client code is unknown, the grant lacks the required scope, or the calling address is outside the grant's IP allowlist. type: https://docs.paypathiq.com/problems/client_scope_denied schema: $ref: '#/components/schemas/Problem' description: >- The Client code is unknown, the grant lacks the required scope, or the calling address is outside the grant's IP allowlist. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '409': content: application/problem+json: examples: recovery_mode_mismatch: value: detail: >- This connection declares approved_rules recovery entry, so instructions are not accepted. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- This connection declares approved_rules recovery entry, so instructions are not accepted. type: https://docs.paypathiq.com/problems/recovery_mode_mismatch recovery_instruction_conflict: value: detail: >- The identity already governs a different Receivable, or the Receivable is governed by a different instruction. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- The identity already governs a different Receivable, or the Receivable is governed by a different instruction. type: >- https://docs.paypathiq.com/problems/recovery_instruction_conflict recovery_restriction_active: value: detail: >- The Source holds a restriction or Dispute on the Receivable or its Customers, so recovery cannot be authorized. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- The Source holds a restriction or Dispute on the Receivable or its Customers, so recovery cannot be authorized. type: >- https://docs.paypathiq.com/problems/recovery_restriction_active source_revision_conflict: value: detail: >- The revision is not exactly one more than the accepted revision, or the same revision carries different content. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: >- The revision is not exactly one more than the accepted revision, or the same revision carries different content. type: >- https://docs.paypathiq.com/problems/source_revision_conflict dependency_missing: value: detail: The Receivable must already exist. requestId: 29400000-0000-4000-8000-000000000001 status: 409 title: The Receivable must already exist. type: https://docs.paypathiq.com/problems/dependency_missing schema: $ref: '#/components/schemas/Problem' description: >- This connection declares approved_rules recovery entry, so instructions are not accepted. The identity already governs a different Receivable, or the Receivable is governed by a different instruction. The Source holds a restriction or Dispute on the Receivable or its Customers, so recovery cannot be authorized. The revision is not exactly one more than the accepted revision, or the same revision carries different content. The Receivable must already exist. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '413': content: application/problem+json: examples: request_too_large: value: detail: Request body exceeds the 256 KiB resource limit. requestId: 29400000-0000-4000-8000-000000000001 status: 413 title: Request body exceeds the 256 KiB resource limit. type: https://docs.paypathiq.com/problems/request_too_large schema: $ref: '#/components/schemas/Problem' description: Request body exceeds the 256 KiB resource limit. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '415': content: application/problem+json: examples: unsupported_media_type: value: detail: >- Media type or content encoding is unsupported. Send uncompressed application/json for PUT and POST, and application/merge-patch+json for PATCH. requestId: 29400000-0000-4000-8000-000000000001 status: 415 title: >- Media type or content encoding is unsupported. Send uncompressed application/json for PUT and POST, and application/merge-patch+json for PATCH. type: https://docs.paypathiq.com/problems/unsupported_media_type schema: $ref: '#/components/schemas/Problem' description: >- Media type or content encoding is unsupported. Send uncompressed application/json for PUT and POST, and application/merge-patch+json for PATCH. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '422': content: application/problem+json: examples: validation_error: value: detail: >- Route parameters or the representation are invalid. Route parameters are checked before authentication. Field errors carry a code such as invalid_format, unrecognized_keys, custom, sensitive_external_id, or sensitive_source_reference. errors: - code: invalid_format detail: Invalid ISO date pointer: /dueDate requestId: 29400000-0000-4000-8000-000000000001 status: 422 title: >- Route parameters or the representation are invalid. Route parameters are checked before authentication. Field errors carry a code such as invalid_format, unrecognized_keys, custom, sensitive_external_id, or sensitive_source_reference. type: https://docs.paypathiq.com/problems/validation_error schema: $ref: '#/components/schemas/Problem' description: >- Route parameters or the representation are invalid. Route parameters are checked before authentication. Field errors carry a code such as invalid_format, unrecognized_keys, custom, sensitive_external_id, or sensitive_source_reference. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string '429': content: application/problem+json: examples: rate_limit_exceeded: value: detail: >- Each API key may send 60 requests per minute and run 1 request at a time. In sandbox, the same limits also apply per Client across all of its keys. Every request, including GET, counts. requestId: 29400000-0000-4000-8000-000000000001 status: 429 title: >- Each API key may send 60 requests per minute and run 1 request at a time. In sandbox, the same limits also apply per Client across all of its keys. Every request, including GET, counts. type: https://docs.paypathiq.com/problems/rate_limit_exceeded schema: $ref: '#/components/schemas/Problem' description: >- Each API key may send 60 requests per minute and run 1 request at a time. In sandbox, the same limits also apply per Client across all of its keys. Every request, including GET, counts. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string Retry-After: description: >- Seconds until this unchanged request may be retried: 1 after a concurrency rejection, 60 after the per-minute limit. schema: minimum: 1 type: integer '503': content: application/problem+json: examples: projection_unavailable: value: detail: >- An unexpected error prevented a safe commit, and nothing was saved. Retry with backoff. requestId: 29400000-0000-4000-8000-000000000001 status: 503 title: >- An unexpected error prevented a safe commit, and nothing was saved. Retry with backoff. type: https://docs.paypathiq.com/problems/projection_unavailable schema: $ref: '#/components/schemas/Problem' description: >- An unexpected error prevented a safe commit, and nothing was saved. Retry with backoff. headers: Cache-Control: description: Integration-facing responses are never cached. schema: const: no-store type: string PayPathIQ-Api-Version: description: >- Public API contract version; industry profile is fixed by the current Integration grant. schema: type: string const: v1 X-Request-Id: description: PayPathIQ-generated support correlation identifier. schema: format: uuid type: string security: - BearerAuth: [] components: schemas: ExternalResourceId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ RecoveryInstruction: type: object properties: scope: type: object properties: type: type: string const: receivable externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: - type - externalReceivableId additionalProperties: false description: The Receivable this instruction governs. state: type: string enum: - authorized - withdrawn description: >- authorized lets PayPathIQ begin recovery for the Receivable, still subject to every current protection. withdrawn holds recovery again. revision: type: integer minimum: 1 maximum: 2147483647 description: >- Starts at 1 and increases by exactly 1 with each changed instruction. Repeat the same revision and content to retry safely. effectiveAt: type: string format: date-time 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))$ description: When the Source issued this instruction. required: - scope - state - revision - effectiveAt additionalProperties: false description: >- A scoped, revisioned recovery instruction. It is separate from financial writes and requires the recovery_instructions:write scope. RecoveryInstructionResponse: type: object properties: externalInstructionId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ scope: type: object properties: type: type: string const: receivable externalReceivableId: type: string pattern: ^[A-Za-z0-9_-]{1,128}$ required: - type - externalReceivableId additionalProperties: false description: The Receivable this instruction governs. state: type: string enum: - authorized - withdrawn - suspended description: >- 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. revision: type: integer minimum: 1 maximum: 9007199254740991 effectiveAt: type: string format: date-time 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))$ recordedAt: type: string format: date-time 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))$ recoveryEntryMode: type: string const: explicit_instruction recoveryHeld: type: boolean description: True while any hold prevents recovery for the Receivable right now. holds: type: array items: type: string enum: - recovery_not_authorized - collection_not_enabled - source_restriction - dispute - source_stale - other_protection - reconciliation_hold description: >- Closed categories of the holds currently preventing recovery. An authorized instruction never clears any of them. required: - externalInstructionId - scope - state - revision - effectiveAt - recordedAt - recoveryEntryMode - recoveryHeld - holds additionalProperties: false description: >- The accepted instruction and whether recovery for its Receivable is currently held. Problem: type: object properties: detail: type: string errors: maxItems: 20 type: array items: type: object properties: code: type: string detail: type: string pointer: type: string required: - code - detail - pointer additionalProperties: false requestId: type: string format: uuid pattern: >- ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$ status: type: integer minimum: 400 maximum: 599 title: type: string type: type: string format: uri required: - detail - requestId - status - title - type additionalProperties: false securitySchemes: BearerAuth: bearerFormat: ppiq_test__ or ppiq_live__ description: >- Integration-owned environment-specific API key. Never paste a production key into documentation tools. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.