> ## 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. # BPO (Business Process Outsourcer) support > Place branded calls for the businesses your call center calls on behalf of. ## 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](/docs/branded-calling/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: | Record | Describes | Where Dial Partners gets the data | Example values | Must NOT contain | | :- | :- | :- | :- | :- | | BPO enterprise (`"role_type": "bpo"`) | Dial Partners, the call center | Its own records | `"legal_name": "Dial Partners LLC"`, Dial Partners' FEIN `98-7654321`, website, address, contact Alex Rivera (`alex@dialpartners.example.com`) | Anything about Maple Ridge: its name, FEIN, address, logo, call reasons, or phone numbers | | Client enterprise (`"role_type": "enterprise"`) | Maple Ridge, the client business | **From Maple Ridge** | `"legal_name": "Maple Ridge Insurance Inc."`, Maple Ridge's FEIN `36-4829105`, website, address, contact Jordan Lee (`jordan.lee@mapleridge.example.com`) | Dial Partners' details | | DIR, under the client enterprise | The brand the called person sees | Display name, logo, call reasons, and authorizer **from Maple Ridge**. The phone numbers are Telnyx numbers in Dial Partners' account that it will call from for Maple Ridge. | `"display_name": "Maple Ridge Insurance"`, Maple Ridge's logo, call reasons `["Policy renewal", "Claim follow-up"]`, authorizer Jordan Lee, the phone numbers that display the brand | Dial Partners' name or logo | | Link: `bpo_authorizations` on the DIR | Permission for Dial Partners to call as Maple Ridge | The BPO enterprise `id` is Dial Partners' own; the LOA is **signed by Maple Ridge** | The BPO enterprise's `id`, plus the LOA signed by 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](/docs/branded-calling/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](#step-1-create-the-bpo-enterprise) 2. **Verify its contact email**: request a 6-digit code, then confirm it (`POST /v2/enterprises/{id}/verify_email`, then `/confirm`). [Step 2](#step-2-verify-the-bpos-contact-email) 3. **Wait for Telnyx to approve the BPO enterprise.** Check `bpo_verification_status` until it is `approved`. [Step 3](#step-3-telnyx-approves-the-bpo-enterprise) **Set up each client (repeat per client)** 4. **Collect the client's information**: company details, brand details (display name, logo, call reasons), and an authorizer. [Checklist](#collect-from-your-client-before-you-start) 5. **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](#step-4-create-the-clients-enterprise-and-dir) 6. **Create the client's DIR** under the client's enterprise. Do not submit it yet. [Step 4](#step-4-create-the-clients-enterprise-and-dir) 7. **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](#step-5-link-the-dir-to-the-bpo-enterprise) 8. **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](#step-5-link-the-dir-to-the-bpo-enterprise) 9. **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](#step-6-submit-the-dir-then-add-phone-numbers) 10. **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](/docs/branded-calling/bc-phone-numbers) 11. **Add the phone numbers** to the approved DIR, attaching the signed phone-number letter (`POST /v2/dir/{dir_id}/phone_numbers`). [Phone Numbers](/docs/branded-calling/bc-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](/docs/branded-calling/enterprises), 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. ```bash theme={null} # Dial Partners (the call center) creates its BPO enterprise. # Every value below is Dial Partners' own data, never the brand owner's. curl -X POST https://api.telnyx.com/v2/enterprises \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "role_type": "bpo", "legal_name": "Dial Partners LLC", "doing_business_as": "Dial Partners", "organization_type": "commercial", "organization_legal_type": "corporation", "country_code": "US", "jurisdiction_of_incorporation": "Delaware", "website": "https://dialpartners.example.com", "fein": "98-7654321", "industry": "business", "number_of_employees": "51-200", "organization_contact": { "first_name": "Alex", "last_name": "Rivera", "email": "alex@dialpartners.example.com", "job_title": "Operations Manager", "phone_number": "+12125559876" }, "billing_contact": { "first_name": "Alex", "last_name": "Rivera", "email": "billing@dialpartners.example.com", "phone_number": "+12125559876" }, "organization_physical_address": { "country": "US", "administrative_area": "NY", "city": "New York", "postal_code": "10001", "street_address": "500 Market St" }, "billing_address": { "country": "US", "administrative_area": "NY", "city": "New York", "postal_code": "10001", "street_address": "500 Market St" } }' ``` 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}`. ```bash theme={null} # Request a verification code, sent to the BPO enterprise's organization_contact.email. curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/verify_email \ -H "Authorization: Bearer YOUR_API_KEY" # Confirm the code from the email. curl -X POST https://api.telnyx.com/v2/enterprises/{enterprise_id}/verify_email/confirm \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "code": "123456" }' ``` 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): ```bash theme={null} curl https://api.telnyx.com/v2/enterprises/{bpo_enterprise_id} \ -H "Authorization: Bearer YOUR_API_KEY" ``` To find your BPO enterprise among all the enterprises in your account (for example, to look up its `id`), filter the list by type: ```bash theme={null} curl "https://api.telnyx.com/v2/enterprises?filter[role_type]=bpo" \ -H "Authorization: Bearer YOUR_API_KEY" ``` 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](/docs/branded-calling/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: ```bash theme={null} # The client enterprise: Maple Ridge's own details, not Dial Partners'. curl -X POST https://api.telnyx.com/v2/enterprises \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "legal_name": "Maple Ridge Insurance Inc.", "doing_business_as": "Maple Ridge Insurance", "organization_type": "commercial", "organization_legal_type": "corporation", "country_code": "US", "jurisdiction_of_incorporation": "Illinois", "website": "https://mapleridge.example.com", "fein": "36-4829105", "industry": "insurance", "number_of_employees": "201-500", "organization_contact": { "first_name": "Jordan", "last_name": "Lee", "email": "jordan.lee@mapleridge.example.com", "job_title": "Director of Customer Operations", "phone_number": "+13125550100" }, "billing_contact": { "first_name": "Jordan", "last_name": "Lee", "email": "billing@mapleridge.example.com", "phone_number": "+13125550100" }, "organization_physical_address": { "country": "US", "administrative_area": "IL", "city": "Chicago", "postal_code": "60601", "street_address": "200 Lakeview Ave" }, "billing_address": { "country": "US", "administrative_area": "IL", "city": "Chicago", "postal_code": "60601", "street_address": "200 Lakeview Ave" } }' ``` 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: ```bash theme={null} # The DIR goes under Maple Ridge's enterprise id. curl -X POST https://api.telnyx.com/v2/enterprises/{client_enterprise_id}/dir \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "display_name": "Maple Ridge Insurance", "authorizer_name": "Jordan Lee", "authorizer_email": "jordan.lee@mapleridge.example.com", "call_reasons": ["Policy renewal", "Claim follow-up"], "logo_url": "https://mapleridge.example.com/logo.bmp", "certify_brand_is_accurate": true, "certify_no_shaft_content": true, "certify_ip_ownership": true }' ``` See [Display Identity Records (DIRs)](/docs/branded-calling/brands) for every DIR field. ## Step 5: Link the DIR to the BPO enterprise 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](/api-reference/documents/upload-a-document) 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: ```bash theme={null} curl -X POST https://api.telnyx.com/v2/dir/{dir_id}/bpo_loa \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "bpo_enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6" }' ``` * `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](/api-reference/documents/upload-a-document), and hold onto the `document_id` it gives back. That is the `loa_document_id` you pass in the next step. ### Link the DIR to the BPO enterprise 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: ```bash theme={null} curl -X PATCH https://api.telnyx.com/v2/dir/{dir_id} \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "bpo_authorizations": [ { "bpo_enterprise_id": "4a6192a4-573d-446d-b3ce-aff9117272a6", "loa_document_id": "2a7e8337-e803-4057-a4ae-26c40eb0bc6c" } ] }' ``` 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](#read-back-a-dirs-authorizations)); 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: ```bash theme={null} curl -X POST https://api.telnyx.com/v2/dir/{dir_id}/submit \ -H "Authorization: Bearer YOUR_API_KEY" ``` 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](/docs/branded-calling/bc-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. ### How links are reviewed 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: ```bash theme={null} curl https://api.telnyx.com/v2/dir/{dir_id}/bpo_authorizations \ -H "Authorization: Bearer YOUR_API_KEY" ``` 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`. ## What the link does 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 * [Quickstart guide](/docs/branded-calling/quickstart), the end-to-end Branded Calling flow. * [Display Identity Records (DIRs)](/docs/branded-calling/brands), full DIR lifecycle, statuses, editing, deletion. * [Enterprises](/docs/branded-calling/enterprises), the required fields for any enterprise, including a BPO enterprise and the brand owner's enterprise.