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.

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

   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": "[e-mail]",
         "contact_phone": "[phone]"
       }
     }'
   

   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 Number Reputation 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_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