---
updatedAt: 2026-06-05T20:14:09.000Z
---

# List Phone Numbers

Retrieve a list of all registered phone numbers of a business.

# OpenAPI definition

```json
{
  "openapi": "3.0.2",
  "info": {
    "version": "1.0",
    "title": "Branded Communications Exchange",
    "termsOfService": "https://firstorion.com/terms-use/",
    "x-logo": {
      "url": "https://firstorion.com/wp-content/themes/salient-child/img/logo-icon-blue.svg",
      "backgroundColor": "rgba(0,0,0,0)",
      "altText": "First Orion Logo"
    },
    "description": "> Please avoid using APIs that are marked `deprecated`. While the functions / endpoints will work for the time being, they will be deprecated in the next major release of the APIs.\n",
    "license": {
      "url": "change this and name",
      "name": "Apache 2.0"
    }
  },
  "servers": [
    {
      "url": "https://api.firstorion.com",
      "description": "Production Environment"
    },
    {
      "url": "https://api.forp-lab.com",
      "description": "Integration Environment"
    }
  ],
  "components": {
    "schemas": {
      "businessId": {
        "type": "string",
        "description": "System generated unique identifier for the business",
        "example": "719d140e-fd6c-4d59-9241-3dee71b38320"
      },
      "phoneNumber": {
        "type": "string",
        "description": "Phone number in E.164 format.",
        "minimum": 7,
        "maximum": 15,
        "pattern": "^\\+[1-9]\\d{1,14}$",
        "example": "+12125554200"
      },
      "businessUnitId": {
        "type": "string",
        "description": "System generated unique identifier for the business unit.",
        "example": "ec0ce06a-3739-45f5-a804-5468e60a843f"
      },
      "programId": {
        "type": "string",
        "description": "System generated unique identifier for the program",
        "example": "df567c99-9354-47e5-b30f-88ee7cbfeab4"
      },
      "phoneNumberId": {
        "type": "string",
        "readOnly": true,
        "description": "System generated unique identifier of a phone number",
        "example": "0dd9a02c-03f9-49d5-aa83-7e9498fbe74f"
      },
      "lastStatusChangeTimestamp": {
        "type": "string",
        "readOnly": true,
        "description": "Epoch timestamp of the last time this phone number's attributes were changed",
        "example": "1639711517"
      },
      "submittedTimestamp": {
        "type": "string",
        "readOnly": true,
        "description": "Epoch timestamp of when the phone number was originally submitted/registered",
        "example": "1639711517"
      },
      "PhoneNumber-status": {
        "type": "string",
        "readOnly": true,
        "description": "A system managed field indicating if the number has passed First Orion's number verification process",
        "enum": [
          "PENDING",
          "UNDER_REVIEW",
          "REJECTED",
          "APPROVED"
        ],
        "default": "PENDING",
        "example": "PENDING"
      },
      "callPurposeCode": {
        "type": "string",
        "description": "The most common purpose why the phone number is making calls. Must be one of `GET /exchange/v1/reference-data/call-purposes`",
        "example": "CS"
      },
      "authenticatedCalls": {
        "type": "boolean",
        "description": "Is the phone number used to make Verified calls",
        "default": false
      },
      "relationships": {
        "type": "object",
        "description": "Association of the phone number with Business, Business Units, Programs, etc.",
        "properties": {
          "businessId": {
            "$ref": "#/components/schemas/businessId"
          },
          "businessUnitId": {
            "$ref": "#/components/schemas/businessUnitId"
          },
          "programId": {
            "$ref": "#/components/schemas/programId"
          },
          "callerName": {
            "type": "boolean",
            "description": "Is the number associated with a callername delivery channel",
            "example": true
          }
        }
      },
      "PostPhoneNumberApproved": {
        "allOf": [
          {
            "type": "object"
          }
        ],
        "properties": {
          "phoneNumberId": {
            "$ref": "#/components/schemas/phoneNumberId"
          },
          "phoneNumber": {
            "$ref": "#/components/schemas/phoneNumber"
          },
          "lastStatusChangeTimestamp": {
            "$ref": "#/components/schemas/lastStatusChangeTimestamp"
          },
          "submittedTimestamp": {
            "$ref": "#/components/schemas/submittedTimestamp"
          },
          "status": {
            "$ref": "#/components/schemas/PhoneNumber-status"
          },
          "callPurposeCode": {
            "$ref": "#/components/schemas/callPurposeCode"
          },
          "authenticatedCalls": {
            "$ref": "#/components/schemas/authenticatedCalls"
          },
          "relationships": {
            "$ref": "#/components/schemas/relationships"
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Unauthorized"
      },
      "Forbidden": {
        "description": "Forbidden"
      },
      "BusinessUnitResourceNotFound": {
        "description": "Not Found",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "description": "Response",
              "properties": {
                "body": {
                  "type": "object",
                  "nullable": true,
                  "example": null
                },
                "error": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "Error code",
                      "example": 404
                    },
                    "message": {
                      "type": "string",
                      "description": "Description of the error",
                      "example": "rpc error: code = NotFound desc = business unit not found"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "BusinessUnitBadRequest": {
        "description": "Bad Request",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "description": "Response",
              "properties": {
                "body": {
                  "type": "object",
                  "nullable": true,
                  "example": null
                },
                "error": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string",
                      "description": "Error code",
                      "example": 400
                    },
                    "message": {
                      "type": "string",
                      "description": "Description of the error",
                      "example": "path validation failed for field businessUnitId: value is required"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "x-tagGroups": [
    {
      "name": "Authentication",
      "tags": [
        "Authentication",
        "OAuth2.0"
      ]
    },
    {
      "name": "Businesses",
      "tags": [
        "Businesses",
        "Business Addresses",
        "Business Contacts",
        "Business Images",
        "Business API Keys",
        "Business Units"
      ]
    },
    {
      "name": "Phone Numbers",
      "tags": [
        "Business Phone Numbers",
        "Business Unit Phone Numbers",
        "CallerName aNumbers"
      ]
    },
    {
      "name": "Programs",
      "tags": [
        "Programs",
        "Schedules"
      ]
    },
    {
      "name": "Program Delivery Channels",
      "tags": [
        "Delivery Channels",
        "CallerName",
        "CallerImage",
        "Blocking",
        "Engage SDK"
      ]
    },
    {
      "name": "Call Authentication",
      "tags": [
        "Call Authentication",
        "Call Authentication V2",
        "PreCall Engage SDK"
      ]
    },
    {
      "name": "Reference Data",
      "tags": [
        "Employee Count Ranges",
        "Daily Call Count Ranges",
        "Industries",
        "Call Purposes"
      ]
    },
    {
      "name": "Utilities",
      "tags": [
        "Phone Number Verification"
      ]
    }
  ],
  "paths": {
    "/exchange/v1/businesses/{businessId}/business-units/{businessUnitId}/phone-numbers": {
      "summary": "Business Unit Phone Numbers",
      "parameters": [
        {
          "name": "Authorization",
          "in": "header",
          "required": true,
          "schema": {
            "type": "string"
          },
          "example": "<token>",
          "description": "Access Token"
        },
        {
          "name": "businessId",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/businessId"
          }
        },
        {
          "name": "businessUnitId",
          "in": "path",
          "required": true,
          "schema": {
            "$ref": "#/components/schemas/businessUnitId"
          }
        }
      ],
      "get": {
        "summary": "List Phone Numbers",
        "description": "Retrieve a list of all registered phone numbers of a business.",
        "operationId": "GetBusinessesUnitPhoneNumbers",
        "tags": [
          "Business Unit Phone Numbers"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 1024,
              "default": 20,
              "example": 500
            },
            "description": "How many items are included in the response"
          },
          {
            "in": "query",
            "name": "pageHash",
            "schema": {
              "type": "string",
              "example": "systemProvidedHashString"
            },
            "description": "Page identifier"
          },
          {
            "in": "query",
            "name": "phoneNumber",
            "required": false,
            "schema": {
              "type": "string",
              "example": "+1212"
            },
            "description": "List phone numbers that start with '+1212'"
          },
          {
            "in": "query",
            "name": "programId",
            "required": false,
            "schema": {
              "type": "string",
              "example": "df567c99-9354-47e5-b30f-88ee7cbfeab4"
            },
            "description": "Filter phone numbers that are associated with the provided program. Filtering is done as strict, exact match."
          },
          {
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "type": "string",
              "example": "APPROVED",
              "enum": [
                "APPROVED",
                "REJECTED",
                "PENDING"
              ]
            },
            "description": "Filter based on approval status of the number."
          },
          {
            "in": "query",
            "name": "callPurposeCode",
            "required": false,
            "schema": {
              "type": "string",
              "example": "CS",
              "enum": [
                "CS",
                "OB",
                "See reference data for full list."
              ]
            },
            "description": "Filter based on call purpose of number."
          },
          {
            "in": "query",
            "name": "authenticatedCalls",
            "required": false,
            "schema": {
              "type": "boolean",
              "enum": [
                true,
                false
              ],
              "description": "Filter phone numbers by their call authenication status."
            }
          },
          {
            "in": "query",
            "name": "callerName",
            "required": false,
            "schema": {
              "type": "boolean",
              "enum": [
                true,
                false
              ]
            },
            "description": "Filter phone numbers that are associated with a callerName delivery channel in a program."
          },
          {
            "in": "query",
            "name": "rcd",
            "required": false,
            "schema": {
              "type": "boolean",
              "enum": [
                true,
                false
              ]
            },
            "description": "Filter phone numbers that are associated with a rcd delivery channel in a program."
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "body": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/PostPhoneNumberApproved"
                      }
                    },
                    "info": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer",
                          "example": 1
                        },
                        "limit": {
                          "type": "integer",
                          "example": 500
                        },
                        "nextPage": {
                          "type": "string",
                          "example": ""
                        }
                      }
                    },
                    "error": {
                      "type": "string",
                      "example": null
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BusinessUnitBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/BusinessUnitResourceNotFound"
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false
  }
}
```