Skip to main content

Matching

The matching field specifies the search mode for the profile to update. The default value is email.

When you update data, you should follow a general matching approach.

Search modematchingRequired fieldsTypeExampleDescription
By email, from profile or subscription"email"emailstring"john@example.com"Email address
By email from profile"email_profile"emailstring"john@example.com"Email addressс
By email from subscriptions"email_sub"emailstring"john@example.com"Email address
By phone, from profile or subscription"phone"phonestring"+79000000000"Phone number
By phone from subscriptions"phone_sub"phonestring"+79000000000"Phone number
By profile ID (only on update!)"profile_id"profile_idstring"abcdefghijklmnqrstuvwxyz"Profile ID
By push subscription"push_sub"providerstring"android-firebase"Provider
subscription_idstring"1234"Push subscription ID
By custom field"custom"field_namestring"CRM_ID"The name of the custom profile field for search.
field_valueint/string"example123"The value of the custom search field.

Search by combination of field values with the "tags" type is available. Tags are passed in a line separated by commas: "tag_1, tag_2".
Search for a profile by subscription to the custom channel"custom_sub"field_namestring"CRM_ID"The name of the custom profile field for search.
field_valueint/string"example123"The value of the custom search field.

Search by combination of field values with the "tags" type is available. Tags are passed in a line separated by commas: "tag_1, tag_2".
By email or phone, from profile"email_phone"email / phonestring"john@example.com" / "+79000000000"Email address / Phone number
By email or phone, from subscriptions"email_phone_sub"email / phonestring"john@example.com" / "+79000000000"Email address / Phone number
info

Unclear matching

If the field you are passing in the request body is not unique, i.e. the value of this field is the same for several profiles, then the query will return you the error: "Unclear matching".

info

Duplicate unique data

The "Duplicate unique data" error occurs if you use a custom unique field for matching when importing a profile, but violate the uniqueness of the system field.

For example, a unique custom field client_id is used for matching. The database has a profile with fields:

  • email: test@example.com,
  • client_id: 100.

You import another profile with fields:

  • email: test@example.com,
  • client_id: 101.

The request will return a "Duplicate unique data" error, because the uniqueness of the email system field is violated.

In such cases, it is recommended to pass the email field in the subscription object:

{
    "token": "m1883gf9cacngh18c912016r7c7995a",
    "db_id": 1,
    "matching": "custom",
    "field_name": "client_id",
    "field_value": "100",
    "data": {
            "_fname": "John",
            "_lname": "Doe",
            "subscriptions": [
                {
                    "channel": "email",
                    "email": "test@example.com",            
                    "resource_id": 1                
                }
            ]
        }
}

Examples of importing/updating a subscription with certain matching​

email, email_profile, email_sub, email_phone, email_phone_sub​

{
     "token": "m1883gf9cacngh18c912016r7c7995a",
     "db_id": 1,
     "matching": "email",
     "email": "example@example.com",
     "data": {
        "subscriptions": [
            {
                "channel": "email",
                "email": "example@example.com",
                "resource_id": 1
            }
        ]
     }
}

phone, phone_sub, email_phone, email_phone_sub​

{
     "token": "m1883gf9cacngh18c912016r7c7995a",
     "db_id": 1,
     "matching": "phone",
     "phone": "+790000000000",
     "data": {
        "subscriptions": [
			{
                "channel": "sms",
                "phone": "+790000000000",       
                "resource_id": 1
            }
        ]
     }
}

profile_id​

{
     "token": "91f1dfa81c264a938b475677c60ce967",
     "db_id": 1,
     "matching": "profile_id",
     "profile_id": "012452gf62fcd71fjh8ec0",   
     "data": {        
        "subscriptions": [
            {
                "channel": "email",
                "email": "example@example.com",         
                "resource_id": 1
            }
        ]
    }
}

push_sub​

{
     "token": "91f1dfa81c264a938b475677c60ce967",
     "db_id": 1,
     "matching": "push_sub",
     "provider": "android-firebase",
     "subscription_id": "<token>",     
     "data": {        
        "subscriptions": [
            {
                "channel": "push",
                "subscription_id": "<token>",
                "provider": "android-firebase",             
                "resource_id": 1
            }
        ]
    }
}

custom, custom_sub​

{
     "token": "91f1dfa81c264a938b475677c60ce967",
     "db_id": 1,
 	 "matching": "custom",
     "field_name": "CRM_id",
     "field_value": "12345",  
     "data": {        
        "subscriptions": [
            {
                "channel": "email",
                "email": "example@example.com",           
                "resource_id": 1
            }
        ]
    }
}
tip

The subscription object contains data about the profile's subscriptions to the resource. Learn more.

Last updated on