curl --request POST \
  --url https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/invoices/{invoiceId}/payee \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'If-Match: <if-match>' \
  --data '
{
  "actionId": "3c5d7e9f-1a2b-4c4d-8e6f-7a8b9c0d1e2f",
  "to": "550e8400-e29b-41d4-a716-446655440210"
}
'

{
  "journalIds": [
    "3c5d7e9f-1a2b-4c4d-8e6f-7a8b9c0d1e2f"
  ],
  "invoice": {
    "id": "550e8400-e29b-41d4-a716-446655440700",
    "invoiceNumber": "INV-389538-455",
    "categoryId": "550e8400-e29b-41d4-a716-446655440100",
    "status": "owed",
    "linkedEvent": {
      "id": "550e8400-e29b-41d4-a716-446655440200",
      "displayName": "Claim #1042"
    },
    "linkedPolicy": null,
    "linkedPayee": {
      "id": "550e8400-e29b-41d4-a716-446655440210",
      "entityType": "Organization",
      "displayName": "Smith & Loeb LLP"
    },
    "incurredDate": "2026-06-01",
    "dueDate": null,
    "memo": "Legal defense",
    "fieldData": null,
    "lineItems": [
      {
        "lineItemId": "550e8400-e29b-41d4-a716-446655440300",
        "lineItemTypeId": "550e8400-e29b-41d4-a716-446655440110",
        "memo": null,
        "amountCents": 10000
      }
    ],
    "totalAmountCents": 10000,
    "amountPaidCents": 0,
    "balanceDueCents": 10000,
    "paidDate": null,
    "lastPaymentDate": null,
    "voidedAt": null,
    "deletedAt": null,
    "createdAt": "2026-06-01T10:30:00.000Z",
    "updatedAt": "2026-06-12T09:00:00.000Z",
    "headJournalId": "3c5d7e9f-1a2b-4c4d-8e6f-7a8b9c0d1e2f"
  },
  "payments": []
}

Payees

Change Invoice Payee

Sets, clears, or changes the invoice’s payee — the invoice.payee_changed action. to is the new payee entity’s id, or null to clear. The previous payee (from) is recorded server-side — clients never author it. Zero ledger rows.

Precondition (422 LIVE_PAYMENTS). The invoice must have no live payments — recorded money has already been attributed to the old payee; remove the payments first (and re-record them after) to repoint a paid invoice, or use merge payee to do that per linked invoice in one call. A named target must exist (422 LINK_TARGET_MISSING).

Concurrency + idempotency. Requires If-Match (the invoice’s current headJournalId) and a client-minted actionId (identical retry → replay; different payload → 409 ACTION_ID_REUSED).

Required permission: company.payment:update

POST

api

companies

{companyId}

financials

invoices

{invoiceId}

payee

curl --request POST \
  --url https://go.aiinsurance.io/api/v1/companies/{companyId}/financials/invoices/{invoiceId}/payee \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --header 'If-Match: <if-match>' \
  --data '
{
  "actionId": "3c5d7e9f-1a2b-4c4d-8e6f-7a8b9c0d1e2f",
  "to": "550e8400-e29b-41d4-a716-446655440210"
}
'

{
  "journalIds": [
    "3c5d7e9f-1a2b-4c4d-8e6f-7a8b9c0d1e2f"
  ],
  "invoice": {
    "id": "550e8400-e29b-41d4-a716-446655440700",
    "invoiceNumber": "INV-389538-455",
    "categoryId": "550e8400-e29b-41d4-a716-446655440100",
    "status": "owed",
    "linkedEvent": {
      "id": "550e8400-e29b-41d4-a716-446655440200",
      "displayName": "Claim #1042"
    },
    "linkedPolicy": null,
    "linkedPayee": {
      "id": "550e8400-e29b-41d4-a716-446655440210",
      "entityType": "Organization",
      "displayName": "Smith & Loeb LLP"
    },
    "incurredDate": "2026-06-01",
    "dueDate": null,
    "memo": "Legal defense",
    "fieldData": null,
    "lineItems": [
      {
        "lineItemId": "550e8400-e29b-41d4-a716-446655440300",
        "lineItemTypeId": "550e8400-e29b-41d4-a716-446655440110",
        "memo": null,
        "amountCents": 10000
      }
    ],
    "totalAmountCents": 10000,
    "amountPaidCents": 0,
    "balanceDueCents": 10000,
    "paidDate": null,
    "lastPaymentDate": null,
    "voidedAt": null,
    "deletedAt": null,
    "createdAt": "2026-06-01T10:30:00.000Z",
    "updatedAt": "2026-06-12T09:00:00.000Z",
    "headJournalId": "3c5d7e9f-1a2b-4c4d-8e6f-7a8b9c0d1e2f"
  },
  "payments": []
}

Authorizations

Authorization

string

header

required

API key authentication. Send your raw API key as the Authorization header value with NO scheme prefix — Authorization: YOUR-API-KEY. Do NOT prefix it with Bearer or ApiKey, and do not use an X-API-Key header; those are not accepted.

Headers

If-Match

string<uuid>

required

The invoice's current headJournalId — the optimistic-concurrency watermark every single-invoice write after creation must send. Read it off any invoice read or write response and echo it verbatim (a bare uuid; an entity-tag dressing of it — "uuid" or W/"uuid" — is also accepted). Missing or malformed is a 400 (IF_MATCH_REQUIRED / IF_MATCH_INVALID); a stale value is a 409 IF_MATCH_CONFLICT whose body carries the current invoice. An idempotent actionId replay short-circuits BEFORE the watermark is evaluated.

Path Parameters

companyId

string<uuid>

required

Company identifier

invoiceId

string<uuid>

required

Invoice identifier

Body

application/json

actionId

string<uuid>

required

Client-minted idempotency key — becomes the action's journal id. An identical retry replays the original outcome; reuse with a different payload is 409 ACTION_ID_REUSED

string<uuid> | null

required

The new payee entity's id, or null to clear

author

string

Optional display label for the source system's author (e.g. the integrator-side user). Stamped as the journal record's display attribution; the acting principal stays the External API service user, so a label can never impersonate an in-app user. Ignored on idempotent replays

Required string length: 1 - 255

Response

The invoice with its new payee — refreshed read state

The response of every single-invoice write — refreshed read state, not an ack: the emitted journal id(s), THE invoice row (identical shape to the reads — one invoice representation everywhere; its headJournalId is the next If-Match), and the invoice's live payments. An idempotent actionId replay returns this same shape rebuilt from the original outcome, server-minted values included.

journalIds

string<uuid>[]

required

Every journal id the write emitted — the anchor action's id (the actionId you supplied) first, then any engine-minted siblings (a multi-mark payment's additional marks) and any companion the horizon rule composed (e.g. the reserve unwind of a pre-horizon eroding payment's removal, or a delete's payment sweep)

Minimum array length: 1

invoice

object

required

THE invoice representation — the same shape everywhere an endpoint returns an invoice (listing rows, the detail read, and every write's refreshed-row response). headJournalId is the invoice's current journal head — the optimistic-concurrency token subsequent writes echo back as If-Match.

Show child attributes

payments

object[]

required

The invoice's live payment marks after the write, newest first

Show child attributes

⌘I

Getting Started

User

Entities

Event Lifecycle

Policy Transactions

Financials

Rating

Notes

Tasks

Configuration Management

Company Files

Forms

Document Generation

Submission Parsing

Reference

Change Invoice Payee

Authorizations

Headers

Path Parameters

Body

Response