Skip to main content

​
Overview

A Business Process Outsourcer (BPO) is a call center or outsourcer that places calls on behalf of other businesses. When a BPO calls for a client, the person being called should see the client’s name and logo, not the call center’s. With Branded Calling, a BPO does this from its own Telnyx account. In that one account it sets up three separate records, each describing a different company or brand:
  1. A BPO enterprise ("role_type": "bpo"), describing the call center itself.
  2. An enterprise for each client ("role_type": "enterprise", the default), describing that client’s business.
  3. A DIR under each client’s enterprise, describing the brand the called person sees: display name, logo, call reasons, and phone numbers.
Then it links each client’s DIR to its BPO enterprise, backed by a Letter of Authorization (LOA) the client signs. Once approved, the link adds the call center to the client DIR’s list of authorized callers in the branded calling registry.
If your calls display your own business’s name, you are not acting as a BPO, even if you run your own call center. Create a normal enterprise and a DIR for your own brand. See the Quickstart.

​
Example: which data goes where

This guide follows two fictional companies:
  • Dial Partners LLC is the BPO. It is a call center and the Telnyx customer. Everything below is done from Dial Partners’ Telnyx account, with its API key.
  • Maple Ridge Insurance Inc. is Dial Partners’ client, the brand owner. It hired Dial Partners to call its policyholders, and wants them to see “Maple Ridge Insurance” and its logo on their phone.
Dial Partners does all the data entry, but not all the data is its own. Each record holds one company’s data only, and for the client’s records Dial Partners has to get the information from Maple Ridge:

​
Collect from your client before you start

Before creating the client’s records, get the following from the client (Maple Ridge in the example). None of it can be filled in with the call center’s own details.
  • Company details for the client enterprise: legal name, DBA, FEIN, organization type and legal type, jurisdiction of incorporation, website, industry, number of employees, physical and billing address, and a contact person with name, job title, email, and phone. See Enterprises for the full field list.
  • Brand details for the DIR: the display name people should see, the logo (256x256 BMP), and the call reasons.
  • An authorizer at the client: a person at Maple Ridge (name and email) who stands behind the brand. If Telnyx sends a verification code to the DIR’s authorizer email, it goes to that person, so they have to pass the code back to you.
  • Supporting documents, if any, that show the client owns the brand (for example, business registration).
  • Business and financial references for the client, if your account is required to provide them. When required, they must be submitted before the DIR is submitted (verify the authorizer email, then submit references, then submit the DIR). These are the client’s references, not the call center’s.
  • A signature on the BPO Letter of Authorization from the client’s contact, in step 5. This is the client’s written permission for you to call under its brand.
  • A signature on the phone-number Letter of Authorization from the client’s contact, in step 6. This letter lists the numbers that will display the client’s brand. It names the client as the enterprise and your call center as the authorized agent, and the client signs it, not you.
The most common mistake is putting the client’s details into the BPO enterprise. For example, Dial Partners creates its BPO enterprise and fills in "legal_name": "Maple Ridge Insurance Inc.", Maple Ridge’s FEIN, and Maple Ridge’s address. That BPO enterprise now describes the wrong company, and it still cannot carry the brand: a BPO enterprise can never have a DIR.The BPO enterprise always describes the call center. The client’s company details go on the client’s own enterprise, and the brand (display name, logo, call reasons, phone numbers) goes on the DIR under the client’s enterprise.
A few rules follow from this:
  • A BPO enterprise cannot have a DIR. Creating a DIR under it is rejected with 400. DIRs always go under a client enterprise.
  • You create the BPO enterprise once. Every client’s DIR links to the same BPO enterprise.
  • Each client gets its own enterprise. If Dial Partners also calls for a second client, it creates a second client enterprise and DIR, and links that DIR to the same BPO enterprise.
  • All records live in the same Telnyx account. A DIR can only be linked to an approved BPO enterprise in your own account. Linking a BPO enterprise from another Telnyx account is rejected with 400.
  • The type is fixed at creation. A BPO enterprise cannot be changed into a normal enterprise, or the other way around. If you created the wrong type, create a new enterprise of the right type.

​
The whole flow at a glance

Everything below is done from the call center’s Telnyx account (Dial Partners in the example). The client (Maple Ridge) only provides information and signs two letters. Each line links to the step with the details. Set up the call center (once)
  1. Create the BPO enterprise with the call center’s own details and "role_type": "bpo" (POST /v2/enterprises). Keep its id. Step 1
  2. Verify its contact email: request a 6-digit code, then confirm it (POST /v2/enterprises/{id}/verify_email, then /confirm). Step 2
  3. Wait for Telnyx to approve the BPO enterprise. Check bpo_verification_status until it is approved. Step 3
Set up each client (repeat per client)
  1. Collect the client’s information: company details, brand details (display name, logo, call reasons), and an authorizer. Checklist
  2. Create the client’s enterprise with the client’s details, accept the Branded Calling Terms of Service if you haven’t yet, and activate Branded Calling on it. Step 4
  3. Create the client’s DIR under the client’s enterprise. Do not submit it yet. Step 4
  4. Get the BPO letter signed: generate it (POST /v2/dir/{dir_id}/bpo_loa), have the client’s contact sign it, and upload it to the Documents API. Step 5
  5. Link the DIR to the BPO enterprise: send bpo_authorizations with your BPO enterprise id and the signed letter’s document_id (PATCH /v2/dir/{dir_id}). Step 5
  6. Submit the DIR (POST /v2/dir/{dir_id}/submit). Telnyx reviews the DIR and the link together; approving the DIR approves the link. Step 6
  7. Get the phone-number letter signed: generate it (POST /v2/dir/{dir_id}/loa) with your call center as the agent, have the client’s contact sign it, and upload it. Phone Numbers
  8. Add the phone numbers to the approved DIR, attaching the signed phone-number letter (POST /v2/dir/{dir_id}/phone_numbers). Phone Numbers
Order matters. The BPO enterprise can’t be approved until its email is verified, a DIR can’t be linked until the BPO enterprise is approved, a DIR can’t be edited (so can’t be linked) while it is under review, and phone numbers can only be added once the DIR is approved.

​
Step 1: Create the BPO enterprise

The BPO enterprise uses the same fields as any enterprise, plus "role_type": "bpo". Branded Calling is US-only, so the call center must be a US company ("country_code": "US"). Every field describes the call center itself. In the example, Dial Partners enters its own legal name, FEIN, website, contact, and address, and nothing about Maple Ridge.
The response includes an id. This is the BPO enterprise’s id, used as bpo_enterprise_id in step 5.
Use a mailbox the call center controls for the organization_contact email. That is the address verified in the next step, and the BPO enterprise cannot be approved until it is verified.

​
Step 2: Verify the BPO’s contact email

Before Telnyx can approve the BPO enterprise, the call center has to prove it owns the contact email on it (in the example, Alex Rivera’s address at Dial Partners). It asks Telnyx to email a 6-digit code, then sends the code back to confirm. Because a BPO enterprise has no DIR of its own, this happens on the enterprise rather than on a DIR. Use the BPO enterprise’s id as {enterprise_id}.
Both calls return where the email verification currently stands, so you can see whether the email is now verified. A code is only good for 15 minutes, and asking for a new one voids the old one. If a code is wrong, expired, or already used, you get back the same generic failure either way, so a rejection never tells an attacker which of those it was.

​
Step 3: Telnyx approves the BPO enterprise

Telnyx reviews the BPO enterprise and moves its status from pending to approved or rejected. The email has to be verified before approval goes through, so don’t expect a decision until that step is done. Check where the review stands by reading the BPO enterprise. Its bpo_verification_status field is pending, approved, or rejected (it is null on normal enterprises):
To find your BPO enterprise among all the enterprises in your account (for example, to look up its id), filter the list by type:
Only an approved BPO can be authorized on a DIR. If Telnyx later rejects a BPO, every authorization it held is set to rejected. Those entries stay in each DIR’s authorization list, with a rejection_reason, but no longer take effect.
Editing an approved BPO enterprise resets it. If you change any identity detail on an approved BPO enterprise (legal name, DBA, website, FEIN, industry, number of employees, physical address, organization contact including its email or phone, D-U-N-S number, legal type, SIC code, corporate registration or professional license number, or jurisdiction), it goes back to pending for re-approval. At the same moment, every DIR authorization for that BPO is set to rejected.To recover:
  1. If you changed the contact email, verify it again (step 2).
  2. Wait for Telnyx to re-approve the BPO enterprise.
  3. For each client DIR, generate a new LOA, have the client sign it, upload it, and send it in bpo_authorizations with the new loa_document_id. Resending the old one keeps the authorization rejected.
Re-sending a value that is unchanged does not reset anything. If Number Reputation is turned on for the enterprise, most of these fields (legal name, DBA, website, FEIN, industry, number of employees, physical address, organization contact, D-U-N-S number) cannot be edited at all: the update is rejected with 400, and nothing is reset.

​
Step 4: Create the client’s enterprise and DIR

Create the client’s enterprise and DIR the same way you would for any brand, following the Quickstart (activate Branded Calling on the enterprise, then create the DIR). The only difference is whose data you enter: the client’s.
Create the DIR, but do not submit it yet. Link the BPO enterprise first (step 5), then submit (step 6). A DIR that is submitted or in_review cannot be edited, so if you submit first, you cannot add the link until vetting finishes, and the link then needs its own separate review.
The client enterprise is a normal enterprise. Leave role_type out (it defaults to enterprise). In the example, it describes Maple Ridge:
Then create the DIR under the client enterprise’s id (not the BPO enterprise’s). The DIR describes the brand the called person sees, so the display name, logo, call reasons, and authorizer are all Maple Ridge’s:
See Display Identity Records (DIRs) for every DIR field. Once the BPO enterprise is approved, link the client’s DIR to it. There are two parts: get the LOA signed, then list the BPO enterprise on the DIR. Have two things ready before you start. The BPO enterprise has to be approved already; linking one that isn’t an approved BPO enterprise in your account is rejected with 400. And the signed LOA has to be uploaded to the Telnyx Documents API so you have its document_id on hand.

​
Generate and sign the authorization LOA

The Letter of Authorization is the brand owner’s written permission for the call center to place calls under its brand. It is generated from your account, but it is signed by the brand owner, not by the call center: in the example, Maple Ridge’s organization contact (the contact on the Maple Ridge enterprise) is named on it as the authorizing representative and signs it. You then upload the signed letter to your own account. Generate a pre-filled BPO Authorization LOA for the brand owner’s DIR. It is filled in from the two enterprises you created: Maple Ridge as the brand owner, Dial Partners as the BPO. Leave signature out to get an unsigned PDF: send it to the client to sign, then upload the signed copy. Or, if the client has given you their drawn signature, include it to embed it directly. Either way the signature must be the client’s (Maple Ridge’s), never the call center’s:
  • bpo_enterprise_id: the id of your approved BPO enterprise (from step 1).
  • signature: optional. An object with image_base64 (the raw base64 of a PNG image, with no data: prefix) and an optional signer_name. Include it to embed the client’s signature in the letter, or omit signature entirely to get an unsigned letter for the client to sign.
The response is the LOA PDF. Have the client sign it, then upload it to the Telnyx Documents API, and hold onto the document_id it gives back. That is the loa_document_id you pass in the next step. List the BPO enterprise, with the signed LOA document, in the bpo_authorizations array of the brand owner’s DIR. You can do this when you create the DIR or later with an update:
Each entry pairs a BPO (bpo_enterprise_id) with its signed LOA (loa_document_id). The array holds up to 10 authorizations.
The bpo_authorizations array replaces the DIR’s current list on every create or update. To keep an existing authorization, include it again with the same loa_document_id (read it from the authorizations list); it then keeps its current review status, so an approved link stays approved. To remove one, leave it out. Leave out any entry whose BPO enterprise is no longer approved: including it rejects the whole update with 400. Sending an empty array ([]) clears all authorizations. Omitting the field leaves the list unchanged. Editing this list does not re-vet the DIR itself.
You can change a DIR’s authorizations only while the DIR is in an editable status (for example draft, verified, rejected, suspended, or unsuccessful). While the DIR is being reviewed, the update is rejected; wait until review finishes.

​
Step 6: Submit the DIR, then add phone numbers

Once the link is in place, submit the client’s DIR:
Telnyx reviews the DIR and its pending link together: when the DIR is approved, its pending authorizations are approved with it. After the DIR is verified, add the phone numbers that should display the client’s brand, as described in Phone Numbers. Adding numbers needs its own signed Letter of Authorization: generate it with POST /v2/dir/{dir_id}/loa, passing your call center’s details in agent. It is filled in from the client’s enterprise, so the client’s contact signs it, not you. A new authorization starts in pending. Telnyx reviews it and moves it to approved or rejected. Only an approved authorization takes effect. Sending a different loa_document_id for a BPO (a newly signed and uploaded LOA) sends that authorization back to pending for another review. Uploading a document on its own changes nothing until you send its id in bpo_authorizations. If you add or change a link on a DIR that is already verified, that link is reviewed on its own, and the DIR stays verified meanwhile.

​
Read back a DIR’s authorizations

Check a DIR’s authorized BPOs and their review status at any time:
Each returned authorization shows the BPO enterprise it belongs to (bpo_enterprise_id), the signed LOA you submitted (loa_document_id), its current status (pending, approved, or rejected), and, when rejected, a rejection_reason. An approved link adds the call center to the client DIR’s list of authorized callers in the branded calling registry. It applies to that one DIR only. It does not change or merge the records: the BPO enterprise still describes the call center, and the client enterprise and DIR still describe the client.

​
Stop working with a BPO

To stop a DIR’s calls going through the BPO, update the DIR with a bpo_authorizations array that leaves that BPO out. Because the list replaces on every update, the omitted authorization is removed. Sending [] removes all of them.

​
What’s next