Letter of Authorization (LOA)

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:

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

Both must be approved. They are tracked independently.

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.

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.

Rendering the LOA is not billable. You only pay once you enable reputation and add numbers.

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:

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:

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"
    }
  }'

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.

Upload the signed PDF to the Documents API

Upload the signed PDF to the Telnyx Documents API. The Documents API returns a document id — that value is your loa_document_id.

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:

{
  "data": {
    "id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c"
  }
}

Save data.id — you’ll pass it as loa_document_id in the next step.

Enable reputation with the loa_document_id

Enable Number Reputation, passing the document id and a refresh frequency.

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"
  }'

Enabling reputation is a billable action. See Number Reputation pricing for current pricing.

Wait for LOA approval

Telnyx reviews your uploaded LOA. Track loa_status on the reputation settings:

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

{
  "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.

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.

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

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:

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.

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 and re-enable it with the new document.

Next steps

Enable and configure reputation
Associate phone numbers once both gates are approved

​Overview

​LOA approval gate

​Replace a pending or rejected LOA

​Next steps

Overview

LOA approval gate

Replace a pending or rejected LOA

Next steps