Subscribe a Number

kaleyra.io enables you to subscribe to a number available for rent using this API. After successfully subscribing to a number, it gets added to your kaleyra.io platform account and you can leverage the features available with the subscribed number.

📘

Note:

kaleyra.io supports only subscriptions for a number using API at a time. In case, if the list has more than one number in your request, then only the first number in the API request will be subscribed.

Base URL

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

API Domain and Value

API Request to Subscribe to a Number

To subscribe to a number, use the <api_domain>/v1/<sid>/number/subscriptions endpoint with the following request method:

Request Format

The following is the request format to subscribe to a number available for rent on the kaleyra.io platform:

curl -X POST 'https://<api_domain>/v1/<sid>/number/subscriptions' \
  -H 'api-key: <api-key>' \
  -H "Content-Type: <content-type>"\
  -d '{
    "numbers": [
        "<numbers>"
    ],
    "document_ids": {
        "<document_ids>": "<document_ids_list>"
    }
}'

Sample Request Format

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

curl -X POST 'https://api.in.kaleyra.io/v1/HXAP16XXXXXX97IN/number/subscriptions' \
  -H 'api-key: Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx3' \
 	-H "Content-Type: application/json"\  
  -d '{
    "numbers": [
        "911234xxxxxx"
    ],
    "document_ids": {
        "5": "12xx5"
    }
}'

URL Parameters and Headers

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

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

📘

Note:

kaleyra.io currently supports only subscriptions for one number. In case, if the list has more than one number in your request, then only the first number in the request will be subscribed.

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 with status code 200 OK:

{
    "code": "CLE271",
    "message": "Number purchase completed successfully",
    "data": [
        {
            "subscription_id": "SG_fdxxxx95-fxx3-4xxe-axx0-c2xxxxxxxxb6",
            "number": "911234xxxxxx",
            "number_id": "SG_0fxxxx50-0xxb-4xx4-bxxa-dcxxxxxxxxe3",
            "monthly_recurring_cost": "83.99",
            "setup_cost": "83.99",
            "currency_code": "INR",
            "document_ids": "{\"5\":[12xx5]}",
            "status": "Under Verification"
        }
    ],
    "error": null
}

Failure Responses

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

When the numbers field is empty in the request method with status code 200 OK:

{
    "code": "CLE272",
    "message": "Number is not available for subscription.",
    "error": {
        "scalar": "Number not available"
    }
}

When the request is sent without a body with status code 400 Bad Request:

{
    "code": "CLE404",
    "status": 400,
    "message": "Invalid Inputs, Validation Error.",
    "error": {
        "scalar": "Invalid request format provided."
    }
}