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

# Letter of Authorization (LOA)

> Render, sign, upload, and manage the Letter of Authorization that Telnyx needs before activating Number Reputation.

## Overview

Before Telnyx can register your phone numbers with the major call-analytics networks used by US carriers, you must provide a signed **Letter of Authorization (LOA)**. The LOA authorizes Telnyx to manage your numbers' reputation on your behalf.

The LOA is the **#1 thing customers get stuck on**, so follow these steps in order. There are two separate approval gates you must clear before you can add phone numbers:

1. Reputation `status` must be `approved` (the activation lifecycle).
2. `loa_status` must be `approved` (Telnyx reviews the signed LOA).

Both must be `approved`. They are tracked independently.

<Steps>
  <Step title="Render the LOA as a PDF">
    Telnyx renders a pre-filled LOA from your enterprise record. The enterprise
    identity, address, and authorized-representative contact are read from the
    enterprise you created - you do **not** pass them again here.

    ```bash theme={null}
    curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -o loa.pdf \
      -d '{}'
    ```

    The response body is the **PDF itself** (`application/pdf`). The `-o loa.pdf`
    flag saves it to disk.

    <Note>
      Rendering the LOA is **not billable**. You only pay once you enable
      reputation and add numbers.
    </Note>

    **Optional body fields** (both optional):

    | Field       | Description                                                                                                                                             |
    | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | `agent`     | A third-party reseller / partner block, used only when a partner manages the enterprise's numbers. Omit when the enterprise works directly with Telnyx. |
    | `signature` | Embeds a signature image in the rendered PDF. When omitted, the PDF is returned **unsigned** for you to sign manually.                                  |

    To render with the agent (reseller) block:

    ```bash theme={null}
    curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -o loa.pdf \
      -d '{
        "agent": {
          "legal_name": "Reseller LLC",
          "dba": "Reseller",
          "street_address": "500 Market St",
          "extended_address": "Suite 200",
          "city": "San Francisco",
          "administrative_area": "CA",
          "postal_code": "94105",
          "country": "US",
          "contact_name": "Pat Partner",
          "contact_title": "Account Manager",
          "contact_email": "pat@reseller.com",
          "contact_phone": "+13125550000"
        }
      }'
    ```

    To embed a signature at render time instead of signing the PDF by hand:

    ```bash theme={null}
    curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -o loa.pdf \
      -d '{
        "signature": {
          "image_base64": "BASE64_ENCODED_SIGNATURE_IMAGE",
          "signer_name": "Jane Smith"
        }
      }'
    ```
  </Step>

  <Step title="Sign the PDF">
    If you did not embed a `signature` at render time, open `loa.pdf` and sign it
    (e-signature or wet signature). Save the signed copy.
  </Step>

  <Step title="Upload the signed PDF to the Documents API">
    Upload the signed PDF to the [Telnyx Documents API](/api-reference/documents/upload-a-document). The
    Documents API returns a document `id` - that value is your `loa_document_id`.

    ```bash theme={null}
    curl -X POST https://api.telnyx.com/v2/documents \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -F "file=@loa.pdf"
    ```

    The response contains the document id:

    ```json theme={null}
    {
      "data": {
        "id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c"
      }
    }
    ```

    Save `data.id` - you'll pass it as `loa_document_id` in the next step.
  </Step>

  <Step title="Enable reputation with the loa_document_id">
    Enable Number Reputation, passing the document id and a refresh frequency.

    ```bash theme={null}
    curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
      -H "Authorization: Bearer YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "loa_document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c",
        "check_frequency": "business_daily"
      }'
    ```

    <Note>
      Enabling reputation is a **billable action**. See
      [Telnyx pricing](https://telnyx.com/pricing/numbers) for current pricing.
    </Note>
  </Step>

  <Step title="Wait for LOA approval">
    Telnyx reviews your uploaded LOA. Track `loa_status` on the reputation
    settings:

    ```bash theme={null}
    curl https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation \
      -H "Authorization: Bearer YOUR_API_KEY"
    ```

    ```json theme={null}
    {
      "data": {
        "status": "approved",
        "loa_status": "pending"
      }
    }
    ```

    `loa_status` moves `pending` → `approved` (or `rejected`). You **cannot add
    phone numbers** until `loa_status` is `approved` **and** reputation `status`
    is `approved`.
  </Step>
</Steps>

## LOA approval gate

| `loa_status` | Meaning                                                                            |
| :----------- | :--------------------------------------------------------------------------------- |
| `pending`    | Telnyx is reviewing the uploaded LOA. Numbers cannot be added yet.                 |
| `approved`   | LOA accepted. Combined with reputation `status` = `approved`, you can add numbers. |
| `rejected`   | LOA was not accepted. Replace it (see below) to retry.                             |

<Warning>
  Reputation `status` and `loa_status` are **two separate gates**. Both must read
  `approved` before `POST .../reputation/numbers` will accept numbers.
</Warning>

## Replace a pending or rejected LOA

If your LOA is `rejected` - or it is still `pending` and you need to upload a
corrected document - render a fresh PDF, sign and upload it to the Documents API
to get a new `loa_document_id`, then point your reputation settings at it:

```bash theme={null}
curl -X PATCH https://api.telnyx.com/v2/enterprises/{enterprise_id}/reputation/loa \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "loa_document_id": "NEW_DOCUMENT_ID"
  }'
```

Replacing the LOA **resets `loa_status` back to `pending`**. The new document
must be approved again before more numbers can be added. This is the recovery
path for a rejected LOA.

<Warning>
  You can only replace the LOA while `loa_status` is `pending` or `rejected`.
  Once `loa_status` is `approved`, the document is locked in and this `PATCH`
  returns **`400 Bad Request`** ("The authorization document cannot be changed
  after it has been approved."). To start over with a different LOA after
  approval, [disable Number Reputation](/docs/branded-calling/number-reputation/settings#disable-number-reputation)
  and re-enable it with the new document.
</Warning>

## Next steps

* [Enable and configure reputation](/docs/branded-calling/number-reputation/settings)
* [Associate phone numbers](/docs/branded-calling/number-reputation/phone-numbers) once both gates are `approved`