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

# 2. Firm setup

> Create the Requestor profile Tavrn uses on every request: firm name, letter of representation, provider invoice approval limit, and affidavits.

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`](/api-reference/v2/endpoint/requestors/list-requestors),
[`POST /v2/requestors`](/api-reference/v2/endpoint/requestors/create-requestor),
[`PATCH /v2/requestors/{requestor_id}`](/api-reference/v2/endpoint/requestors/update-requestor),
[`POST /v2/requestors/sign-upload`](/api-reference/v2/endpoint/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.

```bash theme={null}
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.

```bash theme={null}
# 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](/guides/v2/get-started/track-and-download#answer-action-requests)).

| 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 |

```bash theme={null}
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.

```bash theme={null}
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](/guides/v2/retrieval-guide#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](/guides/v2/retrieval-guide#update-requestor-settings) for every
field and how omitted versus `null` values behave.

<Card title="Next: create your first retrieval" icon="arrow-right" href="/guides/v2/get-started/first-retrieval">
  Upload the authorization, name the patient and facility, send the request.
</Card>