Intake Gateway API

Patient intake submission, plan pricing, Stripe payment, email verification, and Canvas patient creation.

Overview

The Intake Gateway is the public-facing API that powers the React intake forms. It handles the full intake lifecycle: fetching available plans with signed pricing tokens, verifying the patient's email address via OTP, collecting payment information through Stripe, validating discount coupons, and creating patients in Canvas EMR upon final submission.

All endpoints are called directly from the browser -- there is no server-to-server HMAC authentication. The gateway relies on plan token signatures for price integrity and Zod schema validation for input safety.

Base URL

https://intake-api.yourera.com

How It Works

1. Frontend fetches plans from GET /plans, each plan includes an HMAC-signed token encoding the price
2. Patient completes the intake form, verifies their email via OTP (/verify-email/send + /verify-email/check)
3. Frontend creates a Stripe SetupIntent via POST /payment-intent and collects card details client-side
4. Optionally validates a discount code via POST /validate-coupon
5. Frontend submits the full intake via POST /submit with the signed plan token
6. Gateway validates the token signature, checks state availability and age, creates a Canvas patient, and saves the submission
7. Frontend calls POST /save-payment-info to attach the payment method to the submission

CORS & Authentication

All Intake Gateway endpoints are public. They are called directly from React intake forms running in the browser. There is no HMAC signature requirement or API key header.

CORS is configured to allow requests from the intake form origins. All endpoints accept Content-Type: application/json.

Get Plans

Request

No request body or query parameters required.

GET /plans
Host: intake-api.yourera.com

Response (200)

{
  "plans": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "intakeType": "glp-1",
      "plan": "monthly",
      "displayName": "GLP-1 Monthly Plan",
      "amountCents": 29900,
      "interval": "month",
      "token": "eyJpbnRha2VUeXBlIjoiZ2xwLTEi...<base64url>.<hex-hmac>"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "intakeType": "nad",
      "plan": "monthly",
      "displayName": "NAD+ Wellness Protocol",
      "amountCents": 17000,
      "interval": "month",
      "token": "eyJpbnRha2VUeXBlIjoibmFkIi...<base64url>.<hex-hmac>"
    }
  ]
}

Response Fields

Error Responses

Submit Intake

Request Body

address Object

Example Request

{
  "firstName": "Jane",
  "lastName": "Smith",
  "dob": "03-15-1990",
  "gender": "female",
  "email": "jane.smith@example.com",
  "phone": "(555) 123-4567",
  "state": "FL",
  "address": {
    "line1": "123 Main St",
    "line2": "Apt 4B",
    "city": "Miami",
    "state": "FL",
    "zip": "33101"
  },
  "intakeType": "glp-1",
  "planToken": "eyJpbnRha2VUeXBlIjoiZ2xwLTEi...<token>",
  "couponCode": "WELCOME50"
}

Success Response (200)

{
  "success": true,
  "submissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

Error Responses

Submission Processing Steps

1. Validate body -- Parse against intakeSubmissionSchema (Zod)
2. State check -- Reject if state is in EXCLUDED_STATES
3. Age check -- Verify DOB indicates 18+ using isOver18()
4. Verify plan token -- HMAC-SHA256 signature verification + 15-minute expiry check
5. Canvas patient -- Search by email (idempotent), create if not found
6. Save submission -- Insert into intake_submissions table
7. Queue retry -- If Canvas failed, insert into intake_retry_queue

Create Payment Intent

Request Body

Example Request

{
  "customerId": "cus_ABC123"
}

Or with an empty body (no customer association):

{}

Success Response (200)

{
  "clientSecret": "seti_1abc123_secret_xyz789",
  "setupIntentId": "seti_1abc123"
}

Response Fields

Error Responses

Validate Coupon

Request Body

Example Request

{
  "code": "WELCOME50"
}

Success Response -- Valid Coupon (200)

{
  "valid": true,
  "amountOff": 50,
  "percentOff": null
}

Success Response -- Invalid/Expired Coupon (200)

{
  "valid": false,
  "reason": "Coupon is no longer valid"
}

Success Response -- Not Found (200)

{
  "valid": false,
  "reason": "Coupon not found"
}

Response Fields

Error Responses

Send Email Verification

Request Body

Example Request

{
  "email": "jane.smith@example.com"
}

Success Response (200)

{
  "success": true,
  "message": "Verification code sent"
}

Error Responses

Check Email Verification

Request Body

Example Request

{
  "email": "jane.smith@example.com",
  "code": "482910"
}

Success Response (200)

{
  "verified": true
}

Failure Response (200)

{
  "verified": false,
  "error": "invalid_code"
}

Verification Error Codes

Error Responses

Save Payment Info

Request Body

Example Request

{
  "submissionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "paymentMethodId": "pm_1abc123",
  "setupIntentId": "seti_1abc123"
}

Success Response (200)

{
  "success": true
}

Error Responses

Plan Token Security

Plan tokens are the primary mechanism preventing price tampering. Since the intake form runs in the browser and there is no HMAC authentication on API calls, a malicious client could attempt to submit a lower price. Plan tokens make this impossible.

How It Works

1. When GET /plans is called, the server creates a token for each plan by signing a payload containing the intakeType, plan, amountCents, and a timestamp with HMAC-SHA256 using a server-only secret (PLAN_TOKEN_SECRET).
2. The frontend receives the plans with their tokens and displays pricing to the user.
3. At submission, the frontend sends the planToken back in the request body.
4. The server verifies the HMAC signature using crypto.timingSafeEqual (constant-time comparison, preventing timing attacks) and checks the 15-minute expiry.

Token Format

// Format: base64url(payload).hex(hmac-sha256)

// Payload (JSON, base64url-encoded):
{
  "intakeType": "glp-1",
  "plan": "monthly",
  "amountCents": 29900,
  "issuedAt": 1710900000000
}

// Signing:
HMAC-SHA256(PLAN_TOKEN_SECRET, base64url(payload))

Security Properties

Email Verification Flow

Email verification uses a 6-digit OTP (one-time password) flow. The code is generated using crypto.randomInt for cryptographic randomness and stored in an in-memory verification store keyed by email address.

Flow Diagram

// 1. Frontend requests OTP
POST /verify-email/send  { email: "jane@example.com" }
// Server generates 6-digit code, sends via email, stores in memory

// 2. User enters OTP from email
POST /verify-email/check { email: "jane@example.com", code: "482910" }
// Server verifies code, returns { verified: true }

Rate Limiting & Expiry Rules

Canvas Patient Creation

When an intake is submitted, the gateway creates a patient in Canvas EMR using the FHIR Patient API. The creation is idempotent -- it first searches by email to avoid duplicates.

Idempotent Creation

1. Search: Query Canvas for an existing patient with the submitted email address
2. If found: Use the existing patient's id -- no new patient created
3. If not found: Build a FHIR Patient resource and create it via the Canvas API

FHIR Patient Mapping

Intake form data is mapped to a FHIR Patient resource:

Example FHIR Patient Resource

{
  "resourceType": "Patient",
  "name": [{
    "given": ["Jane"],
    "family": "Smith",
    "use": "official"
  }],
  "birthDate": "1990-03-15",
  "gender": "female",
  "telecom": [
    { "system": "phone", "value": "5551234567", "use": "mobile" },
    { "system": "email", "value": "jane.smith@example.com" }
  ],
  "address": [{
    "use": "home",
    "line": ["123 Main St", "Apt 4B"],
    "city": "Miami",
    "state": "FL",
    "postalCode": "33101"
  }]
}

Retry Queue

If Canvas patient creation fails (network error, API timeout, etc.), the submission is still saved with status pending_canvas and a record is inserted into the intake_retry_queue table.

Canvas Retry Worker

The Canvas retry worker is fully functional and runs automatically on a 60-second interval after the intake gateway starts. It picks up all pending entries in the intake_retry_queue table and attempts to create the patient in Canvas.

Retry Policy

• Max attempts: 3 -- after 3 failed attempts, the entry is marked as failed (manual intervention needed)
• Interval: Worker polls every 60 seconds
• Idempotent: Each retry checks for an existing patient by email before creating, preventing duplicates

Retry Flow

1. Fetch pending entries: Query intake_retry_queue for rows with status = 'pending'
2. Look up submission: Retrieve the full submission data using submissionId
3. Build FHIR Patient: Map the submission data to a FHIR Patient resource (same mapping as initial creation)
4. Check for existing patient: Search Canvas by email to avoid duplicates
5. Create patient: If no existing patient found, create via Canvas FHIR API
6. On success: Update the submission with canvasPatientId, set submission status to submitted, mark retry entry as completed
7. On failure: Increment attempts, record the error in lastError. If attempts reach 3, mark as failed; otherwise leave as pending for next cycle

Stripe Integration

The Intake Gateway uses Stripe for payment collection and discount validation. It follows the SetupIntent + off-session PaymentIntent pattern: the patient's card is saved during intake, and charged later when a prescription is approved by a clinician.

Payment Flow

1. SetupIntent: Frontend calls POST /payment-intent to get a clientSecret
2. Collect card: Stripe Elements uses the clientSecret to securely collect card details client-side
3. Save method: After Stripe confirms the setup, frontend calls POST /save-payment-info with the paymentMethodId
4. Charge later: When the prescription is approved, the orchestrator calls chargePaymentHold(canvasPatientId) to create an off-session PaymentIntent and charge the saved card

Coupon Validation

Discount codes are validated against Stripe's Coupon API. The coupon ID in Stripe Dashboard must exactly match the code the user enters. There are two discount types:

Environment Variables

State Restrictions

YourEra does not currently service all US states. The gateway enforces state restrictions at submission time -- intakes from excluded states are rejected with a 400 error.

Excluded States

The excluded list is defined as EXCLUDED_STATES = ['MN', 'CA', 'TX', 'AR', 'OK'] in validation.ts. The check uses a Set lookup for O(1) performance.

Age Verification

All patients must be at least 18 years old. The isOver18() function parses the DOB string (MM-DD-YYYY), computes the exact age accounting for month and day boundaries, and rejects minors with a 400 error.

Database Schema

The Intake Gateway uses four tables, defined with Drizzle ORM in schema.ts.

intake_plans

Active plan definitions. Each plan maps to an intake type, price, and billing interval.

intake_submissions

Every intake submission is stored here, regardless of Canvas creation outcome.

intake_retry_queue

Queued retries for failed Canvas patient creations.

intake_verification_codes

Persistent storage for email OTP codes (schema defined for future use; current implementation uses in-memory store).

intake_api_keys

API keys for future authenticated access (not currently used by the public intake routes).