2. Firm setup

A Requestor is your firm’s retrieval profile. Tavrn puts its name and documents in every packet sent to a provider and uses its invoice limit to decide which provider fees to pay without asking you. Your organization starts with one default profile; most integrations configure that one or create a profile per office or practice group. Endpoints: GET /v2/requestors, POST /v2/requestors, PATCH /v2/requestors/{requestor_id}, POST /v2/requestors/sign-upload. Reading needs requestors:read; creating, updating and uploading need requestors:write.

Firm name

name is the firm name shown to providers. null falls back to your organization name.

curl -X POST https://enterprise.tavrn.ai/v2/requestors \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Example Firm — Records Team" }'

Save the returned id; it becomes requestor_id on your retrievals.

Letter of representation

Upload the PDF, then attach the returned upload_id to the profile.

# 1. Ask for an upload URL
SIGNED=$(curl -s -X POST https://enterprise.tavrn.ai/v2/requestors/sign-upload \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "file_name": "letter-of-representation.pdf", "file_type": "application/pdf" }')
UPLOAD_URL=$(echo "$SIGNED" | jq -r .upload_url)
UPLOAD_ID=$(echo "$SIGNED" | jq -r .upload_id)

# 2. PUT the bytes to the returned upload_url (within 15 minutes)
curl -X PUT "$UPLOAD_URL" -H "Content-Type: application/pdf" \
  --data-binary @letter-of-representation.pdf

# 3. Attach it to the profile (upload_id is valid for one hour)
curl -X PATCH https://enterprise.tavrn.ai/v2/requestors/$REQUESTOR_ID \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "letter_of_rep": { "upload_id": "'$UPLOAD_ID'" } }'

Profile documents must be readable, unencrypted PDFs of at most 25 MiB. The same flow attaches an rfc_form (request-for-copies form) if your firm uses one. A profile without its own letter does not inherit the default profile’s.

Provider invoice approval limit

Providers often charge for copies. provider_invoice_limit (USD) is the amount Tavrn may pay on your behalf without asking. Anything above it opens an action request that your system answers through the API (see Track and download).

Value	Behavior
omitted / `null`	Tavrn applies the default limit of $100
a number, e.g. `150`	Invoices up to $150 are paid automatically; larger ones wait for your approval
`0`	Every positive invoice waits for your approval

curl -X PATCH https://enterprise.tavrn.ai/v2/requestors/$REQUESTOR_ID \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider_invoice_limit": 150 }'

Read responses include effective_provider_invoice_limit, the number actually applied.

Affidavits

Some matters need the provider to attest to the records. Tell Tavrn which record families your firm wants affidavits for, and optionally supply your own affidavit forms.

affidavits.declared_families: any of records, billing, radiology. [] records an explicit “none”.
affidavits.documents: your own form per family ({ "family": "records", "upload_id": "…" }), uploaded with the same sign-upload flow as the letter. One per family.
affidavits.generic: a fallback form used when a family has no exact document.

curl -X PATCH https://enterprise.tavrn.ai/v2/requestors/$REQUESTOR_ID \
  -H "Authorization: Bearer $TAVRN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "affidavits": {
      "declared_families": ["records", "billing"],
      "documents": [{ "family": "records", "upload_id": "33333333-3333-4333-8333-333333333333" }]
    }
  }'

On each request you then ask for the attestation per record line with requested_records[].requirements: ["affidavit"] (or ["certification"]; one kind per request). Details in Requested Records.

Correspondence (optional)

correspondence lets you add a custom letter body, a notice, or billing instructions to the packets. Most firms leave it empty. See Update Requestor Settings for every field and how omitted versus null values behave.

Next: create your first retrieval

Upload the authorization, name the patient and facility, send the request.

Get started

Retrieval reference

Case documents

Firm name

Letter of representation

Provider invoice approval limit

Affidavits

Correspondence (optional)

Next: create your first retrieval

​Firm name

​Letter of representation

​Provider invoice approval limit

​Affidavits

​Correspondence (optional)

Next: create your first retrieval

Firm name

Letter of representation

Provider invoice approval limit

Affidavits

Correspondence (optional)