Disclaimer

The First Orion API has multiple endpoints that can create, assign, and delete phone numbers. This guide covers some of the older endpoints that integrated users may already be using. If you are not already integrated, we recommend following the standard Phone Number Management guide here.

Pre-requisites

1. First Orion Branded Communications agreement
2. Access to First Orion Customer Portal
3. Vetted and Approved Business
4. Understanding of First Orion's Authentication
5. Phone Numbers to Manage
6. Tool/Service to invoke the Phone Number Endpoints (cURL examples shown here)

Understanding a Phone Numbers Assignment in First Orion

Data Hierarchy

Phone Numbers are assigned at a few different levels. All phone numbers that are created in First Orion are automatically in a Business Level. This will associate the phone numbers with the business for purposes of tagging and management.

Phone Numbers assigned at the Business Unit Level are essentially being sorted and prepped for the Program Level.

Phone Numbers assigned at the Program Level are actively tied to Branding or Blocking. This means they will behave and display as desired, unless the Programs Expiration Date has passed.

Allocated Numbers

When a phone number is created in First Orion, it can only be branding in one Business at a time. So if Business Alpha uploads a Phone Number for Branding, Business Bravo will get an error saying, "ALLOCATED_NUMBER", if they try to Create the same Phone Number for Branding.

Here is an example of an Allocated Number.

{
    "body": {
        "phoneNumbers": [],
        "rejectedPhoneNumbers": [
            {
                "phoneNumber": "+15012149020",
                "callPurposeCode": "CS",
                "rejectionReason": "ALLOCATED_NUMBER",
                "allocatedBusinessId": "cb5ef552-ba40-49ee-a722-57d820f48cd3",
                "allocatedPhoneNumberId": "f790b110-41e4-4bac-bcf7-8b117533e010"
            }
        ]
    },
    "error": null
}

Creating a New Phone Number

The following steps detail the process of Creating a new Phone Number using the Create Business Phone Number Endpoint.

Step 1 - Get Token

Check out the Authentication Endpoints to get a token.

Step 2 - Gather Relationship IDs

Phone number assignment is based around the related Relationship IDs. Creating and Updating a phone number can use the same Body format with various Relationship IDs to determine phone number assignment.

Using First Orion Portal

1. Login

2. Notice the Business ID behind "business/" in the URL. Save that for later.

   

3. Scroll down and click a Business Unit.

4. 

   Notice the Business Unit ID behind "businessUnit/" in the URL. Save that for later.

5. 

   While at the Business Unit Level, scroll down and click a Program (Not Pictured). Notice the Program ID on the bottom left. Save that for later.

   

Using First Orion API

1. Use the List Business Endpoint to pull your businesses information. Save the Business ID in the response (See response to endpoint in documentation).
2. Use the List Business Units Endpoint to pull the business units. Save the desired Business Unit ID.
3. Use the List Programs Endpoint to pull the programs. Save the desired Program ID.

Step 3 - Build and Submit the Request

Delivery Channels

Delivery Channels in First Orion's platform dictate what kind of Branding and or Blocking behavior a Program and the associated Phone Numbers should have. This is how we assign INFORM Text and Logo (Image) Branding and SENTRY Blocking to a Phone Number. For more detailed information on delivery channels, see this guide. Here are the delivery channel types.

• callerName - Text Branding
• callerImage - Logo and Text Branding
• blocking - Sentry

Build Request URL

The URL will determine where to assign the Phone Number. Notice the variables in the curly braces {}. Use the Business ID, Business Unit ID, and Program ID gathered earlier. The delivery channel should reflect the type of program.

• {environmentUrl}/exchange/v1/businesses/{businessId}/business-units/{businessUnitId}/programs/{programId}/delivery-channels/{deliveryChannel}/a-numbers

Build Request Body

1. Call Purpose Code - This is used by carriers. Find the full list of codes here.
2. Authenticated Calls - If you are using standard INFORM, this will stay false. If you are using Authenticated Call Branding, this will be true.
3. Phone Number - The phone number to Create in E.164 format.

Submit the Request

Check the second tab for a cURL example.

1. Set the request method to POST.
2. Add the business Authorization Token to the header.
3. Fill in the request body data.
4. Submit the request.

[
  {
    "phoneNumber": "+12125554200",
    "callPurposeCode": "CS",
    "authenticatedCalls": false
  }
]

curl --request POST \
     --url https://api.firstorion.com/exchange/v1/businesses/719d140e-fd6c-4d59-9241-3dee71b38320/business-units/ec0ce06a-3739-45f5-a804-5468e60a843f/programs/df567c99-9354-47e5-b30f-88ee7cbfeab4/delivery-channels/callerName/a-numbers \
     --header 'Authorization: token string' \
     --header 'Ccontent-Type: application/json' \
     --data '
[
  {
    "phoneNumber": "+12125554200",
    "callPurposeCode": "CS",
    "authenticatedCalls": false
  }
]
'

{
  "body": {
    "phoneNumbers": [
      {
        "phoneNumberId": "0dd9a02c-03f9-49d5-aa83-7e9498fbe74f",
        "phoneNumber": "+12125554200",
        "lastStatusChangeTimestamp": "1639711517",
        "submittedTimestamp": "1639711517",
        "status": "PENDING",
        "callPurposeCode": "CS",
        "authenticatedCalls": false,
        "relationships": {
          "businessId": "719d140e-fd6c-4d59-9241-3dee71b38320",
          "businessUnitId": "ec0ce06a-3739-45f5-a804-5468e60a843f",
          "programId": "df567c99-9354-47e5-b30f-88ee7cbfeab4",
          "callerName": true
        }
      }
    ],
    "rejectedPhoneNumbers": []
  },
  "error": null
}

Updating an Existing Phone Number

The following steps detail the process of Updating a Phone Numbers relationship to update the Branding/behaviour.

Step 1 - Get Token

Check out the Authentication Endpoints to get a token.

Step 2 - Build Your Request Body

Check Step 2 - Gather Relationship IDs under the Creating a New Phone Number section to learn how to get other relationship IDs.

This Step will be broken down into the following sections:

• Assign to new Program and Business Unit
• Assign to Business Unit Only

Assign to New Program and Business Unit

When updating a phone number to a different Program, the phone number FIRST has to be removed from the Program and/or Business Unit.

Notice:

1. The first request DELETEs the phone number from the program. It uses the original Business Unit and Program ID. Make sure to include the Phone Number ID, if left out it could DELETE other phone numbers in the program.
2. The second request updates the program and delivery channel with the existing phone numbers. It uses the original Business Unit and new Program ID.

curl --location --request DELETE 'https://api.firstorion.com/exchange/v1/businesses/719d140e-fd6c-4d59-9241-3dee71b38320/business-units/ec0ce06a-3739-45f5-a804-5468e60a843f/programs/df567c99-9354-47e5-b30f-88ee7cbfeab4/delivery-channels/callerName/a-numbers/jd73nhdf8s-7aja-9tj6-8eb0-82jdhnd73ns0' \
--header 'Authorization: token' \
--header 'Content-Type: application/json'

curl --location --request PUT 'https://api.firstorion.com/exchange/v1/businesses/719d140e-fd6c-4d59-9241-3dee71b38320/business-units/ec0ce06a-3739-45f5-a804-5468e60a843f/programs/6d3580a0-f667-425e-84b5-e7df13cc3e1b/delivery-channels/callerName/a-numbers' \
--header 'Authorization: token' \
--header 'Content-Type: application/json' \
--data '{

"phoneNumbers": [
    "+12125554200"
  ]
}'

Notice:

1. The first request DELETEs the phone number from the program and business unit. It uses the original Business Unit and Program ID. Make sure to include the Phone Number ID, if left out it could DELETE other phone numbers in the program. Notice how the URL does not have the program or delivery channel information.
2. The second request updates the program and delivery channel with the existing phone numbers. It uses the new Business Unit and new Program ID. Notice how the program and delivery channel information is back in the URL.

curl --location --request DELETE 'https://api.firstorion.com/exchange/v1/businesses/719d140e-fd6c-4d59-9241-3dee71b38320/business-units/ec0ce06a-3739-45f5-a804-5468e60a843f/phone-numbers/jd73nhdf8s-7aja-9tj6-8eb0-82jdhnd73ns0' \
--header 'Authorization: token' \
--header 'Content-Type: application/json'

curl --location --request PUT 'https://api.firstorion.com/exchange/v1/businesses/719d140e-fd6c-4d59-9241-3dee71b38320/business-units/qbymn4fd-dgy9-nfb6-4ham-7ohen2plvkmm
/programs/8jj2mqcf-vf7m-wjob-g5gc-92478co69n11/delivery-channels/callerName/a-numbers' \
--header 'Authorization: token' \
--header 'Content-Type: application/json' \
--data '{

"phoneNumbers": [
    "+12125554200"
  ]
}'

Assign to New Business Unit Only

This will only associate the Phone Number up to the Business Unit level. This will result in no Branding.

Notice:

1. The first request removes the phone number from the program, so it's only assign up to the Business Unit level.
2. The second request removes from the current Business Unit for the third request.
3. The third request assigns to a new Business Unit. Notice the different Business Unit IDs.

curl --location --request DELETE 'https://api.firstorion.com/exchange/v1/businesses/719d140e-fd6c-4d59-9241-3dee71b38320/business-units/ec0ce06a-3739-45f5-a804-5468e60a843f/programs/df567c99-9354-47e5-b30f-88ee7cbfeab4/delivery-channels/callerName/a-numbers/jd73nhdf8s-7aja-9tj6-8eb0-82jdhnd73ns0' \
--header 'Authorization: token' \
--header 'Content-Type: application/json'

curl --location --request DELETE 'https://api.firstorion.com/exchange/v1/businesses/719d140e-fd6c-4d59-9241-3dee71b38320/business-units/ec0ce06a-3739-45f5-a804-5468e60a843f/phone-numbers/jd73nhdf8s-7aja-9tj6-8eb0-82jdhnd73ns0' \
--header 'Authorization: token' \
--header 'Content-Type: application/json'

curl --location --request PUT 'https://api.firstorion.com/exchange/v1/businesses/719d140e-fd6c-4d59-9241-3dee71b38320/business-units/qbymn4fd-dgy9-nfb6-4ham-7ohen2plvkmm
/phone-numbers' \
--header 'Authorization: token' \
--header 'Content-Type: application/json' \
--data '{

"phoneNumbers": [
    "+12125554200"
  ]
}'

Delete Phone Numbers

Step 1 - Get Token

Check out the Authentication Endpoints to get a token.

Step 2 - Select Delete Method and Submit the Request

Deleting will remove the Phone Number from the business completely. This is useful for cleaning out a phone number inventory in the First Orion platform.

Endpoints:

1. Delete All Phone Numbers - DO NOT USE. This is only useful for deleting every phone number registered to the business.

curl --request DELETE \
     --url https://api.firstorion.com/exchange/v1/businesses/businessId/phone-numbers \
     --header 'accept: application/json'

2. Delete Phone Number - NOT RECOMMENDED TO USE. This is similar to the first endpoint. If the Phone Number ID isn't added to the URL, ALL Phone Numbers under that Business could be deleted.

curl --request DELETE \
     --url https://api.firstorion.com/exchange/v1/businesses/businessId/phone-numbers/x7ssz559-62a8-v3d2-p7xa-0wafb6ljzei1 \
     --header 'accept: application/json'

3. Delete Phone Numbers - RECOMMENDED. This endpoint requires a request body with a list of Phone Numbers or Phone Number IDs. This makes it the most convenient and safest way to Delete Phone Numbers from a Business. Notice this is a POST method with a new URL instead of DELETE.
   • Notice the two different requests. Both requests will delete the same phone numbers.

curl --request POST \
     --url https://api.firstorion.com/exchange/v1/businesses/businessId/phone-numbers/DELETE \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "phoneNumbers": [
    "+12125554200"
  ]
}
'

curl --request POST \
     --url https://api.firstorion.com/exchange/v1/businesses/businessId/phone-numbers/DELETE \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "phoneNumberIds": [
    "0dd9a02c-03f9-49d5-aa83-7e9498fbe74f"
  ]
}
'