Update Contacts: Sample Requests

Use the Update Contacts API to update existing identified or anonymous contacts asynchronously. You can update contact attributes, email and SMS subscription preferences, RCS and WhatsApp subscriptions, and audience assignments.

1. Update Contact Attributes

• When to use: Use this when you want to update one or more attributes of an existing contact.
• What changes: Provide the contact's identifier and add the attributes you want to update inside attributes.
• Best for: Updating customer information such as name, location, customer type, or other configured attributes.

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "attributes": {
          "FIRSTNAME": "John",
          "CITY": "Mumbai"
        }
      }
    ]
  }
}

Note: Attribute names must match the attributes configured for your client. The example attribute names are illustrative.

2. Update Multiple Contact Attributes

• When to use: Use this when you need to update several attributes for the same contact in one request.
• What changes: Add multiple attribute key-value pairs inside attributes.
• Best for: Updating a customer's profile after receiving new information from a CRM or another system.

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "attributes": {
          "FIRSTNAME": "John",
          "LASTNAME": "Doe",
          "CITY": "Mumbai",
          "CUSTOMER_TYPE": "Premium"
        }
      }
    ]
  }
}

Note: The current OpenAPI specification defines attribute values as strings.

5. Update WhatsApp or RCS Subscription

• When to use: Use this when you want to update a contact's subscription status for WhatsApp or RCS.
• What changes: Add a subscription_details entry with the communication channel and subscription status. Provide a reason when setting subscription to false.
• Best for: Managing subscription preferences for supported communication channels.

Opt out of WhatsApp

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "subscription_details": [
          {
            "subscription_channel": "whatsapp",
            "subscription": false,
            "subscription_reason": "Customer opted out of WhatsApp"
          }
        ]
      }
    ]
  }
}

Opt out of RCS

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "subscription_details": [
          {
            "subscription_channel": "rcs",
            "subscription": false,
            "subscription_reason": "Customer opted out of RCS"
          }
        ]
      }
    ]
  }
}

The supported subscription_channel values in the specification are rcs and whatsapp.

6. Update Contact Attributes and Subscription Together

• When to use: Use this when you want to update a contact's profile information and subscription preferences in the same request.
• What changes: Add both attributes and the required subscription fields to the contact object.
• Best for: Updating a customer's profile and communication preferences together.

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "attributes": {
          "FIRSTNAME": "John",
          "CITY": "Mumbai"
        },
        "email_subscription": false,
        "email_subscription_reason": "Customer unsubscribed through email",
        "sms_subscription": true,
        "subscription_details": [
          {
            "subscription_channel": "whatsapp",
            "subscription": false,
            "subscription_reason": "Customer opted out of WhatsApp"
          }
        ]
      }
    ]
  }
}

7. Update Multiple Contacts in One Request

• When to use: Use this when you want to update multiple existing contacts in a single API request.
• What changes: Add multiple contact objects to the contacts array.
• Best for: Bulk updates from a CRM, customer database, or other system.

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "attributes": {
          "FIRSTNAME": "John"
        }
      },
      {
        "identity": "[email protected]",
        "attributes": {
          "FIRSTNAME": "Mary"
        }
      }
    ]
  }
}

Note: The current OpenAPI specification does not define a maximum number of contacts that can be included in one request. Confirm the limit with the API team before documenting one.

8. Update a Contact Using contact_id

• When to use: Use this when you already know the Netcore contact_id.
• What changes: Provide contact_id instead of using the contact's identity.
• Best for: Updating a contact when you have the system-generated contact ID.

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "contact_id": 12345,
        "attributes": {
          "FIRSTNAME": "John"
        }
      }
    ]
  }
}

Important: When contact_id is provided, it takes the highest priority for identifying the contact.

9. Update an Anonymous Contact

• When to use: Use this when you want to update an existing anonymous contact.
• What changes: Set contact_type to anonymous and provide at least one supported identifier such as contact_id, guid, email, or mobile.
• Best for: Updating contacts that do not yet have a known primary identity.

{
  "data": {
    "contact_type": "anonymous",
    "contacts": [
      {
        "guid": "550e8400-e29b-41d4-a716-446655440000",
        "attributes": {
          "FIRSTNAME": "Visitor"
        }
      }
    ]
  }
}

The specification states that anonymous contacts must provide at least one supported identifier.

10. Update Contact and Assign to Audiences

• When to use: Use this when you want to update a contact and associate it with one or more audiences in the same request.
• What changes: Add audience_details to the contact and specify the audience using audience_id or audience_name.
• Best for: Updating a contact and assigning it to the appropriate audience at the same time.

Using audience ID

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "audience_details": [
          {
            "audience_id": [101, 202],
            "audience_type": "list"
          }
        ]
      }
    ]
  }
}

Using audience name

{
  "data": {
    "contact_type": "identified",
    "contacts": [
      {
        "identity": "[email protected]",
        "audience_details": [
          {
            "audience_name": ["Newsletter", "VIP_Group"],
            "audience_type": "list"
          }
        ]
      }
    ]
  }
}

Important: You can provide either audience_id or audience_name. If both are provided, audience_id takes precedence. For anonymous contacts, only list is supported; ccg is not allowed.