Bulk Device Lookup

POST Method

The Bulk Device Lookup API allows you to look up the RCS capability of multiple mobile devices in a single request.

📘
Note:
Numbers are validated for E.164 format, deduplicated, and only valid unique numbers are sent in the request.

E.164 Validation and Normalization

The following points must be considered for E.164 validation and normalization:

Numbers without a + prefix are automatically normalized. For example. The number gets normalized from 917XXXXX2804 to +917XXXXX2804 automatically.
Numbers must have 7–15 digits after the + prefix, with the first digit being in the range of 1 to 9.
Empty strings, whitespace-only strings, and numbers not matching E.164 are filtered as invalid.
Duplicate numbers get removed after validation.
Only valid and unique numbers are sent in the request.

Limitations

The following are the limitations for the bulk device lookup:

After E.164 validation and deduplication, there must be at least 100 unique valid numbers. For lesser numbers, use the single lookup endpoint.
The current threshold for bulk device lookup ranges from 100 to 500 devices.

Prerequisites

After you sign up, your account will be on the trial version. You must complete the KYC to access all the features in kaleyra.io.
Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
Before sending the RCS, you must configure the RCS channel in the Kaleyra platform. To configure the RCS channel in your account, please contact your local Kaleyra representative.

Base URL

URL	Region
`https://rcs-api.<pod>.kaleyra.io`	For North America (NA).

API Domain and Value

api_domain	Value
NA pod	`https://rcs-api.na.kaleyra.io`

API Request for Bulk Device Lookup

To lookup for multiple devices, use the https://rcs-api.<pod>.kaleyra.io/v1/<sid>/rcs/lookup/bulk endpoint with the following request method:

Request Format

The following is the request format to lookup for multiple devices:

curl --location --request POST 'https://<api_domain>/v1/<sid>/rcs/lookup/bulk'\
--header 'api-key: <api-key>' \
--header 'Content-Type: <content-type>'\
--data '{
    "deviceAddresses": [
        "<phone_number_1>",
        "<phone_number_2>",
        "<phone_number_3>",
        "<phone_number_4>"
        .
        .
				.
    ]
}'

Sample Request Format

The following is a sample request format to lookup for multiple devices:

curl --location --request POST 'https://rcs.api.na.kaleyra.io/v1/xxxxx6913850xxxx/rcs/lookup/bulk'\
--header 'api-key: xxxxx3b8497f58a94e84b671aca43xxxx' \
--header 'Content-Type: application/json'\
--data '{
    "deviceAddresses": [
				"+9170XXXXX804",
        "+9198XXXXX210",
        "+1415XXXX671",
        "917XXXXX804"",
        .
        .
				.
    ]
}'

URL Parameters and Headers

The following is the list of parameters and headers to send the outgoing message request:

Parameter/Headers	Data Type	Description	Example	Mandatory?
`sid`	String	Account SID (Security Identifier).	XXXXX6913850XXXX	Yes
`Content-Type`	String	Indicates the format of the content the API will be processing.	The only allowed value is application/JSON	Yes
`api-key`	String	API key generated from kaleyra.io account.	XXXXX3b8497f58a94e84b671aca43XXXX	Yes

The following is a list of attributes to be used in the payload for lookup for multiple devices:

Parameter	Data Type	Description	Example	Mandatory?
`deviceAddresses`	Array of Strings	List of phone numbers in E.164 format. You must have a minimum of 100 and maximum 500 unique valid numbers after validation and deduplication.	[ "+9170XXXXX804", "+9198XXXXX210", "+1415XXXX671", "917XXXXX804"", . . . ]	Yes

Sample Success Response

The following is a sample success response:

{
    "code": "RCS702",
    "message": "Device Lookup successful",
    "data": {
        "total": 250,
        "uniqueTotal": 250,
        "duplicateCount": 0,
        "invalidCount": 1,
        "invalidNumbers": [
            "invalidnumber",
            "",
            "+53XX5"
        ],
        "devices": [
            {
                "deviceAddress": "+9170XXXXX801",
                "carrierId": "Jio",
                "carrierStatus": "ACTIVE",
                "rcsEnabled": true
            },
            {
                "deviceAddress": "+9170XXXXX802",
                "carrierId": "Airtel",
                "carrierStatus": "ACTIVE",
                "rcsEnabled": false
            },
            {
                "deviceAddress": "+9170XXXXX803",
                "carrierId": "Vi",
                "carrierStatus": "ACTIVE",
                "rcsEnabled": true
            }
        ]
    },
    "error": {}
}

Parameters and Descriptions for Success Response

The following are the parameters and descriptions for success response:

Data Object

Parameter	Data Type	Description	Example
`total`	Integer	Total count of valid unique device addresses sent to the provider.	250
`uniqueTotal`	Integer	Count of unique device addresses after deduplication.	250
`duplicateCount`	Integer	Number of duplicate addresses removed from the request.	0
`invalidCount`	Integer	Count of addresses that failed E.164 validation (empty strings, whitespace, non-E.164 format).	1
`invalidNumbers`	Array of String	List of the original invalid device addresses that were excluded from the lookup.	[ "invalidnumber", "", "+53XX5" ]
`devices`	Array of Object	Lookup results for each valid device. See device object structure below.

The following table describes the different parameters used for the devices JSON object:

Parameter	Data Type	Description	Example
`deviceAddress`	String	Phone number in E.164 format.	+9170XXXXX801
`carrierId`	String	Mobile carrier or operator name.	Jio
`carrierStatus`	String	Carrier status of the phone number.	ACTIVE
`rcsEnabled`	Boolean	Either RCS is enabled or not. It can be `true` if the device supports RCS messaging else `false`.	true

Sample Failure Response

The following are sample failure responses:

Empty Device Addresses Array

{
    "code": "RCS702",
    "message": "Required fields are missing",
    "data": [],
    "error": {
        "error_code": "MISSING_REQUIRED_PARAMS",
        "error_message": "deviceAddresses are required"
    }
}

All Numbers Invalid (non-E.164 or empty)

{
    "code": "RCS702",
    "message": "All provided device addresses are invalid or empty. Please provide valid E164 format numbers.",
    "data": [],
    "error": {
        "error_code": "INVALID_FIELD_FORMAT",
        "error_message": "All provided device addresses are invalid or empty. Please provide valid E164 format numbers."
    }
}

Only one Valid Number After Validation

{
    "code": "RCS702",
    "message": "Use single lookup endpoint for one deviceAddress",
    "data": [],
    "error": {
        "error_code": "MISSING_REQUIRED_PARAMS",
        "error_message": "provide multiple deviceAddresses or use /lookup/{device_address}"
    }
}

📘
Note:
If you want to use the single lookup endpoint, see Single Device Lookup.

Number lesser than 100 Unique Valid Numbers

{
    "code": "RCS702",
    "message": "At least 100 device addresses are required for bulk lookup.",
    "data": [],
    "error": {
        "error_code": "MISSING_REQUIRED_PARAMS",
        "error_message": "At least 100 device addresses are required for bulk lookup."
    }
}

Number more than 500 Unique Valid Numbers

{
    "code": "RCS702",
    "message": "Bulk lookup supports a maximum of 500 device addresses.",
    "data": [],
    "error": {
        "error_code": "Limit Exceeded",
        "error_message": "Bulk lookup supports a maximum of 500 device addresses."
    }
}

Invalid JSON Body

{
    "code": "RCS701",
    "message": "Invalid json format passed",
    "data": [],
    "error": {
        "error_code": "INVALID_JSON_PAYLOAD",
        "error_message": "Invalid json format passed"
    }
}

Wrong HTTP Method (except POST)

{
    "code": "RCS405",
    "message": "Method not allowed",
    "data": [],
    "error": {
        "error_code": "METHOD_NOT_ALLOWED",
        "error_message": "Method not allowed"
    }
}

RCS Not Enabled

{
    "code": "RCS601",
    "message": "RCS Channel is not enabled for this User",
    "data": [],
    "error": {
        "error_code": "RCS_CHANNEL_DISABLED",
        "error_message": "RCS Channel is not enabled for this User"
    }
}

Upstream Provider Error

{
    "code": "RCS704",
    "message": "Device lookup failed",
    "data": [],
    "error": {
        "error_code": "PROV_ERROR",
        "error_message": "{upstream error details}"
    }
}

Updated about 7 hours ago