> ## Documentation Index > Fetch the complete documentation index at: https://docs.maxcare.ai/llms.txt > Use this file to discover all available pages before exploring further. # Record that a deposit paid one of your remittances > Claims `amount` of a credit deposit for the app's own remittance `externalRef`. It never changes the platform's ERA reconciliation. `201` creates the match; replaying the same `Idempotency-Key` with the same body answers `200` with the original match, and with a different body `409 idempotency_key_reused`. `409 deposit_already_allocated` when a confirmed or manual ERA reconciliation, a card payout or another installed app's active match holds the deposit (`data.heldBy`); `409 over_allocated` when this app's active matches on the deposit would exceed its amount (`data.remainingAmount`); `409 conflict` when the deposit is excluded (superseded, duplicate or removed: match the row it points to; if that row is excluded too, no live row carries the money and there is nothing to match) or when `externalRef` already has an active match. An unknown, other-organization or debit transaction answers `404`. ## OpenAPI ````yaml /openapi-v4.json post /deposit-matches openapi: 3.0.0 info: title: Max AI Public API description: API for third-party marketplace apps version: '4.0' contact: {} servers: - url: https://api.maxcare.ai/v4 security: [] tags: [] paths: /deposit-matches: post: tags: - Deposit matches summary: Record that a deposit paid one of your remittances description: >- Claims `amount` of a credit deposit for the app's own remittance `externalRef`. It never changes the platform's ERA reconciliation. `201` creates the match; replaying the same `Idempotency-Key` with the same body answers `200` with the original match, and with a different body `409 idempotency_key_reused`. `409 deposit_already_allocated` when a confirmed or manual ERA reconciliation, a card payout or another installed app's active match holds the deposit (`data.heldBy`); `409 over_allocated` when this app's active matches on the deposit would exceed its amount (`data.remainingAmount`); `409 conflict` when the deposit is excluded (superseded, duplicate or removed: match the row it points to; if that row is excluded too, no live row carries the money and there is nothing to match) or when `externalRef` already has an active match. An unknown, other-organization or debit transaction answers `404`. operationId: DepositMatchesPublicController_create parameters: - name: idempotency-key required: true in: header schema: type: string - name: Idempotency-Key in: header description: >- Unique per match for this installation, kept permanently; at most 255 characters required: true schema: type: string - name: X-Organization-Id in: header required: true schema: type: string description: Target clinic organization ID requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateDepositMatchBody' responses: '200': description: Success '201': description: Created content: application/json: schema: $ref: '#/components/schemas/CreateDepositMatchSuccessResponse' '400': description: Missing or invalid request parameter content: application/json: schema: $ref: '#/components/schemas/PublicApiBadRequestResponse' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/PublicApiUnauthorizedResponse' '403': description: Insufficient scope content: application/json: schema: $ref: '#/components/schemas/PublicApiForbiddenResponse' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/PublicApiNotFoundResponse' '409': description: Resource conflict (e.g. editing a signed note) content: application/json: schema: $ref: '#/components/schemas/PublicApiConflictResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/PublicApiRateLimitResponse' security: - api-key: [] components: schemas: CreateDepositMatchBody: type: object properties: bankTransactionId: type: string description: >- The deposit this remittance arrived in (`btx_…`), from `GET /bank-transactions` example: btx_5f1c0000000040000000000000000001 kind: type: string enum: - pharmacy_remittance - other description: What the app's remittance is externalRef: type: string description: >- The app's own identifier for the remittance this deposit paid. One active match per `externalRef` per installation. minLength: 1 maxLength: 200 example: remit-2026-10-0042 amount: type: string description: >- Amount of the deposit allocated to this remittance: a positive decimal string, at most two decimals example: '1250.00' required: - bankTransactionId - kind - externalRef - amount CreateDepositMatchSuccessResponse: type: object properties: code: type: string description: Response code example: success data: $ref: '#/components/schemas/ExternalDepositMatchResponse' required: - code - data PublicApiBadRequestResponse: type: object properties: code: type: string description: Error code example: bad_request message: type: string description: Human-readable error message example: '''id'' must be a valid UUID' trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiUnauthorizedResponse: type: object properties: code: type: string description: Error code example: unauthorized message: type: string description: Human-readable error message example: Invalid or missing API key trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiForbiddenResponse: type: object properties: code: type: string description: Error code example: forbidden message: type: string description: Human-readable error message example: Insufficient scope trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiNotFoundResponse: type: object properties: code: type: string description: Error code example: not_found message: type: string description: Human-readable error message example: Resource not found trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiConflictResponse: type: object properties: code: type: string description: Error code example: conflict message: type: string description: Human-readable error message example: Cannot edit a signed note trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id PublicApiRateLimitResponse: type: object properties: code: type: string description: Error code example: rate_limit_exceeded message: type: string description: Human-readable error message example: Rate limit exceeded. Maximum 1000 requests per 60 seconds. trace_id: type: string description: Trace ID for debugging example: 550e8400-e29b-41d4-a716-446655440000 required: - code - message - trace_id ExternalDepositMatchResponse: type: object properties: id: type: string description: Deposit match ID (`dpm_…`) example: dpm_5f1c0000000040000000000000000002 bankTransactionId: type: string description: The deposit (`btx_…`) example: btx_5f1c0000000040000000000000000001 kind: type: string enum: - pharmacy_remittance - other externalRef: type: string example: remit-2026-10-0042 amount: type: string description: Allocated amount, two decimals example: '1250.00' status: type: string enum: - active - revoked createdAt: type: string description: ISO 8601 timestamp example: '2026-10-19T14:03:00.000Z' required: - id - bankTransactionId - kind - externalRef - amount - status - createdAt securitySchemes: api-key: scheme: bearer bearerFormat: JWT type: http description: Marketplace API key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.