Release NotesStatus Page

How to update, add, delete phone numbers arrays

By learning how to update and delete phone numbers, you also learn how to work all other array objects in the U21 API.

You can send arrays of phone numbers to the Unit21 API on the /entities endpoints in the communication_data field.

This topic demonstrates how to use the list_merge_strategy option to add, remove, and replace values for an array, using phone numbers as an example.

📘

Although this example uses POST requests to /create, the same strategies also apply to PUT requests to /update.

1. Check phone numbers for an entity

You can do this with a simple GET request to /entities/{unit21_id}

This user has two phone numbers.

{
  "general_data": {
    "entity_id": "exampleUser"
},
  ...
  "communication_data": {
    "email_addresses": [],
    "phone_numbers": [
      "+18005551111",
      "+19005550000"
    ]
  }
}

2. Add a phone number using the union strategy

Accomplish this with a POST to /entities using the entity's entity_id.

To add a phone number, you need to pass a union value to options.list_merge_strategy. The request body looks like this:

{
  "user_data": {},
  "communication_data": {
    "phone_numbers": [
      "+18005552222",
      "+19005550000"
    ]
  },
  "general_data": {
    "entity_id": "exampleUser",
    "entity_type": "user"
}.
  "options": {
    "upsert_on_conflict": true,
    "list_merge_strategy": "union"  #←union
}'

Note that, with the union merge strategy, the preceding request adds the new number to the entity's list of phone numbers. Check this with another GET:

{
  "unit21_id": "5926727",
  "general_data": {
    "entity_id": "exampleUser"
  },
...
"communication_data": {
    "email_addresses": [],
    "phone_numbers": [
      "+18005552222", ## ←inserted
      "+18005551111",
      "+19005550000"
    ]
  }
}

3. Remove a phone number with the difference strategy

To remove the number just added, change the list_merge_strategy to difference. Otherwise, the request looks the same:

{
  "user_data": {},
  "communication_data": {
    "phone_numbers": [
      "+18005552222"
    ]
  },
  "general_data": {
    "entity_id": "exampleUser",
    "entity_type": "user",
  },
  "options": {
    "upsert_on_conflict": true,
    "list_merge_strategy": "difference"  # ← difference
  }
}'

The new number has been removed:

{
  "unit21_id": "5926727",
  "general_data": {
    "entity_id": "exampleUser"
  },
...
  "communication_data": {
    "email_addresses": [],
    "phone_numbers": [
      "+18005551111",
     "+19005550000"
    ]
  }
}

4. Replace all numbers with replace

To replace all numbers, use the replace option. 

{
  "user_data": {},
  "communication_data": {
    "phone_numbers": [
      "+18005550000"
    ]
  },
  "general_data": {
    "entity_id": "exampleUser",
    "entity_type": "user"
  },
  "options": {
    "upsert_on_conflict": true,
    "list_merge_strategy": "replace"   # ← replace
  }
}'

The old array has been entirely replaced by the new array:

{
  "unit21_id": "5926727",
  "general_data": {
    "entity_id": "exampleUser"
  },
...
  "communication_data": {
    "email_addresses": [],
    "phone_numbers": [
     "+19005550000"
    ]
  }
}