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.

A prior authorization (PA) flow has up to four phases: submit, wait for status, answer payer questions, and resolve. The Foresight API exposes each phase as a discrete endpoint so you can plug in at any point.

​
Lifecycle states

draft → submitted → in_review → (questions ↻) → approved | denied | manual_review
                                                                           ↓
                                                               admin_decision
StateMeaning
draftCreated but not submitted.
submittedSent to the payer; awaiting first response.
in_reviewPayer is reviewing.
questionsPayer sent clinical/coverage questions; needs answers.
approvedApproved by the payer.
deniedDenied by the payer; can be appealed.
manual_reviewForesight flagged for human review (e.g. confidence too low).
Subscribe to prior_auth.* webhook events to react to state transitions instead of polling.

​
1. Submit

curl -X POST "$FORESIGHT_BASE_URL/prior-authorizations" \
  -H "X-API-Key: $FORESIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "patientId": "pat_...",
    "insurancePolicyId": "pol_...",
    "clinicianId": "cln_...",
    "diagnosisCodes": ["E11.65"],
    "requestedServices": [
      { "cptCode": "J3490", "ndc": "00069-0291-30", "quantity": 1 }
    ],
    "clinicalRationale": "Patient has type 2 diabetes with..."
  }'
Returns pa_... and an initial state of submitted (or draft if the payer integration is async).

​
2. Track status

Either subscribe to webhooks (preferred) or poll: 
GET /v1/prior-authorizations/{pa_id}/status

​
3. Answer payer questions

When status becomes questions, fetch them: 
GET /v1/prior-authorizations/{pa_id}/questions
Then submit answers: 
POST /v1/prior-authorizations/{pa_id}/questions/{question_id}
For LLM-suggested answers (Foresight pre-fills suggestions where it can), either accept directly or override: 
POST /v1/prior-authorizations/{pa_id}/approve-answer

​
4. Provider review and decision

If your team requires clinician sign-off before submission, use the provider-review endpoints:
  • GET /v1/prior-authorizations/{id}/provider-review
  • POST /v1/prior-authorizations/{id}/provider-review/answers
  • POST /v1/prior-authorizations/{id}/provider-review/decision

​
5. Manual review and retry

If a PA enters manual_review (low confidence, conflicting data, etc.):
  • POST /v1/prior-authorizations/{id}/resolve-manual-review — submit a human decision.
  • POST /v1/prior-authorizations/{id}/retry — re-attempt automated submission after fixing input data.

​
Reference

See the full Prior authorization API reference.