SMSWhatsAppVoiceVideoAPIIntegrationRelease NotesFAQs
Guides
Contact UsKaleyra.io Sign InSupport

Get Blocklist

GET Method

Suggest Edits

The Get Blocklist API allows you to fetch the blocklisted status of numbers up to 100.

Base URL

https://<api_domain>/v2/<SID>

To fetch the blocklisted status of numbers, perform the following steps:

  1. Before you get started, Create an API Key. To view the API Key and the SID, see View API Key and SID.
  2. Fetch the blocklisted status of numbers in the API request.

API request to fetch the blocklisted status of numbers

To fetch the blocklisted status of numbers, use the /contacts/blocklisted endpoint with the following request method:

Request Format

The following is the request format to fetch the blocklisted status of numbers.

curl -X GET 'https://api.kaleyra.io/v1/<SID>/contacts/blocklisted?limit=<limit>&offset=<offset>&channel=<channel_name>&mobile=<mobile_numbers>'\
--header 'api-key:  <api_key>' \

Sample Request Format

The following is the sample request format to fetch the blocklisted status of numbers.

curl -X GET 'https://api.kaleyra.io/v1/HXXXXXXX071US/contacts/blocklisted?limit=3&offset=0&channel=whatsapp&mobile=+91802XXXXX52%2C+91803XXXXX53'\
--header 'api-key: A522b7e64XXXXXXXXf7d99b03545fa68e'

📘

Note:

You can send the request for a maximum set of 100 phone numbers.

Parameter and Data Types

The following table shows the list of parameters and data types supported:

ParameterData TypeDescriptionExamplesMandatory
sidStringAccount SID (Security Identifier).HXXXXXXX071USYes
api-keyStringYour API Key generated by kaleyra.io.A522b7e64XXXXXXXXf7d99b03545fa68eYes
limitIntegerSpecifies the number of elements returned in the response. 
Note: It is not possible to retrieve more than 100 contacts per response. By default, the limit is set to 100.		3No
offsetIntegerPosition in the dataset of a particular record. By specifying 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 100 contacts found).0No
channel_nameStringChannel for which the contacts are blocklisted. The acceptable value is "sms", "whatsapp", and "voice".smsOptional
mobile_numbersStringA valid phone number. Ensure that the country code is prefixed to the number. (E164 format).
Note:
a. You can add multiple recipients, separate each number using the comma (,) delimiter.
b. In case mobile numbers is not included in the API request, the complete blocklist numbers will be provided with a limit of 100.		+91802XXXXX52, +91803XXXXX53Optional

Sample Success Response

The following success message appears with the status 202 Accepted:

202 Accepted 
{
"code":"WA202"
"message":"Request Accepted",
"data":{
  "message_id":"AXXXXXXXXXXXXXXXXXXX"
}
"error":{}
}

The following success message appears with the status 200 succeeded.

{ 

    "code": "CNT196", 

    "message": "Successfully fetched blocklisted number(s)", 

    "data": [ 

        { 

            "mobile": "+91802XXXXX52", 

            "channel_type": "3" 

        } 

    ], 

    "error": {} 

}

📘

Note:

The response will only contain the blocklisted numbers and their respective channels. For example, if multiple numbers are provided, then only the blocklisted numbers will be shown and if none of the numbers are blocklisted, then empty array will be returned.

Sample Failure Response

The following are the failure responses:

401 Unauthorized
{
    "code": "RBC001",
    "message": "Incorrect SID or API key.",
    "data": [],
    "error": {
        "error": "Incorrect SID or API key."
    }
}

401 Unauthorized phone number
{
    "code": "WA401",
    "message": "Phone number is not present or does not belong to the account.",
    "data": {},
    "error": {
        "phone_number": "Phone number is not present or does not belong to the account."
    }
}

400 Incorrect payload
{
    "code": "WA400",
    "message": "Refer to correct payload format",
    "data": {},
    "error": {
        "payload": "Incorrect payload format"
    }
}

500 Internal Server Error
{
    "code": "WA500",
    "message": "Please try again later",
    "data": {},
    "error": {
        "error": "Internal server error"
    }
}

400 Low balance
{
    "code": "E110",
    "message": "Please check your balance, You have a low balance!",
    "data": {},
    "error": {
        "balance": "Please check your balance, You have a low balance!"
    }
}

401 Unauthorised Account type
{
    "code": "WA-401",
    "message": "API is not available for given customer.Please contact support for more info",
    "data": {},
    "error": {
        "account": "API is not available for given customer.Please contact support for more info"
    }
}

401 Unauthorized phone number version
{
    "code": "WA-401",
    "message": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint.",
    "data": {},
    "error": {
        "phone_number": "The phone number you're using is associated with different Version of our WA API. Please use the appropriate endpoint."
    }
}

The following is a sample failure response.

{ 

    "code": "CNT195", 

    "message": "Unable to fetch the blocklisted number", 

    "data": [], 

    "error": { 

        "description": "Unable to fetch the blocklisted number" 

    } 

}

Updated 6 months ago