Disassociate a Phone Number

The disassociate API enables you to disconnect a phone number from a user profile. There may be a case when users change their phone numbers and then the numbers are assigned to other users after the cooling-off period.

If the user is identified by the phone number then the data of the previous user may be merged with the new user assigned to the phone number. To avoid this scenario, run the disassociate API and disassociate the phone number assigned to the previous user.

For example, a user discontinues a phone number. The phone number is then assigned to a new user. You can pass the phone number in the Disassociate API. The phone number is disconnected from the previous user profile.

If you want to assign this phone number to a new user, you can use the Upload User Profiles API. A new user is created for the specified phone number. This process must be repeated every time the phone number changes hands.



You can disassociate a phone number only when it is used as an identity.


Passing the phone numbers requires a POST request with a JSON payload specifying the phone number. There is no limit on the number of requests to the API, but the batch size for each request must be up to 1000.



The batch size denotes the maximum number of records that can be fetched in a single call. The response may vary.

Base URL

Here is an example base URL from the account in the India region:


Refer Region for more details.

HTTP Method



Refer Headers for more details.

Body Parameters

Phone numbers are uploaded as a JSON payload. A payload is an object keyed with “d” whose value is an array describing the phone numbers.

For each phone number, type is required. The phone number is CleverTap’s user identifier, which we will use to find the user and dissociate the profile.

ParameterDescriptionTypeExample Value
typeSet to phone. Required.string“phone”
valueThe phone number of the userstring+9119244142334

Here is an example JSON payload for iOS/Android.

	"d": [
			"type": "phone",
			"value": "+919213231415"
			"type": "phone",
			"value": "+919213231416"

Example Request

Here is an example cURL request to the Disassociate API showing the headers needed to authenticate the request from the account in the India region:

curl --location --request POST 'https://in1.api.clevertap.com/1/disassociate/' \
--header 'Content-Type: application/json' \
--header 'X-CleverTap-Account-Id: WWW-WWW-WWRZ' \
--header 'X-CleverTap-Passcode: ICW-QKE-YSGL' \
--data-raw '{"d": [{"type": "phone", "value": "+919213231415"},{"type": "phone","value": "+919213231416"}]}'
require "uri"
require "net/http"
url = URI("https://in1.api.clevertap.com/1/disassociate/")
http = Net::HTTP.new(url.host, url.port);
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["X-CleverTap-Account-Id"] = "WWW-WWW-WWRZ"
request["X-CleverTap-Passcode"] = "ICW-QKE-YSGL"
request.body = "{\"d\": [{\"type\": \"phone\", \"value\": \"+919213231415\"},{\"type\": \"phone\",\"value\": \"+919213231416\"}]}"
response = http.request(request)
puts response.read_body
import requests
url = "https://in1.api.clevertap.com/1/disassociate/"
payload = "{\"d\": [{\"type\": \"phone\", \"value\": \"+919213231415\"},{\"type\": \"phone\",\"value\": \"+919213231416\"}]}"
headers = {
  'Content-Type': 'application/json',
  'X-CleverTap-Account-Id': 'WWW-WWW-WWRZ',
  'X-CleverTap-Passcode': 'ICW-QKE-YSGL'
response = requests.request("POST", url, headers=headers, data = payload)
require_once 'HTTP/Request2.php';
$request = new HTTP_Request2();
  'follow_redirects' => TRUE
  'Content-Type' => 'application/json',
  'X-CleverTap-Account-Id' => 'WWW-WWW-WWRZ',
  'X-CleverTap-Passcode' => 'ICW-QKE-YSGL'
$request->setBody('{"d": [{"type": "phone", "value": "+919213231415"},{"type": "phone","value": "+919213231416"}]}');
try {
  $response = $request->send();
  if ($response->getStatus() == 200) {
    echo $response->getBody();
  else {
    echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
catch(HTTP_Request2_Exception $e) {
  echo 'Error: ' . $e->getMessage();
var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://in1.api.clevertap.com/1/disassociate/',
  'headers': {
    'Content-Type': 'application/json',
    'X-CleverTap-Account-Id': 'WWW-WWW-WWRZ',
    'X-CleverTap-Passcode': 'ICW-QKE-YSGL'
  body: JSON.stringify({"d":[{"type":"phone","value":"+919213231415"},{"type":"phone","value":"+919213231416"}]})
request(options, function (error, response) { 
  if (error) throw new Error(error);
package main
import (
func main() {
  url := "https://in1.api.clevertap.com/1/disassociate/"
  method := "POST"
  payload := strings.NewReader("{\"d\": [{\"type\": \"phone\", \"value\": \"+919213231415\"},{\"type\": \"phone\",\"value\": \"+919213231416\"}]}")
  client := &http.Client {
  req, err := http.NewRequest(method, url, payload)
  if err != nil {
  req.Header.Add("Content-Type", "application/json")
  req.Header.Add("X-CleverTap-Account-Id", "WWW-WWW-WWRZ")
  req.Header.Add("X-CleverTap-Passcode", "ICW-QKE-YSGL")
  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

Example Response

    "status": "success",
    "processed": 2,
    "unprocessed": []


Requests with processing errors will be returned in the API call response as shown in the example below.

    "status":<success, partial, fail>, 
    "unprocessed": [{"status":"fail", "code":<error code>, "error":<error msg>, "record":<record>}]

To test if your data will be submitted without errors, you can add the parameter dryRun=1 to the URL. This will validate the input without submitting the data to CleverTap.



If a user is identified by the phone number, then the GUID can be used to identify the profile after disassociation. All the event and profile updates to the user are made using the GUID till a new phone number is passed to the user.

Handling subscriptions will automatically trigger the subscribe and disassociate APIs leading to Email-level subscription instead of User-level subscription.

To understand the common queries and concerns related to CleverTap APIs, refer to API FAQs.