Home
/
Virtual Numbers
/
Search

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 suit their needs.

Query
countrystringrequired

Country

Example: country=United States
sizeintegerrequired

The maximum number of items to return

Example: size=10
statestring

State

Example: state=New York
numberTypestring

Number Type e.g.(Mobile, Geographic, Non-Geographic, Toll-Free or UIFN)

Example: numberType=Geographic
numberCategorystring

Number Category e.g.(Voice, Voice+SMS)

Example: numberCategory=Voice
digitsstring

Digits

Example: digits=888
Headers
accountIdstringrequired

Account Id of the customer

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 find a specific virtual number within the system. You can use this endpoint to retrieve detailed information about a particular virtual number, including its status and configuration.

Query
numberstringrequired

Number

Example: number=16091609123
Headers
accountIdstringrequired

Account Id of the customer

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 that have been purchased by their account. The endpoint returns details about each number, enabling you to programmatically manage virtual numbers within your application.

Query
sizeintegerrequired

The maximum number of items to return

Example: size=10
accessNumberstring

The Access Number

Example: accessNumber=16091609123
numberTypestring

The Number Type

Example: numberType=Geographic
countrystring

The Country

Example: country=United States
statestring

The State

Example: state=New York
Headers
accountIdstringrequired

Account Id of the customer

curl -i -X GET \
  'https://api.integrari.com/o/virtual-numbers/v1.0/purchased-list?accessNumber=16091609123&country=United%20States&numberType=Geographic&size=10&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

Account Id of the customer

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

Account Id of the customer

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

Account Id of the customer

Body

Release Virtual Numbers

numbersArray of strings
Example: [["16096294649","16096294671"]]
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",
        "16096294671"
      ]
    ]
  }'

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"
}