Home
/
Virtual Numbers
/
Regions

Virtual Numbers

The Virtual Numbers API in Integrari allows the management of virtual numbers, including purchasing, searching, listing, and releasing them. Virtual numbers can be configured for call routing, tracking, and messaging. These APIs provide functionality to search available numbers by region or type, manage purchased numbers, and access regional availability, giving your application flexible control over virtual number operations.

Languages
Servers
https://api.integrari.com/o/

Search

Request

This API allows developers to search for available virtual numbers based on specific criteria, such as country, region, or number type. By integrating this endpoint, you can provide search functionality within your application to help users find virtual numbers that meet their needs.

Query
countrystringrequired

The country to search for virtual numbers. This parameter is required to narrow the search to numbers available within a specific country.

Example: country=United States
sizeintegerrequired

The maximum number of virtual numbers to return in the response. Use this parameter to limit the result set for pagination.

Example: size=10
statestring

The state or region within the specified country to refine the search results. If omitted, the search will include numbers from all regions in the specified country.

Example: state=New York
numberTypestring

The type of virtual number to search for. Valid options include Mobile, Geographic, Non-Geographic, Toll-Free, or UIFN. If omitted, the search will include all number types.

Example: numberType=Geographic
numberCategorystring

The category of the virtual number to search for. Valid options include Voice or Voice+SMS. Use this to filter results based on functionality.

Example: numberCategory=Voice
digitsstring

A specific sequence of digits to search for in the virtual numbers. Use this to find numbers containing a particular pattern (e.g., vanity numbers).

Example: digits=888
Headers
accountIdstringrequired

The unique identifier for the customer's account, used for authentication and tracking.

curl -i -X GET \
  'https://api.integrari.com/o/virtual-numbers/v1.0/search?country=United%20States&digits=888&numberCategory=Voice&numberType=Geographic&size=10&state=New%20York' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'accountId: string'

Responses

A List of Available Numbers

Body
dataArray of objects
messagestring
Example: "The request has succeeded"
statusstring
Example: "OK"
totalinteger
Example: "1"
Response
{
  "data": [
    {
      "cityCoverage": "Birmingham",
      "country": "United States",
      "countryCode": "1",
      "state": "New Jersey",
      "number": "+16091609123",
      "numberCategory": "Voice+SMS",
      "numberType": "Geographic",
      "initialBlock": "6",
      "regularBlock": "6",
      "setupCharge": "0.10",
      "recurringCharge": "0.10",
      "rate": "0.7000",
      "smsRate": "0.0013"
    }
  ],
  "message": "The request has succeeded",
  "status": "OK",
  "total": "1"
}

Find Number

Request

This API allows developers to retrieve detailed information about a specific virtual number within the system. The response includes details such as the number's current status and configuration. Use this endpoint to manage and monitor individual virtual numbers programmatically.

Query
numberstringrequired

The virtual number to look up. This parameter is required and must be provided in the international E.164 format (e.g., +16091609123).

Example: number=16091609123
Headers
accountIdstringrequired

The unique identifier for the customer's account, used to authenticate and authorize the request.

curl -i -X GET \
  'https://api.integrari.com/o/virtual-numbers/v1.0/find-number?number=16091609123' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'accountId: string'

Responses

The request has succeeded

Body
dataArray of objects
messagestring
Example: "The request has succeeded"
statusstring
Example: "OK"
totalinteger
Example: "1"
Response
{
  "data": [
    {
      "cityCoverage": "Birmingham",
      "country": "United States",
      "countryCode": "1",
      "state": "New Jersey",
      "number": "+16091609123",
      "numberCategory": "Voice+SMS",
      "numberType": "Geographic",
      "initialBlock": "6",
      "regularBlock": "6",
      "setupCharge": "0.10",
      "recurringCharge": "0.10",
      "rate": "0.7000",
      "smsRate": "0.0013"
    }
  ],
  "message": "The request has succeeded",
  "status": "OK",
  "total": "1"
}

Purchased List

Request

This API allows developers to retrieve a list of virtual numbers purchased by their account. The endpoint provides details about each number, enabling programmatic management of virtual numbers within your application.

Query
accessNumberstring

A specific virtual number to filter the results. If not provided, results will include all numbers.

Example: accessNumber=16091609123
numberTypestring

The type of virtual number to filter the results (e.g., Geographic, Mobile). If omitted, results will include all number types.

Example: numberType=Geographic
countrystring

The country associated with the virtual numbers. Use this to filter results by country. If omitted, results will include numbers from all countries.

Example: country=United States
statestring

The state or region associated with the virtual numbers. Use this to filter results by state. If omitted, results will include numbers from all states.

Example: state=New York
pageNumberstring

Specify the page number for pagination.

Example: pageNumber=1
pageLimitstring

Define the maximum number of records per page.

Example: pageLimit=0
Headers
accountIdstringrequired

The unique identifier for the customer's account, used to authenticate the request.

curl -i -X GET \
  'https://api.integrari.com/o/virtual-numbers/v1.0/purchased-list?accessNumber=16091609123&country=United%20States&numberType=Geographic&pageLimit=0&pageNumber=1&state=New%20York' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'accountId: string'

Responses

The request has succeeded

Body
dataArray of objects
messagestring
Example: "The request has succeeded"
statusstring
Example: "OK"
totalinteger
Example: "1"
Response
{
  "data": [
    {
      "accessNumber": "+12050032925",
      "assignment": {
        "flowID": "169",
        "flowName": "Test Recon",
        "type": "Flow Builder"
      },
      "assignmentType": "IPPBX",
      "country": "United States",
      "customerId": "190",
      "mrc": "0.10",
      "nrc": "0.10",
      "numberType": "Geographic",
      "smsRate": "0.0013",
      "voiceRate": "0.7000"
    }
  ],
  "message": "The request has succeeded",
  "status": "OK",
  "total": "1"
}

Regions

Request

This API allows developers to retrieve information about the regions where virtual numbers are available. Use this endpoint to display available regions to users when searching or purchasing virtual numbers, ensuring they can select numbers from the desired location.

Query
numberTypesstring

Only return regions for which numbers are provided with the given types: Mobile, Geographic, Nongeographic, Toll-Free or UIFN. For multiple value send comma seprated number types

Example: numberTypes=Geographic
Headers
accountIdstringrequired

The unique identifier for the customer's account, used to authenticate the request.

curl -i -X GET \
  'https://api.integrari.com/o/virtual-numbers/v1.0/regions?numberTypes=Geographic' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'accountId: string'

Responses

The request has succeeded

Body
dataArray of objects
messagestring
Example: "The request has succeeded"
statusstring
Example: "OK"
Response
{
  "data": [
    {
      "regionName": "United States",
      "types": [
        "Geographic",
        "Mobile"
      ]
    }
  ],
  "message": "The request has succeeded",
  "status": "OK"
}

Purchase Numbers

Request

This API allows developers to programmatically purchase virtual numbers from the Integrari IPPBX system. Using this endpoint, you can acquire new virtual numbers for your application, enabling features such as call routing, tracking, and messaging.

Headers
accountIdstringrequired

The unique identifier for the customer's account, used to authenticate the request.

Body

Purchase Virtual Numbers

sipTrunkIdinteger
Example: "169"
numbersArray of strings
Example: ["12050012202"]
curl -i -X POST \
  https://api.integrari.com/o/virtual-numbers/v1.0/purchase-numbers \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'accountId: string' \
  -d '{
    "sipTrunkId": "169",
    "numbers": [
      "12050012202"
    ]
  }'

Responses

The request has succeeded

Body
dataArray of objects
messagestring
Example: "The request has succeeded"
statusstring
Example: "OK"
Response
{
  "data": [
    {
      "success": {
        "numbers": [
          {
            "accessNumber": "12050012202",
            "message": "Number Purchased Successfully"
          }
        ]
      },
      "error": {
        "numbers": [
          {
            "accessNumber": "12012334233",
            "message": "Not able to purchase the number"
          }
        ]
      }
    }
  ],
  "message": "The request has succeeded",
  "status": "OK"
}

Release Numbers

Request

This API allows developers to release a virtual number that is no longer needed. Use this endpoint to programmatically remove virtual numbers from your account.

Headers
accountIdstringrequired

The unique identifier for the customer's account, used to authenticate the request.

Body

Release Virtual Numbers

numbersArray of strings
Example: ["16096294649"]
curl -i -X POST \
  https://api.integrari.com/o/virtual-numbers/v1.0/release-numbers \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'accountId: string' \
  -d '{
    "numbers": [
      "16096294649"
    ]
  }'

Responses

The request has succeeded

Body
dataArray of objects
messagestring
Example: "The request has succeeded"
statusstring
Example: "OK"
Response
{
  "data": [
    {
      "success": {
        "numbers": [
          {
            "accessNumber": "16096294649",
            "message": "Number Released Successfully"
          }
        ]
      },
      "error": {
        "numbers": [
          {
            "accessNumber": "16096294671",
            "message": "Number Cannot be Released because it is associated with the flow builder"
          }
        ]
      }
    }
  ],
  "message": "The request has succeeded",
  "status": "OK"
}