> ## Documentation Index > Fetch the complete documentation index at: https://docs.casepathiq.com/llms.txt > Use this file to discover all available pages before exploring further. # Place or replace a Matter > Creates a Matter on first valid PUT or fully replaces Integration-owned intake fields. Currency must equal the authorized Client currency and is immutable after creation. A full PUT may correct opening outstandingAmount only before recovery activity. Afterwards outstandingAmount must match the authoritative balance. Every PUT is conditional and must carry exactly one precondition: `If-None-Match: *` to create, or `If-Match: ` to replace an existing Matter. Neither header returns `428`; a precondition that no longer holds returns `412` without mutation. This is what stops a delayed delivery of older content from being committed as an intentional return to that content. ## OpenAPI ````yaml /openapi/partner-api-v1.yaml put /v1/clients/{clientCode}/matters/by-client-reference/{clientReferenceId} openapi: 3.1.0 info: title: CasePath IQ Partner API v1 version: 1.0.0 summary: Inbound Matter API for approved partner integrations license: name: Proprietary identifier: LicenseRef-Proprietary description: >- CasePath IQ Partner API v1 for scoped Matter intake, payment observations, lifecycle commands and polling. Sandbox callers use a Sandbox Bearer API key supplied securely at onboarding; no Microsoft sign-in or IP allowlist setup is required for new unrestricted Sandbox keys. Production onboarding is separate and is not advertised by this Sandbox specification. Every error is `application/problem+json`. Methods a route does not support, including `HEAD` and `OPTIONS`, return `405` with an `Allow` header, and unknown paths under `/v1` return `404`. Each key is limited to a fixed number of requests per minute; `429` and `503` carry `Retry-After`. While the platform pauses Partner API writes, every write returns `503 partner_writes_paused` and reads continue. servers: - url: https://api.sandbox.casepathiq.com description: Sandbox testing security: - PartnerKey: [] tags: - name: Matters description: Place, update, and read partner-owned Matter source data - name: Synchronization description: Pull minimized current-state changes for one granted Client - name: Payments description: Record and read immutable external payment evidence - name: Lifecycle description: Apply explicit, predecessor-bound Matter lifecycle transitions paths: /v1/clients/{clientCode}/matters/by-client-reference/{clientReferenceId}: parameters: - $ref: '#/components/parameters/ClientCode' - $ref: '#/components/parameters/ClientReferenceId' put: tags: - Matters summary: Place or replace a Matter description: >- Creates a Matter on first valid PUT or fully replaces Integration-owned intake fields. Currency must equal the authorized Client currency and is immutable after creation. A full PUT may correct opening outstandingAmount only before recovery activity. Afterwards outstandingAmount must match the authoritative balance. Every PUT is conditional and must carry exactly one precondition: `If-None-Match: *` to create, or `If-Match: ` to replace an existing Matter. Neither header returns `428`; a precondition that no longer holds returns `412` without mutation. This is what stops a delayed delivery of older content from being committed as an intentional return to that content. operationId: putMatterByClientReferenceId parameters: - $ref: '#/components/parameters/IfMatch' - $ref: '#/components/parameters/IfNoneMatch' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MatterSource' example: clientCode: SDCC clientReferenceId: SDCC-2026-00482 matterType: debt_recovery parties: - role: debtor type: person isPrimaryLiable: true name: givenName: Aoife middleNames: - Máire familyName: Murphy dateOfBirth: '1984-03-12' customerNumber: C-99102 addresses: - type: correspondence line1: 12 Example Street city: Tallaght state: Dublin countryCode: IE emails: - address: aoife.murphy@example.com type: personal isPrimary: true - address: aoife.murphy@work.example.com type: work isPrimary: false phones: - number: '+353871234567' type: mobile isPrimary: true - number: '+35314605000' type: landline isPrimary: false - role: debtor type: person isPrimaryLiable: false name: givenName: Cormac familyName: Murphy addresses: - type: correspondence line1: 12 Example Street city: Tallaght state: Dublin countryCode: IE debt: type: commercial_rates currency: EUR outstandingAmount: '1250.00' instruction: summary: Commercial rates arrears — instruct legal recovery requestedAction: letter_before_action responses: '200': $ref: '#/components/responses/MatterSuccess' '201': description: Matter created headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' ETag: $ref: '#/components/headers/ETag' Location: schema: type: string format: uri-reference content: application/json: schema: $ref: '#/components/schemas/MatterResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '408': $ref: '#/components/responses/RequestTimeout' '409': $ref: '#/components/responses/Conflict' '412': $ref: '#/components/responses/PreconditionFailed' '413': $ref: '#/components/responses/PayloadTooLarge' '415': $ref: '#/components/responses/UnsupportedMediaType' '428': $ref: '#/components/responses/PreconditionRequired' '429': $ref: '#/components/responses/TooManyRequests' '503': $ref: '#/components/responses/ServiceUnavailable' default: $ref: '#/components/responses/Problem' components: parameters: ClientCode: name: clientCode in: path required: true description: Granted Local Authority Client code schema: $ref: '#/components/schemas/ClientCodeValue' ClientReferenceId: name: clientReferenceId in: path required: true description: Stable partner Matter key; must not contain personal data schema: $ref: '#/components/schemas/ClientReferenceIdValue' IfMatch: name: If-Match in: header required: false description: >- The entity-tag the write is conditioned on, from the `ETag` header or the `etag` field of the representation you last read. Required to update an existing Matter. A stale tag returns `412`; omitting it on an update returns `428`. `*` matches any current Matter and returns `412` when none exists. A closed Matter returns `409 matter_closed` until it is reopened. schema: type: string example: '"m1-7f3a9c2b"' IfNoneMatch: name: If-None-Match in: header required: false description: >- Send `*` to create a Matter that must not already exist. Required on a create. If the client reference ID already has a Matter the request returns `412` without mutation — read the Matter and reconcile rather than replaying the create. schema: type: string const: '*' schemas: MatterSource: type: object additionalProperties: false required: - clientCode - parties - debt properties: clientCode: $ref: '#/components/schemas/ClientCodeValue' clientReferenceId: $ref: '#/components/schemas/ClientReferenceIdValue' description: >- Optional on write. When present it must equal the path's `clientReferenceId`, otherwise 400 identity_mismatch. matterType: $ref: '#/components/schemas/MatterTypeValue' parties: type: array minItems: 1 maxItems: 10 description: >- Every Party against whom recovery is instructed on this Matter. Exactly one entry must set `isPrimaryLiable: true`. Each entry needs its own usable correspondence address, because each is separately addressable. Do not duplicate the obligation per Party and do not split one instructed file into several Matters. items: $ref: '#/components/schemas/MatterParty' debt: $ref: '#/components/schemas/Debt' instruction: $ref: '#/components/schemas/Instruction' MatterResponse: type: object additionalProperties: false required: - clientCode - clientReferenceId - matterType - parties - debt - instruction - matterId - sourceRevisionId - lifecycleStateId - etag - status - intakeStatus - createdAt - updatedAt properties: clientCode: $ref: '#/components/schemas/ClientCodeValue' clientReferenceId: $ref: '#/components/schemas/ClientReferenceIdValue' matterType: $ref: '#/components/schemas/MatterTypeValue' parties: type: array minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/MatterParty' debt: $ref: '#/components/schemas/Debt' instruction: $ref: '#/components/schemas/Instruction' matterId: type: string sourceRevisionId: type: string lifecycleStateId: type: string etag: type: string description: >- Strong entity-tag of this partner-facing representation, identical to the `ETag` response header. Send it back as `If-Match` on the next write. example: '"m1-7f3a9c2b"' status: type: string enum: - received - in_review - active - paused - closed intakeStatus: type: string enum: - needs_review - ready createdAt: type: string format: date-time updatedAt: type: string format: date-time ClientCodeValue: type: string pattern: ^[A-Z][A-Z0-9]{1,31}$ example: SDCC ClientReferenceIdValue: type: string pattern: ^(?!\.{1,2}$)[A-Za-z0-9._-]{1,128}$ description: 1-128 characters; `.` and `..` alone are refused. example: SDCC-2026-00482 MatterTypeValue: type: string enum: - debt_recovery default: debt_recovery description: >- The kind of legal work instructed. Optional on write; omitted means `debt_recovery`. Always returned. MatterParty: description: >- One Matter Party: a Party's participation in this Matter through a Matter-specific role. Several Parties may hold the debtor role on one Matter; joint liability never multiplies the obligation, so `debt.outstandingAmount` remains the single Matter total. oneOf: - title: Person party type: object additionalProperties: false required: - role - type - isPrimaryLiable - name - addresses properties: role: type: string const: debtor description: Matter-specific role of this Party type: type: string const: person isPrimaryLiable: type: boolean description: >- Exactly one entry in `parties` must be `true`. The primary liable Party is the one the source file identifies as liable; it does not by itself select a correspondence recipient. name: $ref: '#/components/schemas/PersonName' dateOfBirth: type: string format: date description: >- Optional, from 1900-01-01 to today. Used to confirm identity; never returned in sync items. customerNumber: type: string maxLength: 512 addresses: type: array minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/Address' emails: type: array maxItems: 10 description: >- At most one email may be primary; the others are secondary contacts. items: $ref: '#/components/schemas/EmailContact' phones: type: array maxItems: 10 description: >- At most one phone number may be primary; the others are secondary contacts. A number may repeat only with a different extension. items: $ref: '#/components/schemas/PhoneContact' - title: Organisation party type: object additionalProperties: false required: - role - type - isPrimaryLiable - legalName - addresses properties: role: type: string const: debtor description: Matter-specific role of this Party type: type: string const: organisation isPrimaryLiable: type: boolean description: Exactly one entry in `parties` must be `true`. legalName: type: string minLength: 1 maxLength: 200 companyNumber: type: string pattern: ^[A-Za-z0-9]{1,20}$ description: Optional company registration number, for example a CRO number. tradingNames: type: array maxItems: 5 default: [] description: Names the organisation trades under, besides its legal name. items: type: string minLength: 1 maxLength: 200 customerNumber: type: string maxLength: 512 addresses: type: array minItems: 1 maxItems: 10 items: $ref: '#/components/schemas/Address' emails: type: array maxItems: 10 description: >- At most one email may be primary; the others are secondary contacts. items: $ref: '#/components/schemas/EmailContact' phones: type: array maxItems: 10 description: >- At most one phone number may be primary; the others are secondary contacts. A number may repeat only with a different extension. items: $ref: '#/components/schemas/PhoneContact' Debt: type: object additionalProperties: false required: - currency - outstandingAmount properties: type: $ref: '#/components/schemas/DebtTypeValue' currency: type: string pattern: ^[A-Z]{3}$ example: EUR outstandingAmount: $ref: '#/components/schemas/Money' Instruction: type: object additionalProperties: false properties: summary: type: string maxLength: 2000 historyNotes: type: string maxLength: 10000 requestedAction: type: string enum: - letter_before_action - issue_proceedings - review_only ProblemDetails: type: object additionalProperties: false required: - type - title - status - detail - code if: properties: code: const: rate_limited required: - code else: required: - requestId properties: type: type: string format: uri-reference title: type: string status: type: integer minimum: 400 maximum: 599 detail: type: string code: type: string description: >- Stable machine-readable error code. Client software branches on this value; it never parses detail. The same codes appear in `errors[].code`, where field-level codes such as required_field, unknown_field and unsupported_enum point at what to correct. enum: - balance_mismatch - capacity_limited - card_number_detected - client_not_configured - client_scope_denied - currency_mismatch - effective_date_out_of_range - identity_mismatch - invalid_credentials - invalid_field - invalid_page_token - invalid_precondition - invalid_request - invisible_character - matter_closed - method_not_allowed - not_found - opening_balance_change_not_allowed - partner_writes_paused - payload_too_large - payment_observation_conflict - precondition_failed - precondition_required - primary_liable_party_required - rate_limited - recipient_rebind_required - request_timeout - required_field - source_write_conflict - stale_lifecycle_precondition - stale_lifecycle_retry - unavailable - unknown_field - unprocessable_entity - unsupported_enum - unsupported_media_type - usable_address_required example: client_scope_denied instance: type: string format: uri-reference description: >- Optional server-issued opaque occurrence URI; never contains request path or query values, or partner identifiers requestId: type: string description: >- Equals the `X-Request-Id` header. Present on every application response; absent only on a `rate_limited` response answered by the network edge before the request reaches the application. errors: type: array maxItems: 50 description: At most 50 field-level entries, in the order found. items: type: object additionalProperties: false required: - pointer - code properties: pointer: type: string code: type: string example: type: https://api.casepathiq.com/problems/usable_address_required title: Usable address required status: 400 detail: >- Each Party needs exactly one usable correspondence address that meets the letter minimum. code: usable_address_required requestId: 6f2c1b8e-3a41-4f43-9a55-6b2f0b1b7c10 errors: - pointer: /parties/1/addresses code: usable_address_required PersonName: type: object additionalProperties: false required: - givenName - familyName properties: givenName: type: string minLength: 1 maxLength: 120 middleNames: type: array maxItems: 3 items: type: string minLength: 1 maxLength: 120 familyName: type: string minLength: 1 maxLength: 120 Address: type: object additionalProperties: false required: - type description: >- A create requires exactly one correspondence address with a valid IE Eircode or line1 plus city and/or state. properties: type: type: string enum: - correspondence - rated_property - registered - site line1: type: string maxLength: 512 line2: type: string maxLength: 512 city: type: string maxLength: 512 state: type: string maxLength: 512 postalCode: type: string maxLength: 16 countryCode: type: string enum: - AD - AE - AF - AG - AI - AL - AM - AO - AQ - AR - AS - AT - AU - AW - AX - AZ - BA - BB - BD - BE - BF - BG - BH - BI - BJ - BL - BM - BN - BO - BQ - BR - BS - BT - BV - BW - BY - BZ - CA - CC - CD - CF - CG - CH - CI - CK - CL - CM - CN - CO - CR - CU - CV - CW - CX - CY - CZ - DE - DJ - DK - DM - DO - DZ - EC - EE - EG - EH - ER - ES - ET - FI - FJ - FK - FM - FO - FR - GA - GB - GD - GE - GF - GG - GH - GI - GL - GM - GN - GP - GQ - GR - GS - GT - GU - GW - GY - HK - HM - HN - HR - HT - HU - ID - IE - IL - IM - IN - IO - IQ - IR - IS - IT - JE - JM - JO - JP - KE - KG - KH - KI - KM - KN - KP - KR - KW - KY - KZ - LA - LB - LC - LI - LK - LR - LS - LT - LU - LV - LY - MA - MC - MD - ME - MF - MG - MH - MK - ML - MM - MN - MO - MP - MQ - MR - MS - MT - MU - MV - MW - MX - MY - MZ - NA - NC - NE - NF - NG - NI - NL - 'NO' - NP - NR - NU - NZ - OM - PA - PE - PF - PG - PH - PK - PL - PM - PN - PR - PS - PT - PW - PY - QA - RE - RO - RS - RU - RW - SA - SB - SC - SD - SE - SG - SH - SI - SJ - SK - SL - SM - SN - SO - SR - SS - ST - SV - SX - SY - SZ - TC - TD - TF - TG - TH - TJ - TK - TL - TM - TN - TO - TR - TT - TV - TW - TZ - UA - UG - UM - US - UY - UZ - VA - VC - VE - VG - VI - VN - VU - WF - WS - YE - YT - ZA - ZM - ZW default: IE EmailContact: type: object additionalProperties: false required: - address - type - isPrimary properties: address: type: string format: email maxLength: 254 type: type: string enum: - personal - work - other isPrimary: type: boolean PhoneContact: type: object additionalProperties: false required: - number - type - isPrimary properties: number: type: string pattern: ^\+[1-9]\d{7,14}$ type: type: string enum: - mobile - landline - work - other extension: type: string pattern: ^[0-9]{1,6}$ description: Optional extension for a landline or work number. isPrimary: type: boolean DebtTypeValue: type: string enum: - commercial_rates - rent_arrears - housing_loan - other description: The kind of debt being recovered. Optional. Money: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ maxLength: 15 example: '1250.00' responses: MatterSuccess: description: Current partner-facing Matter representation headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/MatterResponse' BadRequest: description: Validation, schema, enum, money or letter-minimum failure headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' Unauthorized: description: >- Missing, malformed, expired, revoked or unknown partner key, an invalid edge identity, or a network address outside the key's allowed ranges (invalid_credentials). The same neutral 401 is returned for every cause. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' Forbidden: description: >- The key cannot act for this Client code (client_scope_denied). Unknown, ungranted and key-restricted Client codes share this response. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' NotFound: description: No such Matter or Payment observation in this scope (neutral) headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' RequestTimeout: description: >- The request body was not received within 10 seconds (request_timeout). Nothing was changed. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' Conflict: description: Balance, payment, lifecycle or retained Source conflict headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' PreconditionFailed: description: >- The supplied `If-Match` tag is not the current one, or `If-None-Match: *` was sent for a Matter that already exists (precondition_failed). Nothing is mutated and no downstream action runs. Read the current Matter and decide again; never replay old content under a fresh tag. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' PayloadTooLarge: description: The request body exceeds 256 KiB (payload_too_large). headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' UnsupportedMediaType: description: >- The Content-Type is not accepted (unsupported_media_type). Use `application/json`, or `application/merge-patch+json` for PATCH. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' PreconditionRequired: description: >- A conditional write is required and no precondition was supplied (precondition_required): `If-None-Match: *` to create, `If-Match` to update. Nothing is mutated. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' TooManyRequests: description: >- Per-key rate limit (rate_limited), per-Matter daily write cap or pilot capacity limit (capacity_limited). Wait for Retry-After before retrying. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' ServiceUnavailable: description: >- Transient or fenced failure (unavailable), or Partner API writes paused by the platform (partner_writes_paused; reads still work). Retry unchanged content after Retry-After. headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' Problem: description: RFC 9457 Problem Details error headers: X-Request-Id: $ref: '#/components/headers/RequestId' Cache-Control: $ref: '#/components/headers/CacheControl' content: application/problem+json: schema: $ref: '#/components/schemas/ProblemDetails' headers: RequestId: description: CasePath IQ-generated support correlation identifier schema: type: string example: req_01JEXAMPLE CacheControl: description: Sensitive responses are not cacheable schema: type: string const: no-store ETag: description: >- Strong entity-tag of the partner-facing Matter representation. It changes whenever any visible field changes — Source facts, authoritative balance, lifecycle state or intake status — not only when the Source revision advances. schema: type: string example: '"m1-7f3a9c2b"' RetryAfter: description: Seconds to wait before retrying this request schema: type: integer minimum: 1 example: 30 securitySchemes: PartnerKey: type: http scheme: bearer bearerFormat: CasePath IQ partner key description: >- Environment-specific Integration key. Never paste a live key into documentation tooling. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.