SMSWhatsAppVoiceVideoAPIIntegrationRelease NotesFAQs
Guides
Contact UsKaleyra.io Sign InSupport

List the Available Numbers for Subscriptions

GET Method

Suggest Edits

kaleyra.io enables you to get the list of numbers available for subscriptions using this API. These subscribed numbers can be utilized to send and/or receive SMS or Voice Calls. You can get a list of 50 available numbers per single API request.

The following number types are available for subscription:

  • Mobile
  • Toll-free
  • Fixed Line
  • Shared

The available numbers listed in the response can be filtered by using the following number type parameter:

  • SMS
  • Voice
  • SMS/Voice

📘

Note:

SMS type will list only numbers capable of sending/receiving SMS. Voice Type will list only numbers capable of sending/receiving voice calls. “SMS/Voice“ will list numbers with either Voice capabilities or SMS capabilities will be listed.

Base URL

https://<api_domain>/v1/<SID>

API Domain and Value

api_domainValue
IN podapi.in.kaleyra.io
SG Podapi.ap.kaleyra.io
EU Podapi.eu.kaleyra.io

API Request to Get the Numbers Available for Subscription on kaleyra.io Platform

To get the list of numbers available for subscription on kaleyra.io platform, use the <api_domain>/v1/<sid>/number endpoint with the following request method:

Request Format

The following is the request format to get the numbers available for subscription on the kaleyra.io platform:

curl -X GET 'https://<api_domain>/v1/<sid>/number/available-numbers?iso_code=<iso_code>&capabilities=<capabilities>&number_type=<number_type>&limit=<limit>&number=<number>&offset=<offset>' \
  -H 'api-key:<api-key>'

Sample Request Format

The following is the sample request format to get the numbers available for subscription on the kaleyra.io platform:

curl -X GET 'https://api.in.kaleyra.io/v1/HXAP16XXXXXX97IN/number/available-numbers?iso_code=in&capabilities=voice,sms&number_type=mobile&limit=2&number=91&offset=0' \
  -H 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3'

URL Parameters and Headers

Following is the list of parameters and headers to send the API request:

HeadersData TypeDescriptionExampleMandatory?
sidStringAccount SID (Security Identifier).HXAP16XXXXXX97INYes
api-keyStringAPI key generated from kaleyra.io account.Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3Yes

Following is the list of attributes to be used in the payload to send the API request:

ParameterData TypeDescriptionExampleMandatory?
iso_codeISO CodeThe country ISO code for which you want to search the number available for subscriptions. ISO code should be 2 alpha standards. For more information, see ISO 3166-1 alpha-2.inYes
capabilitiesStringThe capability of the numbers you want to be returned in the response. Allowed values are SMS, voice, or SMS/voice.smsNo
number_typeStringThe number type for which you want to subscribe the new number.
The following are the supported number types:

- Mobile
- Toll-free
- Fixed Line
- Shared		mobileNo
limitIntegerSpecifies the number of elements returned in the response. You can list a maximum of 50 numbers in response.2No
numberStringAny set of consecutive digits you want the returned number to have.91No
offsetIntegerPosition in the dataset of a particular record. By specifying an offset, you retrieve a subset of records starting with the offset value. By default, offset is set to 0 (which returns result for the first X contacts found where X is equal to value set for limit query param).0No

Response Format

This section provides you the success and failure JSON response formats for different scenarios.

Success Response

The following success response is received when the JSON script has the correct syntax:

{
    "code": "CLE402",
    "message": "Request executed successfully",
    "data": [
        {
            "number": "919972xxxxxx",
            "number_id": "SG_75xxxx69-3xxe-4xx5-axx4-aexxxxxxxxfa",
            "country_name": "India",
            "number_type": "Mobile",
            "number_status": "0",
            "monthly_recurring_cost": "1.000000",
            "setup_cost": "1.000000",
            "currency_code": "USD",
            "capabilities": [
                "voice_in",
                "voice_out"
            ]
        },
        {
            "number": "918917xxxxxx",
            "number_id": "SG_e5xxxx88-fxxb-4xx3-9xxc-f1xxxxxxxx80",
            "country_name": "India",
            "number_type": "Mobile",
            "number_status": "0",
            "monthly_recurring_cost": "1.000000",
            "setup_cost": "1.000000",
            "currency_code": "USD",
            "capabilities": [
                "voice_in",
                "voice_out"
            ]
        },
    ],
    "total": 3,
    "offset": "0",
    "limit": "3",
    "error": null
}

Failure Responses

The following failure responses are received when the JSON script has an incorrect syntax:

{
    "code": "CLE404",
    "status": 400,
    "message": "Invalid Inputs, Validation Error.",
    "error": {
        "scalar": "The provided country code is invalid."
    }
}

{
    "code": "CLE404",
    "status": 400,
    "message": "Invalid Inputs, Validation Error.",
    "error": {
        "scalar": "The provided capability is invalid."
    }
}

{
    "code": "CLE404",
    "status": 400,
    "message": "Invalid Inputs, Validation Error.",
    "error": {
        "scalar": "The provided number type is invalid."
    }
}

{
    "code": "CLE404",
    "status": 400,
    "message": "Invalid Inputs, Validation Error.",
    "error": {
        "scalar": "The maximum limit allowed is 50."
    }
}

{
    "code": "RBC001",
    "message": "Incorrect SID or API key.",
    "data": [],
    "error": {
        "body": "Incorrect SID or API key.",
        "error": "record not found"
    }
}

{
    "code": "RBC201",
    "message": "Incorrect SID or API key.",
    "data": [],
    "error": {
        "body": "Incorrect SID or API key.",
        "error": "API Key Not Found"
    }
}

Updated 7 days ago