Reference

Intake

Fetch the clinical intake your patient's clinic uses, submit the answers, and see the patient move into clinical review. Completing intake does not approve the patient.

Intake is required, not optional

A new patient starts at intake_pending. A clinician should not prescribe without the intake. This API lets you submit it. It does not let you approve the patient or book a consultation.

Why intake exists#

The intake is the medical questionnaire the clinician reviews before prescribing. It is per clinic and per patient, not per product. The product's purchase gate is a separate, coarser signal.

A new patient created with POST /v1/patients reads as intake_pending. The accepted value on the create response is the request status, not the patient lifecycle. Read the patient or this endpoint to see the real status.

Read the required form#

GET/v1/patients/{id}/intakeScope: patients:read

The response carries the forms adopted by the patient's clinic, their questions, the patient status and the last submission summary.

json

{
  "ok": true,
  "request_id": "…",
  "patient_id": "…",
  "clinic_id": "…",
  "patient_status": "intake_pending",
  "forms": [
    {
      "id": "…",
      "slug": "caelo-sandbox-intake",
      "name": "Caelo Sandbox Intake",
      "description": "Synthetic form for partner API testing. Do not use with real patients.",
      "intro_text": "This form exists only in the Caelo sandbox.",
      "tracks": [],
      "requires_video_consult": false,
      "questions": [
        {
          "key": "consent",
          "prompt": "I consent to a telehealth evaluation.",
          "type": "consent",
          "required": true,
          "position": 1,
          "options": [],
          "rows": [],
          "config": {},
          "show_when": []
        }
      ]
    }
  ],
  "submission": null
}

tracks says which clinical track a form belongs to. An empty list means general. requires_video_consult is the form's clinical setting; it does not mean you book the consult. show_when uses the answer key of the controlling question.

If the key holds more than one clinic and the patient is linked to more than one, pass ?clinic_id=…. Without it the request is 400.

Submit the answers#

POST/v1/patients/{id}/intakeScope: patients:write

Idempotency-Key is required. The body carries the form, the answers, the attestation and the time you verified the patient's identity.

http

POST /api/partner/v1/patients/{id}/intake
Authorization: Bearer tfk_test_…
Idempotency-Key: intake-2026-11-09-0001
Content-Type: application/json

{
  "form_slug": "caelo-sandbox-intake",
  "form_version": 1,
  "answers": {
    "consent": true,
    "medical_history": "…",
    "medications": "…",
    "allergies": "…",
    "signature": "Patient full name"
  },
  "attestation": {
    "accepted": true,
    "text": "I consent to a telehealth evaluation.",
    "version": "1"
  },
  "identity_verified_at": "2026-11-09T12:00:00Z",
  "clinic_id": "…"
}

Field	Required	Notes
`form_slug`	Yes	A form returned by the read endpoint.
`form_version`	No	Defaults to 1. The submission records it.
`answers`	Yes	Keyed by question `key`. Hidden branches are dropped; unknown keys are refused.
`attestation.accepted`	Yes	Must be `true`. You are attesting the patient consented.
`identity_verified_at`	Yes	ISO 8601 instant with a zone. When you verified the patient's identity.
`clinic_id`	No	Only when the key holds several clinics and the patient is linked to several.

The response is 201 for a new submission and 200 for a replay:

json

{
  "ok": true,
  "request_id": "…",
  "submission": {
    "id": "…",
    "form_slug": "caelo-sandbox-intake",
    "submitted_at": "2026-11-09T12:00:00.000Z",
    "status": "accepted"
  },
  "patient_status": "intake_complete",
  "requires_video_consult": false,
  "idempotent": false
}

What happens after#

The patient moves to intake_complete.
A TRIMFITT clinician reviews the intake.
The clinician either approves the patient for ordering or schedules a consultation, depending on the product and the clinical protocol.
Read the patient or this endpoint to see the next status.

No auto-approval

A completed intake is not an approval. The partner cannot set approved. The order you create is still a referral and still goes to clinical review.

Patient status#

Status	Meaning
`intake_pending`	No clinical intake yet.
`intake_complete`	Intake submitted, clinician review pending.
`consultation_scheduled`	A consultation is required and booked.
`consultation_completed`	The consultation happened; review continues.
`approved`	Approved for ordering.
`not_approved`	Clinically declined.
`inactive`	Not currently active.
`archived`	Archived by staff.
`deleted`	Tombstoned; the partner routes return 404.

Errors#

Status	Code	Meaning
400	`validation_failed`	Bad body, missing key, invalid answer, wrong form version, or a multi-clinic patient without `clinic_id`.
403	`intake_not_enabled`	Live runtime and the BAA, DPA or intake switch is missing.
404	`not_found`	The patient is not linked to the clinic, or the form is not adopted by the clinic.
409	`idempotency_conflict`	Same key, different body.
503	`service_unavailable`	The credential or intake gate could not be checked. Retry with backoff.

Sandbox and production#

The sandbox uses a synthetic form, caelo-sandbox-intake. It is adopted by the Caelo sandbox clinic and must not be used with real patients. Production forms are clinical content and are configured by the clinical team.

Live intake requires the signed BAA and DPA and the separate intake switch. The sandbox bypasses the gate. The intake switch is separate from the order switch.