SMSWhatsAppVoiceVideoAPIIntegrationRelease NotesFAQs
Guides
Contact UsKaleyra.io Sign InSupport

Change Blocklist Status for Number

POST Method

Suggest Edits

The Change Blocklist Status for Number API allows you to change the status of one or multiple phone numbers, determining whether they should be included in the blocklist or not.

📘

Note:

  • Status "0" is used to remove a blocklist status from a number and "1" is used to add a blocklist status to a number. 
  • If a number is passed with Status “1” that was not previously in the blocklist status, then that number is added to the blocklist.
  • You can update the blocklist status for up to 100 contacts per request.

Base URL

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

To change the status of numbers in the blocklist (blocked or unblocked), 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. Change the status of numbers in the blocklist API request.

API request to change the status of numbers in the blocklist (blocked or unblocked)

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

Request Format

The following is the request format to change the status of the numbers in the blocklist (blocked or unblocked).

curl -X POST 'https://api.kaleyra.io/v1/<SID>/contacts/blocklisted' \
--header 'api-key:  <api_key>' \
--header 'content-type: <content_type> ' \
--data '{"channel":<channel_name>,"contacts":[{"blocklist_status":<blocklist_status>,"numbers":["<mobile_numbers>"]}]}'

Sample Request Format


curl -X POST ' https://api.kaleyra.io/v1/HXXXXXXX071US/contacts/blocklisted' \
  -header 'api-key: A522b7e64XXXXXXXXf7d99b03545fa68e' \
  -header 'content-type: application/json' \
  -data '{"channel":"sms","contacts":[{"blocklist_status":1,"numbers":["+9188XXXX6328","+91620XXXX124"]},{"blocklist_status":0,"numbers":["+9170XXXX9399","+9197XXXX5019"]}]}'

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
content_typeJSONSpecifies the type of data being sent in the request.application/jsonYes
channelStringChannel for which the contacts are blocklisted. The acceptable value is "sms", "whatsapp", and "voice".smsYes

The following table describes the different attributes used for the contacts array.

ParameterData TypeDescriptionExampleMandatory
blocklist_statusIntegerIndicates the blocklisting status (1 for blocking and 0 for unblocking).1Yes
numbersArray of stringSpecifies the phone numbers being blocklisted.["+9188XXXX6328","+91620XXXX124"]Yes

Sample Success Response to change the status of the numbers in the blocklist

The following success message appears with the status 200 succeeded.

{ 

    "code": "RBC024", 

    "message": "Request processed", 

    "data": [], 

    "error": {} 

}

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.

{ 

    "status": 400, 

    "code": "E413", 

    "message": "Invalid/incorrect inputs", 

    "error": { 

        "type": "Invalid/incorrect inputs" 

    } 

}

Updated 6 months ago