Skip to main content

​
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.
1

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):
FieldDescription
agentA third-party reseller / partner block, used only when a partner manages the enterprise’s numbers. Omit when the enterprise works directly with Telnyx.
signatureEmbeds 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"
    }
  }'
2

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

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

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 Telnyx pricing for current pricing.
5

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_statusMeaning
pendingTelnyx is reviewing the uploaded LOA. Numbers cannot be added yet.
approvedLOA accepted. Combined with reputation status = approved, you can add numbers.
rejectedLOA 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