Skip to main content
POST
/
instances
/
{instanceId}
/
token
/
{token}
/
mobile
/
registration-available
Check availability
curl --request POST \
  --url https://api.z-api.io/instances/{instanceId}/token/{token}/mobile/registration-available \
  --header 'Client-Token: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "ddi": "<string>",
  "phone": "<string>"
}
'
{
  "available": true,
  "blocked": true,
  "appealToken": "<string>",
  "smsWaitSeconds": 123,
  "voiceWaitSeconds": 123,
  "waOldWaitSeconds": 123,
  "waOldEligible": true,
  "reason": "<string>"
}

​
Overview

Method used to check the registration availability of a number. This endpoint verifies if the number is available for registration and performs the WhatsApp onboarding setup. It must be called before requesting the confirmation code.
ATTENTIONDo not use this method if you do not have access to the phone where the number is currently linked. This method is useful for speeding up the code confirmation process without having to wait for an SMS or voice call, but it requires you to have the device in hand with the WhatsApp app open.
Banned number scenarioThere are some scenarios where the number is prevented from being connected even on the official WhatsApp app. In this case, the number availability check API is not able to identify this, and the number is only returned as blocked when requesting the code. Unfortunately, there is nothing we can do about this at the moment, because unlike the standard ban, no token (appealToken) is provided to submit an unban request.

​
Attributes

​
instanceId
string
required
Your instance ID. Available in the Z-API panel under Instances.
​
token
string
required
Your Z-API instance token.

​
Body

​
ddi
string
required
Country code
​
phone
string
required
Phone number with area code, no formatting

​
Request Body

{
  "ddi": "55",
  "phone": "4499999999"
}

​
Response

​
200

​
available
boolean
Returns true if the number is available for registration
​
blocked
boolean
Whether the number is banned or blocked for some other reason
​
appealToken
string
Token for unban request (when blocked)
​
smsWaitSeconds
number
Time to wait before requesting SMS
​
voiceWaitSeconds
number
Time to wait before requesting voice call
​
waOldWaitSeconds
number
Time to wait before requesting in-app pop-up
​
waOldEligible
boolean
Whether the pop-up code request method is available
​
reason
string
In case of error, this attribute states the reason why the error occurred
Available number: 
{
  "available": true,
  "smsWaitSeconds": 0,
  "voiceWaitSeconds": 0,
  "waOldWaitSeconds": 0,
  "waOldEligible": true
}
Blocked number: 
{
  "available": false,
  "blocked": true,
  "appealToken": "Ae0B_6FfVfyB8on0v76ALf1RkWXFFsfvliOdh02JyXTFcbnlTAwO5_h5Ju4L5zfa..."
}

​
400

Invalid request. Check if the data you are sending matches the documentation.

​
405

Make sure you are correctly sending the method specification, that is, verify that you sent POST or GET as specified at the beginning of this topic.

​
415

If you receive a 415 error, make sure to add the “Content-Type” header to your request, which in most cases is “application/json”.