Updating a contact's email address via API

Overview

Sometimes you may need to update a contact’s email address via the API, often used as the unique identifier.

You can do this if contacts are identified by a different unique field (e.g., an external ID). If not, you can update the email address using the Ortto Contact ID instead. Read on to learn how to do this using both methods.

Update using a different unique identifier

If you have a different field that holds a unique value for each contact, like an External ID, you can simply include that field in the body of the API call, along with the new email address. In the example below, we're updating two contacts' email addresses based on the str::ei field.

json
 
{
  "people": [
    {
      "fields": {
        "str::ei": "AB0001",
        "str::email": "john-new-email@example.com"
      }
    },
    {
      "fields": {
        "str::ei": "AB0002",
        "str::email": "alex-new-email@example.com"
      }
    }
  ],
  "merge_by": ["str::ei"],
  "merge_strategy": 2,
  "skip_non_existing": true
}

Important notes:

• merge_by: The merge_by must contain the unique identifier used to locate existing contacts. This is the field our system uses to find matches and update them with the new email address. For example, in the payload above: "merge_by": ["str::ei"]
• merge_strategy: The merge_strategy must be set to 2, which means overwrite. This ensures the existing email address is replaced with the new one provided in the payload.
• skip_non_existing: We also recommend setting skip_non_existing to true as this prevents new contacts from being created if the unique identifier provided doesn’t match any existing records in your Ortto account (e.g., the contact may have been deleted).

Update using the Ortto Contact ID

If you don’t currently have another identifier in place, such as an external ID, phone number, etc., you can still update the email address of an existing contact using the Ortto Contact ID. This ID is automatically generated by Ortto and is unique to each contact.

The Ortto Contact ID can be provided as str::person_id:

json
 
{
  "people": [
    {
      "fields": {
        "str::person_id": "00686bc7b47dd02115695600",
        "str::email": "john-new-email@example.com"
      }
    },
    {
      "fields": {
        "str::person_id": "0068404d7e38b27a9a276200",
        "str::email": "alex-new-email@example.com"
      }
    }
  ],
  "merge_by": ["str::person_id"],
  "merge_strategy": 2
}

Important notes:

• merge_by: The merge_by must contain the unique identifier used to locate existing contacts. This is the field our system uses to find matches and update them with the new email address. For example, in the payload above: "merge_by": ["str::person_id"]
• merge_strategy: The merge_strategy must be set to 2, which means overwrite. This ensures the existing email address is replaced with the new one provided in the payload.

Finding the Ortto Contact ID

There are two methods to find the Ortto Contact ID: the first is more suitable for one-off updates since it’s a manual approach, while the second is better for bulk updates.

Find the Contact ID in the URL navigation bar (manual method)

To find a Contact ID manually in Ortto, open the relevant contact profile and the Contact ID will be visible in the URL bar, as shown in the example below.

Retrieve Contact IDs for multiple contacts via API (bulk operations)

To retrieve the Contact ID for multiple contacts, you can call this endpoint. The response always will include the Contact ID for each contact returned.

In the example response payload below, each object inside the contacts array contains an id field, which corresponds to the unique Contact ID for that contact.

json
 
{
   "contacts":[
      {
         "id":"0061b02b24f9b6f85dcb1e00",
         "fields":{
            "str::ei":"c533532fe5d16c7d4fa4c7f0",
            "str::email":"alex@example.com",
            "str::first":"Alex"
         }
      },
      {
         "id":"006153c064088217368efb00",
         "fields":{
            "str::email":"chris.hiedler@example.com",
            "str::first":"Chris",
            "str::last":"Hiedler"
         }
      }
   ],
   "meta":{
      "total_contacts":2,
      "total_accounts":0,
      "total_matches":2,
      "total_subscribers":2
   },
   "offset":0,
   "next_offset":2,
   "cursor_id":"0062299d655c7cf67184e1e0",
   "has_more":false
}