PriorAuth Pilot API

Connect an EHR, billing system or other software to PriorAuth Pilot. Version 1. Base address: https://app.priorauthpilot.com/api/v1

The API carries protected health information. Use it only under a Business Associate Agreement with the agency, over HTTPS, and store keys securely.

Authentication

An agency administrator creates a key in Settings → Connect other software (API). Send it on every call in one of these headers:

Authorization: Bearer pap_xxxxxxxx
X-API-Key: pap_xxxxxxxx

Each key only reaches its own agency's data. Limit: 120 calls per minute per key (HTTP 429 above that). Every call that changes data is recorded in the agency's activity log.

Endpoints

Method and path	What it does
`GET /ping`	Checks the key. Returns the agency name.
`GET /clients?medicaid_id=&limit=&offset=`	Lists clients (up to 500 per page).
`POST /clients`	Creates a client, or updates the one with the same Medicaid ID. JSON: `name` (required), `dob` (YYYY-MM-DD), `medicaid_id`, `phone`, `plan`.
`POST /requests`	Starts a prior authorization request. JSON: `client_id` or `client` {…}, `plan`, `request_type` (initial \| reauthorization), `primary_dx`, `practitioner`, `practitioner_npi`, `services`: [{`code` (e.g. H0036, H2019 HQ) or `service_key`, `units`, `start_date`}]. Staff finish the request in PriorAuth Pilot (reasons, supporting information, review); the response includes `app_url`.
`POST /requests/{id}/documents`	Uploads a clinical document as multipart form field `file` (PDF, .docx or .txt). Optional field `doc_type`: assessment \| treatment_plan \| other.
`GET /authorizations?updated_since=&limit=&offset=`	Lists requests with each service's decision, auth number, approved units and dates, and units used. Use `updated_since` (ISO date-time) to fetch only changes.
`GET /authorizations/{id}`	One request.
`POST /usage`	Sends billed units so PriorAuth Pilot can track units used, annual thresholds and the billing check. JSON: `{"rows": [{"medicaid_id", "code", "modifier", "date", "units"}]}`.

Example

curl -X POST https://app.priorauthpilot.com/api/v1/requests \
  -H "Authorization: Bearer pap_xxxxxxxx" -H "Content-Type: application/json" \
  -d '{"client": {"name": "Jane Doe", "dob": "2012-04-09", "medicaid_id": "123456789012", "plan": "CareSource"},
       "request_type": "reauthorization", "primary_dx": "F33.1",
       "services": [{"code": "H0036", "units": 96, "start_date": "2026-11-01"}]}'

Automatic notifications (webhooks)

The agency enters your https address in Settings and picks which events to send:

request.sent
decision.recorded
authorization.expiring

Each notification is a JSON POST: {"event": "...", "sent_at": "...", "data": {authorization}}. Verify it with the signing secret shown to the administrator when it was created:

X-PriorAuthPilot-Signature: sha256=HEX( HMAC_SHA256(secret, raw_request_body) )

Reply with any 2xx status. The agency can send a test notification from Settings.

Errors

Errors return JSON {"error": "..."} with HTTP 400 (bad input), 401 (missing or invalid key), 403 (account not active), 404 (not found) or 429 (rate limit).

Questions: support@priorauthpilot.com