> ## Documentation Index
> Fetch the complete documentation index at: https://docs.scan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Build with AI

> Copy-paste prompts and machine-readable pages for building a Scan.com Partner API integration in Cursor, Claude, or ChatGPT. Start from the published spec.

Every page on this site is available as plain markdown, and the full contract is
published as OpenAPI. Point a coding agent at them, paste one of the flow
prompts below, and it can build against the sandbox without guessing at field
names.

## Get started

**1. Get sandbox keys**

Create a token from [Get API keys](https://admin.staging.scan.com/partner/api_access).
Sandbox data is synthetic, so no PHI leaves your machine while you build.

**2. Point your agent at the docs**

Add the [agent instructions](#add-it-to-your-agent) to a Cursor rule,
Claude skill, or the first message of a chat.

**3. Paste a flow prompt**

Start with [First referral, end to end](#first-referral-end-to-end), then
add webhooks and status tracking.

> [!WARNING]
>
> Build against the sandbox only. Do not paste production tokens or real
> patient data into an AI tool unless your organization has a BAA that covers
> it. See [Security and PHI](https://docs.scan.com/guides/security-and-phi.md). Review and test
> generated code before it runs in production.

## AI-friendly resources

> [card] [OpenAPI contract](https://docs.scan.com/openapi.yaml)
>
> Every endpoint, parameter, and schema. Use it when the agent generates
> requests, clients, or validators.

> [card] [llms.txt](https://docs.scan.com/llms.txt)
>
> An index of every page with a one-line description. Many agents look for it
> on their own.

> [card] [llms-full.txt](https://docs.scan.com/llms-full.txt)
>
> The full text of every page in one file. Use it when the agent needs the
> rules behind the endpoints, such as status, webhooks, and errors.

> [card] [Markdown per page](https://docs.scan.com/guides/quickstart.md)
>
> Add `.md` to any page URL. Use it when a token limit rules out the full
> file.

> [card] Copy page menu
>
> The menu at the top of every page copies it as markdown or opens it in
> ChatGPT, Claude, Perplexity, Cursor, or VS Code.

> [card] MCP server
>
> `https://docs.scan.com/mcp` lets an MCP client search these docs. Connect
> it from the Copy page menu.

## Add it to your agent

Save this as a Cursor rule or Claude skill so every session starts with it.

```text theme={"dark"}
You have access to the Scan.com Partner API v2 documentation:
- Full docs: https://docs.scan.com/llms-full.txt
- Page index: https://docs.scan.com/llms.txt
- OpenAPI: https://docs.scan.com/openapi.yaml
Use the sandbox host https://api.staging.scan.com/api/v2 only.
Authenticate with "Authorization: Bearer $SCAN_API_TOKEN" and read the token from the environment.
Consult these before writing any Scan.com integration code.
```

## Flow prompts

Each prompt names the pages to read, the calls in order, and the rules agents
most often get wrong. Replace the language in the first line with your own.

### First referral, end to end

```text theme={"dark"}
Using the Scan.com Partner API v2 sandbox, write a script in <language> that takes one synthetic patient from referral to booking.

Read first:
- https://docs.scan.com/guides/quickstart.md
- https://docs.scan.com/guides/submit-a-medical-referral.md
- https://docs.scan.com/guides/submit-medical-questions.md
- https://docs.scan.com/guides/submit-preferred-times.md
- https://docs.scan.com/guides/submit-a-booking.md
- https://docs.scan.com/openapi.yaml

Steps, in order:
1. POST /testing/fixtures and keep cpt_code_id, icd10_code_id, and body_part_id.
2. POST /referrals with order_form (PDF data URL), injury_type, incident_date, patient, and visits[].orders[].cpt_code_id.
3. GET then PUT /referrals/{referral_id}/medical_questionnaire.
4. POST /referrals/{referral_id}/scheduling_preferences.
5. POST /referrals/{referral_id}/book.
6. GET /referrals/{referral_id} and print visits[].status.

Rules:
- Base URL https://api.staging.scan.com/api/v2, token from SCAN_API_TOKEN.
- Use ids from /testing/fixtures. Do not hardcode catalog ids.
- Do not send a modality string. cpt_code_id infers it.
- On an error, log type, code, and request_id. Do not retry 4xx.
```

### Webhook receiver

```text theme={"dark"}
Build a webhook endpoint in <language/framework> for Scan.com Partner API v2 events.

Read first:
- https://docs.scan.com/guides/webhooks.md
- https://docs.scan.com/webhooks/status-changed.md
- https://docs.scan.com/guides/testing-and-sandbox.md

Requirements:
- Read the raw body before parsing JSON.
- Verify X-Scan-Signature: HMAC-SHA256 of "<timestamp>.<raw_body>" with the signing secret. The header can hold several v1= values during rotation; accept a match on any of them.
- Reject timestamps older than five minutes.
- Route on X-Scan-Event: visit.status_changed, notification.status_changed, referral.auto_book_completed.
- Dedupe visit and notification events on event_id. Make auto-book handling idempotent on auto_book_request.id and its terminal status.
- Delivery is at least once and not ordered. After an event, GET the referral and treat visits[].status as the source of truth.
- Return 2xx quickly and do the work in a background job.
- Test with POST https://api.staging.scan.com/api/v2/testing/events and {"event_name":"visit.status_changed"}.
```

### Status tracking

```text theme={"dark"}
Add Scan.com referral status tracking to my <language> integration.

Read first:
- https://docs.scan.com/guides/track-referral-status.md
- https://docs.scan.com/guides/objects.md
- https://docs.scan.com/guides/testing-and-sandbox.md

Requirements:
- Key integration logic off visits[].status, not the top-level referral status.
- Act on the milestones the guide lists, and ignore statuses you do not recognize, because new ones can be added.
- Store the latest status per visit and skip updates that are not newer.
- Write a sandbox test that moves a fixture visit with PATCH /testing/visits/{visit_id} through booked, report_uploaded, and sent_to_rp, and asserts the handler for each.
```

### Reports, DICOM, and invoices

```text theme={"dark"}
Write a <language> function that downloads the report, DICOM study, and invoice for a Scan.com visit.

Read first:
- https://docs.scan.com/guides/order-documents-and-dicom.md
- https://docs.scan.com/openapi.yaml

Requirements:
- Use GET /order_documents and the dedicated report, dicom, and invoices routes.
- Pass delivery=url. Base64 delivery is deprecated and large studies are not expanded.
- The URL expires after 15 minutes, so download right away and never store the URL.
- Treat a missing document as "not ready yet", not an error. DICOM returns 404 when the study is missing.
```

### Structured errors

```text theme={"dark"}
Add an HTTP client wrapper in <language> for the Scan.com Partner API v2.

Read first:
- https://docs.scan.com/guides/errors.md

Requirements:
- Parse the error envelope: type, code, message, request_id, documentation_url, and errors when present.
- Log the X-Request-Id header on every response.
- Raise one exception class per type: authentication_error, validation_error, permission_error, not_found_error, rate_limit_error, api_error.
- Retry only 5xx and 429, with exponential backoff and jitter. Never retry other 4xx.
- Include request_id in the exception message so support can find the call.
```

### Lines of business

Add one of these after the first-referral prompt.

```text theme={"dark"}
This integration is for workers' compensation. Read https://docs.scan.com/guides/lines-of-business/workers-comp-and-payers.md and apply its required fields and call order. After the referral leaves pending or canceled, poll GET /referrals/{referral_id}/payments. An empty referral_payments array is normal until Scan logs a payment.
```

```text theme={"dark"}
This integration is for an employer benefit team. Read https://docs.scan.com/guides/lines-of-business/employers-and-benefit-teams.md and apply its required fields and status handling.
```

```text theme={"dark"}
This integration is for a health plan. Read https://docs.scan.com/guides/lines-of-business/health-plans.md and apply how health-plan referrals appear on GET and in webhooks.
```

## Example prompts

Once the agent has the docs, short asks work:

* "Generate a Ruby client for creating a referral with retries on 5xx."
* "Which fields on create are required for a workers' comp referral?"
* "Write a TypeScript type for the visit.status\_changed webhook payload from the OpenAPI spec."
* "Why would POST /referrals return validation\_error, and how do I fix it?"


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.