Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.have-foresight.app/llms.txt

Use this file to discover all available pages before exploring further.

This walkthrough creates a patient, verifies their insurance eligibility, and returns the normalized benefit response — the smallest end-to-end loop that exercises auth, request shape, and our response envelope.

​
1. Get an API key

In the Foresight dashboard, go to Settings → API keys → Create key. Choose the scopes you need (least-privilege; for this walkthrough you need patients:write and eligibility:read) and copy the returned key.
API keys are shown once at creation. Store them in a secrets manager (AWS Secrets Manager, Doppler, 1Password). Never commit them to a repo or embed them in client-side code.
API keys begin with the prefix fsk_ followed by a 64-character random body.

​
2. Set environment variables

export FORESIGHT_API_KEY="fsk_live_..."
export FORESIGHT_BASE_URL="https://api.have-foresight.app/v1"
For the staging sandbox, swap to: 
export FORESIGHT_BASE_URL="https://api.staging.have-foresight.app/v1"

​
3. Create a patient

curl -X POST "$FORESIGHT_BASE_URL/patients" \
  -H "X-API-Key: $FORESIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "firstName": "Jamie",
    "lastName": "Rivera",
    "dateOfBirth": "1985-04-12",
    "biologicalSex": "female",
    "primaryAddress": {
      "line1": "100 Main St",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701"
    }
  }'
A successful response returns HTTP 201 Created: 
{
  "data": {
    "id": "pat_01J5K8XQ7M3N5R8T2W6Y9Z1B4D",
    "firstName": "Jamie",
    "lastName": "Rivera",
    "dateOfBirth": "1985-04-12",
    "biologicalSex": "female",
    "createdAt": "2026-05-03T19:42:11.402Z"
  }
}
Save the id — you’ll need it in the next step.

​
4. Attach an insurance policy

curl -X POST "$FORESIGHT_BASE_URL/insurance-policies" \
  -H "X-API-Key: $FORESIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "patientId": "pat_01J5K8XQ7M3N5R8T2W6Y9Z1B4D",
    "payerId": "pay_aetna",
    "memberId": "W123456789",
    "groupNumber": "GRP-0042",
    "subscriberRelationship": "self",
    "effectiveDate": "2026-01-01"
  }'

​
5. Verify eligibility

curl -X POST "$FORESIGHT_BASE_URL/insurance-policies/validate" \
  -H "X-API-Key: $FORESIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "insurancePolicyId": "pol_01J5K8XR2N4P6S8V1X3Z5A7C9E",
    "serviceDate": "2026-05-15",
    "serviceTypes": ["medical_care", "prescription_drug"]
  }'
The response includes the raw 271 transaction, normalized benefits (copay, deductible, coinsurance, OOP max), and a status of eligible, ineligible, or needs_review.

​
What’s next

Submit a prior authorization

Walk through a full PA submission, including answering payer questions.

Submit your first claim

From draft to submission to remittance posting.

Subscribe to webhooks

Get notified when claim status, PA decisions, or denials change.

Browse the full reference

Every endpoint, parameter, and response shape.