Profiles API

This API can be used to create, update, and access profiles in the Wyng platform Consumer service.

Base api url: /api/v1/consumer

/tdm

Permissions

Direct access to this endpoint is restricted. The "Profiles" tab on the Wyng platform is the recommended way to add and configure a data model.

POST

Create data model.

Payload

Name	Type	Required	Default	Description
fields	List	Yes		List of data model fields
strong_id	String	Yes		ID which will be used for merging profiles
ids_priority	List	No	["email", "phone", "uid"]	List of strings. Id fields in high to low order of priority. Used for lookups when multiple profiles with different ids are found. The profile with the highest priority Id field will be returned

{
  "fields": [
    {
      "name": "email",
      "id": "email",
      "type": "text",
      "status": "active"
    },
    {
      "name": "Hair color",
      "id": "hair_color",
      "type": "text",
      "status": "active"
    },
    {
      "name": "Skin Concerns",
      "id": "skin_concerns",
      "type": "text",
      "status": "active"
  }, {
      "name": "Date of Birth",
      "id": "dob",
      "type": "date"
  }],
  "strong_id": "email",
  "ids_priority": ["email", "phone", "uid"]  // Optional. See more info in ids_priority section.
}

Field Object Definition

id required	string Field id must be unique within a TDM instance.
name required	string User friendly field name.
type	string Field type. textdateboolnumsettext
status required	string Enum: "active" "inactive" Field state, allows a field to be disabled/archived.
is_key	boolean Default: false Use to look up profiles.
is_internal	boolean Default: false Indicates a particular attribute should not be displayed directly to the consumer; for example, should not be included when portal template experience is generated
relevance_window	integer Default: null Optional window of time in days since last update that the value can still be considered relevant for personalization.
retention_window	integer Default: null Optional window of time in days since last update that the value can be used for any purpose. After retention_window expires, the attribute will be deleted

Example

textdateboolnumsettext

[

• {

  • "id": "email",
  • "name": "Email",
  • "type": "text",
  • "status": "active"

  },
• {

  • "id": "skin_concerns",
  • "name": "Skin Concerns",
  • "type": "text",
  • "is_internal": true

  }

]

Additional details on the Type field

TDM fields can have different data types. The data type will be defined in the TDM. Data types that are available are text, date, bool, num, and set

Text

This is the default data type that will be used for most fields. This fields type will contain string values that can be any value.

Date

The following formats are accepted:

• A datetimestamp in ISO 8601 format: 2011-12-03T10:15:30Z, 2011-12-03T10:15:30.001…
• A date without a time component in ISO 8601 format: 2011-12-03. In that case, 00:00:00Z will be assumed as the time component.

Boolean

A boolean field containing True or False

Numeric

Numeric fields. Values can be either integers or floats.

Set

A list of values. Values can be added to, or removed from the Profile without prior knowledge of the current values that are in the Set. The possible values are defined in the values attribute of the TDM, if allow_other_values is set to false, the Set will only accept values that are defined in the values attribute of the TDM.

strong_id

The strong_id must be an id field. Currently, this must be one of email, phone, or uid.

*Note: That must be one of the id fields in "fields" configuration.*

Response

Status code: 201

{
  "fields": [
    {
      "name": "email",
      "id": "email",
      "type": "text",
      "status": "active"
    },
    {
      "name": "Hair color",
      "id": "hair_color",
      "type": "text",
      "status": "active"
    }
  ],
  "strong_id": "email",
  "ids_priority": ["email", "phone", "uid"]
}

These two profiles will be merged into 1 profile if the strong_id is set to email. If the strong_id is phone, only one of the two profiles will be used, the other will be ignored

*Note: The value must be one of the id of the field in "fields".*

ids_priority

Order of the fields used by the /lookup endpoint. If multiple profiles exist for the multiple ids, the profile with the id that has the highest priority will be used

By default ids_priority contains email, phone, uid even if these fields do not exist in the data model configuration. If request payload is

{
  "fields": [
    {
      "name": "GA Id",
      "id": "ga_id",
      // …
    },
    {
      "name": "hair_color",
      "id": "hair_color",
      // …
    }
  ],
  "strong_id": "ga_id",
  "ids_priority": ["email", "phone", "uid"]
}

this ids_priority will be created, with the strong_id automatically inserted at the front:

{
  "fields": [
    {
      "name": "GA Id",
      "id": "ga_id",
      // …
    },
    // …
  ],
  "strong_id": "ga_id",
  "ids_priority": ["ga_id","email", "phone", "uid"]
}

the top priority will be "ga_id" because it is being used as strong_id.

*Note: API provides the possibility to define ids priorities manually, but the field name which id defined in the strong id will be always first.*

Success response

Status code: 200

{
  "fields": [
    {
      "name": "email",
      "id": "email",
      "type": "text",
      "status": "active"
    },
    {
      "name": "Hair color",
      "id": "hair_color",
      "type": "text",
      "status": "active"
    }
  ],
  "strong_id": "email",
  "segments": [],
  "ids_priority": ["email", "phone", "uid"]
}

/tdm/<tdm_id>

Permissions

This endpoint requires a private access token. This endpoint should not generally be used by developers. The "Profiles" tab on the Wyng platform is the recommended way to add or configure a data model.

PUT

Update a data model instance. Uses the same payload as create.

GET

Get data model configuration

Success response

Status code: 200

{
  "fields": [
    {
      "name": "email",
      "id": "email",
      "type": "text",
      "status": "active"
    },
    {
      "name": "Hair color",
      "id": "hair_color",
      "type": "text",
      "status": "active"
    }
  ],
  "strong_id": "email",
  "ids_priority": ["email", "phone", "uid"]
}

/profiles/upsert

PUT

Create or update a profile in a data model instance.

This endpoint accepts a set of fields, and either creates or updates the corresponding profile. Profiles may be matched by any of three key fields: email, phone, uid. If any key fields provided match a profile, we will update that profile. ids_priority setting on TDM will be used to decide which profile to update, if multiple profiles match. If no matching profile exists, we will create a new one. If the action would result in multiple profiles having the same strong_id, those profiles will be merged.

Permissons

This endpoint may be accessed with a public access token.

Token may be passed:

1. Url parameter access_token=token
2. HTTP header X-Access-Token

Payload

Name	Type	Required	Description
fields	Fields object	No	TDM fields data
consent	string	No	Text value that encodes some consent information about the attribute.
source	string	No	Text value that encodes where the attribute came from. The Profiles Connector will put an experience_id in here.
timestamp	String	No	Date and time that should be set as the last update time for the fields that are being changed. Default value is Now. Sample date: 2020-10-19 16:25 (corresponds to October 19, 2020 4:25 pm)

Fields object

All TDM fields values should be passed through the 'fields' object with attribute values of the TDM Profile where the key is a TDM field id, e.g.

{
    "fields": {
        "uids": {"value": ["bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"]},
        "email": {"value": "mail3@example.com"},
        "phone": {"value": "+18882223344"},
        "field_1": {"value": "value"},
        "field_2": {"value": "value 2"},
        "set_field": {"value": [ {"name": "Value to Add", "value": true}, {"name": "Value to Remove", "value": false} ]}
    },
    // // …
}

UIDS

The uids field should always be an array type.

Set field types

Set field values are always an array of objects. The object expects two attributes, name, and value.

Name	Type	Required	Description
name	string	Yes	Value that is added or removed from the set field
value	boolean	Yes	true if adding the name to the set, false if removing

• Note: instead of true or false boolean values, 1 or 0 numeric values are also accepted, as well as '1' and '0' or 'true' and 'false' string values. Any other value will result in an error and the entire record will be rejected.

Each field contains additional metadata attributes, e.g.

{"fields":  {
    "email": {
            "value": "mail3@example.com",
            "updated": "2021-09-22T00:00:00.000000",
            "created": "2020-01-01T00:00:00.000000",
            "consent": "Data source",  // Appears if 'consent' was provided in the upsert payload
            "source": "Some consent value"  // Appears if 'source' was provided in the upsert payload
         }
}}

Atribute	Description
updated	Date time when the field value was updated. Can be customized with the global timestamp attribute.
created	Date time when the field value was added.
source	Data source can be customized with the global source attribute. (See Consent & source section)
consent	Data consent can be customized with the global consent attribute. (See Consent & source section)

Example request

{
    "fields": {
        "uids": {"value": ["bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"]},
        "email": {"value": "mail3@example.com"},
        "phone": {"value": "+18882223344"},
        "field_1": {"value": "value"},
        "field_2": {"value": "value 2"},
        "set_field": {"value": [ { "name": "Add value", "value": true }, { "name": "Remove value", "value": false } ]}
    },
    "timestamp": "2020-09-22 07:23"
}

Expected Response

{
    "fields": {
        "uids": {
            "value": ["bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"],
            "updated": "2019-09-22T00:00:00.000000",
            "created": "2019-09-22T00:00:00.000000"
        },
        "email": {
            "value": "mail3@example.com",
            "updated": "2021-09-22T00:00:00.000000",
            "created": "<Creation date or current>"
         },
        "phone": {
            "value": "+18882223344",
            "updated": "2021-09-22T00:00:00.000000",
            "created": "<Creation date or current>"
        },
        "field_1": {
            "value": "value",
            "updated": "2021-09-22T00:00:00.000000",
            "created": "<Creation date or current>"
        },
        "field_2": {
            "value": "value 2",
            "updated": "2021-09-22T00:00:00.000000",
            "created": "<Creation date or current>"
        },
        "set_field": {
            "value": ["Untouched Already Existing Value", "Add value"],
            "updated": "2021-09-22T00:00:00.000000",
            "created": "<Creation date or current>"
        }
    }
}

Consent & source

For example, you have an existing Profile

{
    "fields": {
        "uids": {
            "value": ["bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"],
            "updated": "2019-09-22T00:00:00.000000",
            "created": "2019-09-22T00:00:00.000000"
        },
        "field_1": {
            "value": "value",
            "updated": "2021-09-22T00:00:00.000000",
            "created": "2021-09-22T00:00:00.000000"
        }
    }
}

And you want to populate data from another source different from Wyng and provide some consent info for attributes

{
    "fields": {
        "uids": {
            "value": ["bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"],
            "updated": "2019-09-22T00:00:00.000000",
            "created": "2019-09-22T00:00:00.000000"
        },
        "other_field": { "value": "value" }
    },
    "source": "Your source",
    "consent": "Consent info"
}

The result will be

{
    "tdm_id": "...",
    "fields": {
        "uids": {
            "value": ["bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"],
            "updated": "2019-09-22T00:00:00.000000",
            "created": "2019-09-22T00:00:00.000000"
        },
        "field_1": {
            "value": "value",
            "updated": "2019-09-22T00:00:00.000000",
            "created": "2019-09-22T00:00:00.000000"
        },
        "other_field": {
            "value": "value",
            "updated": "Current date",
            "created": "Current date",
            "consent": "Consent info",
            "source": "Your source"
        }
    }
}

/profiles/lookup

GET

Search the data model instance for a profile that matches on one or more of the given IDs. Returns a canonical profile ID that can be used to retrieve a profile.

Permissons

This endpoint requires a private token. The token can be submitted using one of two ways:

1. URL parameter access_token=token
2. HTTP header X-Access-Token

Payload

IDs to match on should be passed as URL parameters.

/profiles/lookup?uid=<example_uid>&email=<example_email>

Expected Response

{
    "id": "5f68bf46030feaa8f4b5bb7b"
}

Error response

When profile doesn't exist

Status code: 200

{}

/profiles/<profile_id>

GET

Returns the full JSON for a profile object matching canonical profile ID, including all fields, values, and field update timestamps.

info

Calling this endpoint does not recalculate segments or modify the profile in any way, and does not update the Last Activity Date (updated_at).

Query parameters

By default, API returns full profile data that includes relevant and not relevant attributes. You may modify that behavior using a query parameter to get only relevant or not relevant attributes.

relevant=1 - Same as behavior with no parameter, but response only includes attributes updated within relevance_window for each attribute

relevant=0 - Same as behavior with no parameter, but response only includes attributes NOT relevant any more and which may need to be refreshed

Permissons

This endpoint requires either a TDM private token or a TDM public token. The public can be used in combination with a JWT The Access Token can be submitted using one of two ways:

1. URL parameter access_token=token
2. HTTP header X-Access-Token

The JWT can be submitted as a URL parameter jwt=jwt_value

When only a public token is provided, Private data will not be returned by the endpoint.

Expected Response

Private Profile Response

{
    "created_at": "2020-01-22T16:11:00.347000",
    "parent_profiles": [],
    "updated_at": "2022-01-19T20:02:54.145000",
    "tdm_id": "5f633bc86feb832df525d51f",
    "segments": [ "8a275098d27134f9c1e7395b" ],
    "fields": {
        "uids": {"value":  [
            "dafaaafdadd1bfaaaabfefadaaaadc31",
            "dafaaafdadd1bfaaaabfefadaaabdc31"
        ]},
        "email": {
            "value": "hello@aWoRlD.com",
            "updated": "2021-06-17T10:40:04Z",
            "created": "2021-03-22T10:11:00.347000"
        },
        "hello": {
            "value": "hi",
            "updated": "2021-06-17T10:40:04Z",
            "created": "2021-03-22T10:11:00.347000"
        },
        "test_key": {
            "value": 1234,
            "updated": "2021-06-17T10:40:04Z",
            "created": "2020-01-22T16:11:00.347000"

        },
        "test": {
            "value": 2,
            "updated": "2022-01-19T20:02:54.145000",
            "created": "2021-06-17T10:40:04Z"
        }
    },
    "field_list": [ "uids", "email", "hello", "test_key", "test" ]
}

Public Profile Response

{
    "tdm_id": "5f633bc86feb832df525d51f",
    "segments": [ "8a275098d27134f9c1e7395b" ],
    "field_list": [ "uids", "email", "hello", "test_key", "test" ]
}

Error response

When profile doesn't exist

Status code: 200

{}

/profiles/<profile_id>/attributes/<field_id>

GET

Returns single relevant field value and metadata for a profile object matching canonical profile ID.

Permissons

This endpoint requires a TDM private token Token can be submitted using one of two ways:

1. URL parameter access_token=token
2. HTTP header X-Access-Token

Expected Response

{
    "created": "2021-07-09T16:24:53.797000",
    "value": "Attribute value",
    "updated": "2021-07-09T16:24:53.797000",
    "relevance_window": 10,
    "retention_window": 30
}

Error response

When an attribute for profile doesn't exist or attribute is not relevant will be returned:

Status code: 404

/profiles/<profile_id>/compare?<field_id>=<field_value>

GET

Check to see if the relevant field value for a profile matches a certain value. If the field is of type SET the check is done to see if the given value is in the SET.

Only attributes that are not Key fields can be checked using this endpoint

Permissons

This endpoint requires a TDM public token. The token can be submitted using one of two ways:

1. URL parameter access_token=token
2. HTTP header X-Access-Token

Return value

Name	Type	Required	Description
has_value	boolean	Yes	True if attribute has a value for the given Profile. False if not
result	boolean	Yes	True if attribute value matches for the given Profile. False if it does not match. For SET attributes value will be True if one of the values in the SET of the Profile matches the given value.

Expected Response

{
    "has_value": true,
    "result": true
}

Status code: 200

Error response

When the <profile_id> does not exist

Status code: 404

When the <field_id> does not exist

Status code: 404

When the <field_id> is a Key field

Status code: 403

/profiles/<profile_id>/segments

GET

Returns the list of segments for canonical Profile ID.

Permissons

This endpoint requires a TDM private or TDM public tokens Token can be submitted using one of two ways:

1. URL parameter access_token=token
2. HTTP header X-Access-Token

Expected Response

[
  "60c857159543dbd15581e00f",
  "000000000000000000000000"
]

Error response

When profile doesn't exist

Status code: 404

caution

Side effects

Calling this endpoint will recalculate this profile's segments and update the Last Activity date (updated_at).

/profiles/<profile_id>/identify

POST

Get a JWT that can be used as a temporary credential to access the full profile for a specific user. The JWT can be passed in as an optional URL parameter to /profiles/<profile_id>, to retrieve the full profile. The JWT can be inspected to determine how long it is valid, but will generally be valid for 30 minutes.

Permissions

This endpoint requires a TDM private read token Token can be submitted using one of two ways:

1. URL parameter access_token=token
2. HTTP header X-Access-Token

Payload

Name	Type	Required	Default	Description
expire_in	Integer	No	1800	Number of seconds till JWT will expire

{
    "expire_in": 600
}

Expected Response

{
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ0ZG1faWQiOiI2MGY5YzFlNzM5NWVhMDAyMDJlYTM2ZjIiLCJwcm9maWxlX2lkIjoiNjFlODZlNmU5ZjU4YzBjZTVkZjcwNDhmIiwiaXNzIjoiY29uc3VtZXIiLCJpYXQiOjE2NDI2MjM4MjksImV4cCI6MTY0MjYyNDEyOX0.orjzmugi-SM920tT3gu713KxjjxgTN7Ck1NbZp2BWxKhZzio96PareDIw8Pnjk70VS7M8vWbOQ_gXUsGnZMMAAK4oKe8IyhC0yjwlMWMsVSOeYdfeCeFfauYZsfXXoteG1_vz_kZ33ko3WIcoP_o1TlROaxUEzdSmGPVa2MQTGY2wqvnCBLcPw4QKflOBel60y822nEUValehJDQsymjfFeD8PMem8dE7A6tze1t3T-4uagsxh0lQH5ETmoJlocswlMC2fNa_pInVqDG3VYmDkn6ZlqEYU6ADNLnGIZVfxMF8qTxlJEIfngUzuPZ4HlZUcDVxITy_1DTU5r7aP6BimR3oGbQ2nR0wLPb5Ri14i1d5edTb6WH04Fu9SdLy1U9dqugfAXgE7xdwGhjy2s-fquzAWernLk85_lvUHCiCy-5HQaRAeTZCV-_sncEPSzjcjnRJzFc6fzO8KZ6oqxTDDl8d-pMHDS5EkwGE-UBayRtrMPjthsG_-2Gh1C9w8dZ-orweDYhTqxtDM_aUDPEijO4x6WJfWWa1c2R36gcZ1cnJ3EbSJ2D28vpQ6FiGjqN6OF0apJxTa1wBcoH60QHeGjYEvqVzmhy8IhFtqgNcQiPs4tZdtrtM32X0P73jAaaLOS-KVKqcsn56kflZURdLJ-qbx37XKjE-Svra3KV2SA"
}

/profiles/identity-verification/exchange

PUT

Exchange a JWT received using Identity Verification in an experience for a Profiles JWT that can be used to retrieve private Profile information

Permissons

This endpoint requires a TDM public token. The token can be submitted using one of two ways:

1. URL parameter access_token=token
2. HTTP header X-Access-Token

Payload

Name	Type	Required	Default	Description
jwt	String	Yes		JWT received from verification service after Identity Verification has been completed
key_field	String	Yes		Id of the key field in the Data Model that matches with the verified identity field in the JWT that is to be exchanged, which is stored in either the value or email field of the Wyng-generated JWT. The key field will be used to look up the Profile that access will be granted to.
expire_in	Integer	No	1800	Number of seconds till JWT will expire

{
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJlbWFpbCI6InJlbmUuc2Ftc29uKzIwMjIuMi43XzZAd3luZy5jb20iLCJleHBlcmllbmNlSWQiOiI2MGY5ZTU4ZWY3ZjZiOTAwMGU4M2YwMTMiLCJ2ZXJpZmllZCI6dHJ1ZSwiaXNzIjoidmVyaWZpY2F0aW9uLXNlcnZpY2UiLCJpYXQiOjE2NDQyOTAwMTQsImV4cCI6MTY0NDMxMTYxNH0.U_dU_lWK0q14fQmR6UrcCdhDfiL7Flx6gm2ZghrbPNHLoU98iI0b4PVgKTfGi_pHWAf2z22xfzxzO7zX3NBiXu-bU2m2YjNxvHRIqOP14qf_IIllPbnMweXp4GcpQbyTULzhx47GRObJXjUhtdcG8VeGydD1ko-q9RUxdFaH2soYvYUjqSgwh1ibB5mVsD6Qu5cxbhAPFzqPYEAHczNDMdUJ33n1Y1LU4E21PeUFbvxcpe9bPG2gjrdSh3qZdmjQXwxO90oYarBa3E0M-W9fRzVvTlIz1SHxz8hStFuj20YQKtoC-0F8Z6YAfB17gL1WHgz0ioS1f-OWEmnlYvf6XWutTBoArVgB9g0RNAH6HZFN23e0GNQs9OKDe6o1Q0EQF8VBnfCvNYCvL51G556FI2vJv0UwlkXRrvmcfRpH7sOOZRLt7sCKtz2XO6YSr1_gdtbIl4aOg-mHfgbgXr1BVn4sw2liHu5zqzqIGBKzkDv28hTiG31zQukjATQw7UNtW_l_7ZCbH0Il6fNH5LiuBS-IpAD4-5ir94Pl2UpCUnknW2DLvozN7KsGYOL_oN9mRXfgsRM2I-Ym0tZ05o2ROfx83BI6XZ3uuJj198dqlDBLxLGDFLLc-378XlhVX_7wSAD3o8W7CBhnZig2WzWQyihLOClx3wJszh0MaOaqTE8",
    "key_field": "email"
}

Expected Response

{
    "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJ0ZG1faWQiOiI2MGY5YzFlNzM5NWVhMDAyMDJlYTM2ZjIiLCJwcm9maWxlX2lkIjoiNjFlODZlNmU5ZjU4YzBjZTVkZjcwNDhmIiwiaXNzIjoiY29uc3VtZXIiLCJpYXQiOjE2NDI2MjM4MjksImV4cCI6MTY0MjYyNDEyOX0.orjzmugi-SM920tT3gu713KxjjxgTN7Ck1NbZp2BWxKhZzio96PareDIw8Pnjk70VS7M8vWbOQ_gXUsGnZMMAAK4oKe8IyhC0yjwlMWMsVSOeYdfeCeFfauYZsfXXoteG1_vz_kZ33ko3WIcoP_o1TlROaxUEzdSmGPVa2MQTGY2wqvnCBLcPw4QKflOBel60y822nEUValehJDQsymjfFeD8PMem8dE7A6tze1t3T-4uagsxh0lQH5ETmoJlocswlMC2fNa_pInVqDG3VYmDkn6ZlqEYU6ADNLnGIZVfxMF8qTxlJEIfngUzuPZ4HlZUcDVxITy_1DTU5r7aP6BimR3oGbQ2nR0wLPb5Ri14i1d5edTb6WH04Fu9SdLy1U9dqugfAXgE7xdwGhjy2s-fquzAWernLk85_lvUHCiCy-5HQaRAeTZCV-_sncEPSzjcjnRJzFc6fzO8KZ6oqxTDDl8d-pMHDS5EkwGE-UBayRtrMPjthsG_-2Gh1C9w8dZ-orweDYhTqxtDM_aUDPEijO4x6WJfWWa1c2R36gcZ1cnJ3EbSJ2D28vpQ6FiGjqN6OF0apJxTa1wBcoH60QHeGjYEvqVzmhy8IhFtqgNcQiPs4tZdtrtM32X0P73jAaaLOS-KVKqcsn56kflZURdLJ-qbx37XKjE-Svra3KV2SA"
}

Error response

When the verification JWT is not verified

Status code: 401

When the verification JWT is invalid for the TDM that is being accessed

Status code: 403

Any other error when generating a JWT

Status code: 404

/segments

GET

Returns the list of defined segments for certain TDM.

Permissons

This endpoint requires a TDM private read token Token can be submitted using one of two ways:

1. URL parameter access_token=token
2. HTTP header X-Access-Token

Expected Response

[
    {
        "id": "612cd80b8f7dc59afd836639",
        "name": "test3",
        "tdm_id": "60f9c1e7395ea00202ea36f2",
        "expression": {
            "operator": "and",
            "operands": [
                {
                    "operator": "profile-attribute-equal",
                    "operands": [
                        "email",
                        "test2@test.te"
                    ]
                },
                true
            ]
        },
        "updated_at": "2021-08-30T13:07:23.777000",
        "created_at": "2021-08-30T13:07:23.777000"
    }
]

POST

define segment for certain TDM.

boolean operators

list of available boolean operators : [ and, or, not ]

and

{
  "operator": "and",
        "operands": [
            "<operand>",
            // …
        ]
    }
}

<operand> can be expression object evaluetes in True if all of <operand> evaluates in True evaluetes in False if some of <operand> evaluates in False

or

{
  "operator": "or",
        "operands": [
           "<operand>",
            // …
        ]
    }
}

<operand> can be expression object evaluates in True if some of<operand> evaluates in True evaluates in False if all of<operand> evaluates in False

not

{
  "operator": "not",
        "operands": [
           "<operand>"
        ]
    }
}

inverts boolean value of<operand> operand can be expression

profile attribute level operators

list of available profile attribute operators : [ profile-attribute-exists, profile-attribute-equal, profile-attribute-lt, profile-attribute-gt, profile-attribute-in, profile-attribute-has ]

first operand in list for profile attribute operators must be valid tdm field id

{
  "operator": "<profile-attribute-operator>",
        "operands": [
           "<profile-attribute-id>",
           "<operand>"
        ]
    }
}

examples:

example profile:

{
    "tdm_id": "5f633bc86feb832df525d51f",
    "fields": {
        "uids": {"value":  [
            "d",
            "c"
        ]},
        "email": {
            "value": "hello@aWoRlD.com",
            "updated": "2021-06-17T10:40:04Z",
            "created": "2021-03-22T10:11:00.347000"
        },
        "hello": {
            "value": "hi",
            "updated": "2021-06-17T10:40:04Z",
            "created": "2021-03-22T10:11:00.347000"
        },
        "test_key": {
            "value": 1234,
            "updated": "2021-06-17T10:40:04Z",
            "created": "2020-01-22T16:11:00.347000"

        },
        "test": {
            "value": 2,
            "updated": "2021-06-17T10:40:04Z",
            "created": "2021-06-17T10:40:04Z"
        }
    }
}

profile-attribute-exists and profile-attribute-not-exists

evaluates in True if profile has seted field with given id

for operator profile-attribute-not-exists results oposite to profile-attribute-exists

following expression for example profile evaluates in: True

{
  "operator": "profile-attribute-exists",
        "operands": [
            "email"
        ]
    }
}

following expression for example profile evaluates in: False

{
  "operator": "profile-attribute-exists",
        "operands": [
            "some"
        ]
    }
}

profile-attribute-equal and profile-attribute-not-equal

checking strict eqality of given value with profile attribute value comparation values of different types not allowed can compare any types of profile attributes lists comparing with sensivity of order( ["a", "b"] not equal ["b", "a"])

1 is equal 1 "a" is equal "a" ["a", "b"] is equal ["a", "b"]

1 is not equal 2 "a" is not equal "b" ["a", "b"] is equal ["b", "a"]

for operator profile-attribute-not-equal results oposite to profile-attribute-equal

following expression for example profile evaluates in: True

{
  "operator": "profile-attribute-equal",
        "operands": [
            "email",
            "hello@aWoRlD.com"
        ]
    }
}

following expression for example profile evaluates in: False

{
  "operator": "profile-attribute-equal",
        "operands": [
            "email",
            "test2@test.te"
        ]
    }
}

following expression for example profile evaluates in: True

{
  "operator": "profile-attribute-equal",
        "operands": [
            "uids",
            [
                "d",
                "c"
            ]
        ]
    }
}

profile-attribute-lt and profile-attribute-gt

strict comparation of given value with profile attribute value comparation values of different types not allowed can compare any types of profile attributes lists comparing with sensivity of order( ["a", "b"] not equal ["b", "a"])

in case when strings are comparing all characters in string comparing consiquently result of comparation depends on first different character in following logic: " " < ... < "@" < "A" < "B" < "C" < ... < "Z" < "a" < "b" < "c" < // …

in case when lists are comparing all items comparing consiquently until first different item and comparing logic for items same as for common value

1 less than 2 "a" less than "b" "abc" less than "bbc" ["a", "b"] less than ["b", "a"]

for operator profile-attribute-gt results oposite to profile-attribute-lt

following expression for example profile evaluates in: True

{
  "operator": "profile-attribute-lt",
        "operands": [
            "test",
            3
        ]
    }
}

following expression for example profile evaluates in: False

{
  "operator": "profile-attribute-lt",
        "operands": [
            "test",
            1
        ]
    }
}

following expression for example profile evaluates in: True

{
  "operator": "profile-attribute-lt",
        "operands": [
            "hello",
            "i"
        ]
    }
}

following expression for example profile evaluates in: False

{
  "operator": "profile-attribute-lt",
        "operands": [
            "hello",
            "g"
        ]
    }
}

following expression for example profile evaluates in: True

{
  "operator": "profile-attribute-lt",
        "operands": [
            "uids",
            ["f"]
        ]
    }
}

following expression for example profile evaluates in: False

{
  "operator": "profile-attribute-lt",
        "operands": [
            "uids",
            ["c"]
        ]
    }
}

profile-attribute-in and profile-attribute-not-in

checks if given value(list/string) includes value of profile attribute

3 is included in [1, 2, 3] "3" is substring of "123"

3 is not included in [1, 2] "3" is not substring of "12"

for operator profile-attribute-not-in results oposite to profile-attribute-in

following expression for example profile evaluates in: True

{
  "operator": "profile-attribute-in",
        "operands": [
            "test",
            [1,2,3,4]
        ]
    }
}

following expression for example profile evaluates in: False

{
  "operator": "profile-attribute-in",
        "operands": [
            "test",
            [1,3,4]
        ]
    }
}

following expression for example profile evaluates in: True

{
  "operator": "profile-attribute-in",
        "operands": [
            "hello",
            "hi some thig else"
        ]
    }
}

profile-attribute-has and profile-attribute-has-not

checks if profile attribute value has given value

attribute is list(set) then checks if attribute includes given value attribute is string then checks if attribute includes given value as substing

[1, 2, 3] includes 3 "123" includes substing "3"

[1, 2] doesn't include 3 "12" doesn't include substing "3"

for operator profile-attribute-has-not results oposite to profile-attribute-has

following expression for example profile evaluates in: True

{
  "operator": "profile-attribute-has",
        "operands": [
            "uids",
            "c"
        ]
    }
}

following expression for example profile evaluates in: False

{
  "operator": "profile-attribute-has",
        "operands": [
            "uids",
            "a"
        ]
    }
}

following expression for example profile evaluates in: True

{
  "operator": "profile-attribute-has",
        "operands": [
            "email",
            "hello"
        ]
    }
}

following expression for example profile evaluates in: False

{
  "operator": "profile-attribute-has",
        "operands": [
            "email",
            "some"
        ]
    }
}

Permissons

This endpoint requires a TDM private edit token Token can be submitted using one of two ways:

1. URL parameter access_token=token
2. HTTP header X-Access-Token

Example request

{
  "name": "test3",
  "expression": {
    "operator": "and",
    "operands": [
      {
        "operator": "profile-attribute-equal",
        "operands": [
          "email",
          "test2@test.te"
        ]
      },
      {
        "operator": "profile-attribute-has",
        "operands": [
          "text_field",
          "some"
        ]
      }
    ]
  }
}

Expected Response

{
    "id": "612cd80b8f7dc59afd836639",
    "name": "test3",
    "tdm_id": "60f9c1e7395ea00202ea36f2",
    "expression": {
        "operator": "and",
        "operands": [
            {
                "operator": "profile-attribute-equal",
                "operands": [
                  "email",
                  "test2@test.te"
                ]
            },
            {
                "operator": "profile-attribute-has",
                "operands": [
                    "text_field",
                    "some"
                ]
            }
        ]
    },
    "updated_at": "2021-09-02T07:12:47.558888",
    "created_at": "2021-09-02T07:12:47.558888"
}

Error response

When invalid expression

Example response

{
    "message": {
        "expression": "Expression profile-attribute-has",
        "message": "first operand must be one of ['email', 'customer_id', 'number_field', 'boolean_field', 'text_field', 'date_field', 'set_field']"
    }
}

Status code: 400

/segments/<segment_id>

GET

Returns the certain segment by id for certain TDM.

Permissons

This endpoint requires a TDM private read token Token can be submitted using one of two ways:

1. URL parameter access_token=token
2. HTTP header X-Access-Token

Expected Response

{
    "id": "612cd80b8f7dc59afd836639",
    "name": "test3",
    "tdm_id": "60f9c1e7395ea00202ea36f2",
    "expression": {
        "operator": "and",
        "operands": [
            {
                "operator": "profile-attribute-equal",
                "operands": [
                    "email",
                    "test2@test.te"
                ]
            },
            true
        ]
    },
    "updated_at": "2021-08-30T13:07:23.777000",
    "created_at": "2021-08-30T13:07:23.777000"
}

PUT

update certain segment by id for certain TDM.

Permissons

This endpoint requires a TDM private edit token Token can be submitted using one of two ways:

1. URL parameter access_token=token
2. HTTP header X-Access-Token

Example request

{
  "name": "test3",
  "expression": {
    "operator": "and",
    "operands": [
      {
        "operator": "profile-attribute-equal",
        "operands": [
          "email",
          "test2@test.te"
        ]
      },
      {
        "operator": "profile-attribute-has",
        "operands": [
          "text_field",
          "some"
        ]
      }
    ]
  }
}

Expected Response

{
    "id": "612cd80b8f7dc59afd836639",
    "name": "test3",
    "tdm_id": "60f9c1e7395ea00202ea36f2",
    "expression": {
        "operator": "and",
        "operands": [
            {
                "operator": "profile-attribute-equal",
                "operands": [
                  "email",
                  "test2@test.te"
                ]
            },
            {
                "operator": "profile-attribute-has",
                "operands": [
                    "text_field",
                    "some"
                ]
            }
        ]
    },
    "updated_at": "2021-09-02T07:12:47.558888",
    "created_at": "2021-09-02T07:12:47.558888"
}

Error response

When invalid expression

Example response

{
    "message": {
        "expression": "Expression profile-attribute-has",
        "message": "first operand must be one of ['email', 'customer_id', 'number_field', 'boolean_field', 'text_field', 'date_field', 'set_field']"
    }
}

Status code: 400

DELETE

delete certain segment by id for certain TDM.

Permissons

This endpoint requires a TDM private edit token Token can be submitted using one of two ways:

1. URL parameter access_token=token
2. HTTP header X-Access-Token

Error response

When segment is not found

Status code: 204