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

# Synthpop for developers

> One API to orchestrate the patient journey: intake, coverage, and engagement.

## One API for the patient journey

Synthpop turns the slow, manual, document-heavy work of healthcare operations into
a single programmable surface. You submit the documents you already receive —
referrals, orders, clinical notes, insurance cards, forms — and Synthpop reads
them, structures them, validates them against clinical and payer requirements, and
drives the follow-up. Intake, coverage, and patient engagement all run through one
resource: the **Task**.

* **One integration, three capabilities.** Referral & order intake, coverage &
  authorization, and patient engagement share the same endpoints and the same
  response shape.
* **Documents in, decisions out.** Upload PDFs, images, text, or audio; read back
  structured records, per-code verdicts, and a plain-English conclusion.
* **Asynchronous by design.** Create a Task and get an ID immediately; results
  arrive as the Task moves to a terminal status.

<CardGroup cols={2}>
  <Card title="Get your first result" icon="rocket" href="/quickstart">
    Go from an API key to a validated Task in five steps.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Eight endpoints, one resource. Explore the full contract.
  </Card>
</CardGroup>

## Your first request

Every capability starts the same way: `POST /task/create` with a `task_type` and
one or more documents. It returns immediately with a Task ID and
`status: "pending"` — Synthpop processes the work in the background.

<CodeGroup>
  ```bash cURL theme={null}
  # $SYNTHPOP_JWT_TOKEN comes from step 2 of the Quickstart (token exchange)
  curl -X POST "https://app.synthpop.ai/public/v1/task/create" \
    -H "Authorization: Bearer $SYNTHPOP_JWT_TOKEN" \
    -F "task_type=task" \
    -F "uploads=@referral-packet.pdf;type=application/pdf"
  ```

  ```python Python theme={null}
  import os
  import requests

  BASE_URL = "https://app.synthpop.ai/public/v1"

  # jwt_token comes from the auth step — exchange your api_secret for a
  # bearer token first (see /authentication). Here we read the cached token
  # from the environment.
  jwt_token = os.environ["SYNTHPOP_JWT_TOKEN"]

  with open("referral-packet.pdf", "rb") as f:
      response = requests.post(
          f"{BASE_URL}/task/create",
          headers={"Authorization": f"Bearer {jwt_token}"},
          data={"task_type": "task"},
          files={"uploads": ("referral-packet.pdf", f, "application/pdf")},
      )

  task = response.json()
  print(task["uuid"], task["status"])  # -> "<uuid>" "pending"
  ```
</CodeGroup>

<Note>
  `task_type` is required and is **provisioned for your organization** during
  onboarding — there is no discovery endpoint. `task` shown above is an
  org-provisioned convenience type that auto-classifies the document and routes it
  to the right workflow; your Synthpop contact will tell you which task types are
  enabled for you. See the [Quickstart](/quickstart) for the full auth-to-result
  path.
</Note>

## Three capabilities, one Task

The public API exposes a single lever — the `task_type` you choose on create.
The same integration covers the whole journey.

<CardGroup cols={3}>
  <Card title="Referral & order intake" icon="file-import" href="/guides/intake/overview">
    Classify and validate incoming referrals and orders. Extract structured
    records, check documentation against clinical and payer rules, and get a
    per-code verdict on whether the request is supported.
  </Card>

  <Card title="Coverage & authorization" icon="shield-check" href="/guides/coverage/overview">
    Evaluate coverage and authorization requirements alongside the clinical
    documentation, so you know what a payer needs before you submit.
  </Card>

  <Card title="Patient engagement" icon="phone" href="/guides/engagement/overview">
    Reach patients to gather missing information and move cases forward,
    including the voice agent for enabled organizations.
  </Card>
</CardGroup>

## What you can build

<CardGroup cols={2}>
  <Card title="Automated intake triage" icon="inbox">
    Drop every faxed or emailed packet into Synthpop and let it sort complete
    submissions from those that need follow-up — no manual page-sorting.
  </Card>

  <Card title="Documentation & compliance checks" icon="clipboard-check">
    Validate that a referral or order carries the records and evidence a payer
    requires, with issues surfaced field-by-field.
  </Card>

  <Card title="Structured data extraction" icon="table">
    Pull demographics, diagnosis codes, service dates, and insurance details out
    of scanned, handwritten, or out-of-order documents.
  </Card>

  <Card title="Closed-loop patient outreach" icon="messages">
    Trigger patient engagement to collect what's missing and route the completed
    case back into your workflow.
  </Card>
</CardGroup>

## How it works

One Task threads a patient's case through the whole journey. You create it, feed
it documents, and read back a structured result — Synthpop does the reading,
structuring, validating, and engaging in between.

<Steps>
  <Step title="Create a Task">
    `POST /task/create` with a `task_type` and your documents. You get a Task ID
    and `status: "pending"` right away.
  </Step>

  <Step title="Synthpop processes it">
    The Task moves through `processing`. It classifies and reads each document,
    extracts structured **medical records**, and evaluates them.
  </Step>

  <Step title="Read the result">
    Poll `GET /task/get` (or receive an opt-in callback) until the Task reaches a
    terminal status. If it needs more from you it pauses at `waiting`; you upload
    the missing documents and it resumes.
  </Step>

  <Step title="Act on the verdict">
    A completed validation Task carries per-code `verdicts`, plain-English
    `verdict_summaries`, and any `issues` — everything you need to move forward or
    follow up.
  </Step>
</Steps>

<Tip>
  Because the flow is asynchronous, `POST /task/create` never returns verdicts.
  Read results from `GET /task/get` after the Task reaches a terminal status. See
  [Working with async results](/guides/async-results).
</Tip>

## Resources

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Zero to your first validated result.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    The full endpoint and schema reference.
  </Card>

  <Card title="Changelog" icon="clock-rotate-left" href="/reference/changelog">
    What's new in the public API.
  </Card>

  <Card title="Support" icon="life-ring" href="/support/contact">
    Reach the Synthpop team.
  </Card>
</CardGroup>