Use this API to add or remove identifiers associated with a customer's profile. This includes standard identifiers such as mobile number, email, and external ID, as well as card-specific operations such as linking or delinking a loyalty card.

Supported identifier types

Supported operations

What you cannot do with this API

Profile attributes

Only identifiers can be updated using this API. Other profile attributes cannot be modified.

Identifier uniqueness rules

Identifiers must be unique within the scope of their source type:

• For single-account sources, identifiers must be unique within the source.
• For multi-account sources, identifiers must be unique within the account.

If an identifier you add already exists under a different source or account, the two accounts are automatically merged. The new account becomes the victim account and the existing account becomes the survivor account.

Identifier reuse from campaign and victim users

By default, if an identifier (mobile, email, or external ID) is already held by a campaign user (a non-registered user created by a campaign) or a victim user (the merged-away account in a previous merge), the API blocks the update.

You can change this behavior by enabling the org-level configuration CONF_ALLOW_CAMPAIGN_AND_VICTIM_USER_IDENTIFIER_REUSE. When this configuration is enabled:

• The conflicting identifier is automatically cleared from the campaign or victim user.
• The requesting customer's profile takes the identifier.
• Applies to mobile, email, and externalId identifier types only.
• Supported only for requests with source=INSTORE.

If the identifier cannot be freed — for example, the conflicting user does not exist in the same INSTORE scope — the API returns an error.

Updating multiple identifiers in a single request

When updating multiple identifiers (for example, both mobile and cuid) in a single request with source=INSTORE, the following limitations apply.

Simultaneous updates may not work

The API does not reliably support updating certain combinations of identifiers at the same time. If you include both mobile and cuid in the same request, the update may process only one of them or fail entirely.

Some identifiers may be silently skipped

In some cases, the API may skip certain identifiers such as cuid without returning an explicit error. This can cause the update to appear successful while leaving one or more identifiers unchanged, and may lead to data inconsistencies across systems.

Behavior may differ across platforms

If your integration runs on multiple platforms (such as Android and iOS), differences in how each platform structures the request payload can produce inconsistent results. An update that works on one platform may not behave the same way on another.

Partial failures can create incomplete profiles

If the CONF_RESTRICT_ORPHAN_V2_PROFILE configuration parameter is enabled, failed or partial updates may create orphan profiles (profiles without a primary identifier). This can affect downstream processes and data integrity.

Mobile number update and identifier sync

If CONF_IDENTIFIERS_SYNC_ENABLED is enabled, updating a mobile number triggers a sync to the external system. If the new mobile number already exists in another profile, the update fails with error code 11000 (duplicate identifier value). When this occurs, the sync does not take place and the mobile number is not updated. This behavior prevents duplicate identifiers across profiles.

Recommendations

To avoid the issues above:

• Update only one identifier at a time per request, especially for critical identifiers like mobile and cuid.
• Review your integration to ensure payload consistency across platforms, and handle error responses appropriately.
• Understand how CONF_RESTRICT_ORPHAN_V2_PROFILE and CONF_IDENTIFIERS_SYNC_ENABLED affect profile creation, identifier updates, and synchronization before configuring your environment.

Prerequisites

• A valid customer ID for the profile you want to update.
• Valid identifier value(s) to add or remove.
• For card issuance:
  • External or manually generated cards — Add the card first using the /v2/card API before issuing it to a customer.
  • Auto-generated cards — Generate the card first using the card/generate API before issuing it to a customer.

Path parameters

Query parameters

Example request

curl --location 'https://eu.api.capillarytech.com/v2/customers/564767826/changeIdentifier?source=INSTORE' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Basic cnV0dWphXMGI0NzZjNg==' \
--header 'Cookie: _cfuvid=pQPy_F.YRXJFSzvmPJmB4FH7K2rncxP7s12ArteCH1E-1744806036086-0.0.1.1-604800000' \
--data '{
    "add": [
        {
            "type": "cardnumber",
            "value": "Test09000000000004end",
            "seriesCode": "Test",
            "statusLabel": "ACTIVE"
        }
    ]
}'

curl --location 'https://eu.api.capillarytech.com/v2/customers/564767826/changeIdentifier?source=INSTORE&format=json' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Basic cnV0dWphX20NzZjNg==' \
--header 'Cookie: _cfuvid=pQPy_F.YRXJFSzvmPJmB4FH7K2rncxP7s12ArteCH1E-1744806036086-0.0.1.1-604800000' \
--data '{
    
    "remove": [
        {
            "type": "cardnumber",
            "value": "Test09000000000004end",
            "seriesCode": "Test",
            "statusLabel": "NOT_ISSUED"
        }
    ]
}'

curl --location 'https://eu.api.capillarytech.com/v2/customers/564845545/changeIdentifier?source=INSTORE' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'Authorization: Basic =' \
--header 'Cookie: _cfuvid=a0NmZQvi.30LKK7NvCQJgMpK8Ig15sul9um2ZFRucDk-1757422794990-0.0.1.1-604800000' \
--data '{
    "add": [
        {
            "type": "cardnumber",
            "value": "mtest00000000057003",
            "seriesCode": "Test",
            "statusLabel": "ACTIVE"
        }
    ]
}'

Body parameters

📘

Note

When using externalId, the value must match the prefix and length configured in Org Settings > Registration. For example, if the prefix is LM* and the length is 10 digits, only values starting with LM and exactly 10 digits long are accepted.

For more info on adding cards, refer to Adding cards.

Example response

{
    "createdId": 564854782,
    "warnings": []
}

Error and warning codes