Clinics and agreements

Summary: send every order with a clinic, identified by your own stable clinic.external_id. A clinic is created the first time an order names it, or earlier when you enroll it with POST /clinics. If your account is partner-attested, enroll each clinic with its signed-terms attestation before its first order; if your clinics sign Axiom's agreement by e-signature, each clinic must sign it first. Otherwise its orders are refused with 422 agreement_unsigned.

Agreement modes

Your account is set up in one of three modes, which we confirm with you when it is created:

Mode	What it means for you
No per-clinic agreement	Clinics are created by their first order. If you are billed directly, you can also enroll them first, to put their contacts on file early. If your clinics are billed, enrollment through the API is not available on this mode (it is refused); clinics come from their orders.
Partner-attested	The clinic accepts Axiom's terms inside your onboarding, and you send us that acceptance with POST /clinics. Orders for a clinic without an attestation are refused. Only in this mode can you use the banking endpoints and PATCH /clinics/identity.
Axiom e-signature	Axiom sends the clinic its agreement to sign. Orders are accepted once it is signed. You cannot enroll these clinics through the API (422 axiom_boldsign_required), and you cannot change a clinic's signer details (primary contact email, signer name and title) through the API (422 signer_identity_locked_boldsign).

How an order finds its clinic

Loading diagram...

If no clinic resolves and your account has no default clinic configured, the order is created without a clinic. Always send clinic.external_id.

When an order creates a clinic, it uses the order's clinic.name (or Clinic <external_id>), npi, contact email and phone, and pricing_tier if you send one. The clinic is created before the order's later checks run, so it can exist even if that first order is refused.

Enroll a clinic

POST /api/inbound/{slug}/clinics with an Idempotency-Key. The body has two parts:

• clinic: external_id, npi, name, legal_entity_name, ein (9 digits, 12-3456789 accepted), legal_address, the primary contact's first and last name and email, billing_email, billing_phone, authorized_signer_name and authorized_signer_title, plus optional dba, primary_contact_phone and support_email. A banking block (account holder, checking or savings, bank name, ACH routing number, account number) is required, except on an account that is billed directly to you and is not partner-attested.
• attestation: version (the terms version the clinic accepted), accepted_by, accepted_at, and optional evidence (up to 2000 characters of serialized JSON: your own references, such as the user id and screen that captured the acceptance).

Unknown fields are refused. A validation error lists the field paths (fields) and a reason for each (issues); a value that fails a format check, such as a routing or account number, is not repeated back.

A successful enrollment answers 201:

{ "ok": true, "clinicId": 123, "agreementStatus": "signed", "alreadyEnrolled": false, "warnings": [] }

• alreadyEnrolled is true when the clinic already existed or this agreement version was already recorded. Re-enrolling is safe.
• In partner-attested mode the attestation is stored as a permanent record and agreementStatus is signed. A second attestation for the same version keeps the first one unchanged. When its accepted_by or accepted_at differ, the response says "attestation": "kept_existing"; a difference only in evidence is not flagged, and the new evidence is not stored.
• If your account is billed directly and is not partner-attested, banking is not needed: if you send it anyway it is ignored and warnings says so (banking_ignored_partner_billed).

Enrollment can be refused with 422 banking_requires_attestation (banking sent by an account that is not partner-attested), 422 axiom_boldsign_required, 400 banking_invalid, or 409 banking_conflict (a different bank account is already on file: change it with PUT /clinics/banking).

Keep a clinic up to date

Change	Request	Notes
Practice details	PATCH /clinics	Send clinic.external_id and only the fields that change: name, contacts, billing email and phone, signer, dba, legal_address, support_email, billing_contact_name. Send null to clear the optional ones. The response lists what actually changed in updated.
Regulated identity	PATCH /clinics/identity	Group npi, legal_entity_name, ein. Partner-attested accounts only, for an attested clinic. An NPI another of your clinics already uses is 409 npi_conflict.
Bank account	PUT /clinics/banking	Sends the whole new account. Partner-attested accounts only. Where Axiom keeps bank revisions, the new account waits beside the current one, and debits keep using the current account until Axiom makes the new one active; neither this call nor authorizing the new account (next row) switches debits by itself. Where Axiom keeps a revision history of the clinic's bank accounts, changes are limited to one per clinic per 24 hours (429 bank_change_quota). Refused with 409 ach_debit_in_flight while a debit for the clinic is being processed.
Authorize the new account	POST /clinics/banking/authorize	Confirms the clinic's newest account for ACH by repeating its routing and account number, with "authorized": true. Available once Axiom has switched it on for the clinic (409 bank_revisions_off until then). A refusal is 409 bank_authorize_refused with a reason: not_newest, account_mismatch, already_authorized, rejected or approval_pending (Axiom has not approved the account yet).

All four need an Idempotency-Key. A clinic you do not own, or one that does not exist, is 404 clinic_not_found. The identity and banking endpoints answer 422 clinic_not_attested for a clinic without a partner attestation.

Bank account numbers and tax ids are stored encrypted, are never returned by the API, and never appear in error messages.

agreement_unsigned reasons

reason	What to do
clinic_reference_missing	Send clinic.external_id on the order. This check runs first, so fixing it may then show not_attested.
not_attested	Enroll the clinic with its attestation (POST /clinics).
not_signed	The clinic has not signed the Axiom agreement yet (e-signature accounts).
clinic_unresolved	The order did not identify a single clinic. Send clinic.external_id.