Single Device Lookup

GET Method

The Single Device Lookup API allows you to retrieve the RCS capability of a single mobile device using its phone number in E.164 format.

📘
Note:
The RCS channel must be enabled on your account. If it is not enabled, all lookup endpoints will return a 401 Unauthorized response.

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 Single Device Lookup

To get the single device lookup, use the https://rcs-api.<pod>.kaleyra.io/v1/<sid>/rcs/lookup/{device_address} endpoint with the following request method:

Request Format

The following is the request format for Single Device Lookup:

curl --location GET 'https://<api_domain>/v1/<sid>/rcs/lookup/device_address' \
--header 'Accept: application/json' \
--header 'api-key: <api-key>'

Sample Request Format

The following is the sample request format for Single Device Lookup:

curl --location GET 'https://rcs.api.na.kaleyra.io/v1/XXXXX6913850XXXX/rcs/lookup/%2B917057412804' \
--header 'Accept: application/json' \
--header 'api-key: XXXXX3b8497f58a94e84b671aca43XXXX '

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 the list of parameters to be used in the payload for single device lookup:

Parameter	Data Type	Description	Example	Mandatory?
`device_address`	string	Phone number in E.164 format. For example, +917057XXXXXX, the + prefix is optional in the URL, if provided, URL encode it as %2B.	%2B917057412804	Yes

Sample Success Response

The following is the sample success response:

{
    "code": "RCS702",
    "message": "Device Lookup successful",
    "data": {
        "deviceAddress": "+91705XXXXX74",
        "carrierId": "Jio",
        "carrierStatus": "ACTIVE",
        "rcsEnabled": true
    },
    "error": {}
}

Sample Failure Response

The following are the sample failure responses:

Missing Device Address - 400 Bad Request

{
    "code": "RCS702",
    "message": "device_address is required",
    "data": [],
    "error": {
        "error_code": "MISSING_REQUIRED_PARAMS",
        "error_message": "device_address is required"
    }
}

Invalid Phone Number Format - 400 Bad Request

{
    "code": "RCS704",
    "message": "Please enter a valid mobile number with country code.",
    "data": [],
    "error": {
        "error_code": "INVALID_FIELD_FORMAT",
        "error_message": "Please enter a valid mobile number with country code."
    }
}

Wrong HTTP Method - 405 Method Not Allowed

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

RCS Not Enabled - 401 Unauthorized

{
    "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 - 4xx / 502

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

Route Not Found - 404 Not Found

{
    "code": "RCS404",
    "message": "Route not found",
    "data": [],
    "error": {
        "error_code": "RCS404",
        "error_message": "Route not found"
    }
}

Updated about 6 hours ago