Skip to main content

Attribute Sync

Introduction

Attribute sync allows associatingenables users withto be linked to attributes whichthat can be used for inventory,inventory management, campaign insights,analysis and targeting.
These associations are retrieved onwhen ad-request.an ad is requested.

BecauseAs the data is associated with a userIduser ID, consent is needed.required. When you push data to adheseAdhese via the attribute-sync, we assume that the sender has validated the consent. Do not pushsend userdataus data for which no consent washas been given.

OnWe do validate consent on the ad-request sideside. weAd do validate consent. An ad-requestrequests without a userIduserID or consent will not getbe linked with theto data that was pushed via attribute-sync.

Pushing data

Authentication

The first step ofin pushing data,data is retrievingto retrieve a valid JWTJSON tokenWeb Token (JWT) from our keycloak.Keycloak server. We use the ROPC flow, but this exact flow may change in the future. You will be provided with the login credentials for an account that is specifically used for the attribute-sync.

An example request to retrieve a JWT token

curl --location 'https://auth.we.adhese.org/realms/user-sync/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=user-sync-app' \
--data-urlencode 'username=[username]' \
--data-urlencode 'password=[password]' \
--data-urlencode 'grant_type=password'

This token can be re-used multiple times untilbefore it expires.

IP-filtering

IfUpon requestedrequest, we can enable IP-filtering on the attribute-sync endpoint. If enabledIP-filtering is enabled, we will only accept data coming from a predefined list of IP-Addresses.IP addresses.

Uploading data

ActuallyThe uploading of data actually happens via the https://ads-[customer].adhese.com/usersync/attributesync endpoint (POST with json payload).

BeEnsure sure to passthat the access_tokenaccess token from the previousprior steps is used as a bearer token in the Authorization headerheader.

{
  "reportDateTimeValid": "2026-02-11T17:11:00Z",
  "entries": [
    {
      "identifier": {
        "name": "DIGIMON_ID",
        "value": "userId1"
      },
      "attributes": [
        {
          "name": "firstAttribute",
          "value": [
            "known_app_user",
            "example_value"
          ]
        },
        {
          "name": "secondAttribute",
          "value": [
            "known_app_user2",
            "known_test_trait_pageview_less_then_2"
          ]
        }
      ]
    },
    {
      "identifier": {
        "name": "DIGIMON_ID",
        "value": "foobar"
      },
      "attributes": [
        {
          "name": "firstAttribute",
          "value": [
            "known_app_user",
            "another_example_value"
          ]
        }
      ]
    }
  ]
}

Above you can see an example payload.

reportDateTimeValid Optional HowFor how long should we can/should store the data from this request.request? If absentthis is not specified, we default to 7seven days in the future. By defaultdefault, we limit the validity to a maximum of 30 days in the future.days.
entries Mandatory

Each user is represented by anone entry. We accept up to 500 entries per request.

ToIf you need to store data for more than 500 users, please usesubmit multiple requests instead.requests.
entries.identifier.value Mandatory

This field represents the userId of this entry.
entries.identifier.name Mandatory

Some customers have different types of userIdsuserIDs (ege.g. an actual userIduserID and a deviceId)deviceID) and want to be able to store different data for the same userIdID if the userIdit came from a different source. 
You can think of this as a namespace for your userIds.userIDs. These can be arbitraryarbitrary, but need tomust be used consistently.


Please

Informinform our support agents which ones you plan to use.

 


Even if you only use a single source of userIds,user IDs, you still need to choose a value still needs to be chosen.

value.
entries.attributes Mandatory but can be empty

Can be left empty for deleting data. See below.
entries.attributes.name Mandatory

The attribute for which you want to store values for the specific userId.
entries.attributes.values Mandatory

The values you want to store with the attribute for the specific userId.

Each time we receive data via the attribute-sync for a specific user, itthe latest request overwrites the data fromany previous requests regardingfor that user, even if certain attributes arewere included in an earlier request but not included in the latest request but were in the first request.one.
This has as athe side effect that you can delete all (attribute-sync)sync data associated with a user by leaving the entries.attributes field empty. 

BecauseAs attribute-sync is meantintended for textualtext-based data, we maycannot rejectaccept data that containscontaining Unicode control characters. 

Using the data

Cooperate with supportSupport to configure which target(s)targets representcorrespond userId(s),to which userIDs and which attributeattributes correspondscorrespond withto which target.targets. WhenOnce donethis ad-is complete, ad requests with consent and a userIduser ID will automatically getreceive additional targets from the data you pushed, even if the push happenedoccurred less than a second ago.

What data to store

BecauseAs all the data pushed via the attribute-sync needs tomust be accessible withoutimmediately, delay, this datait is stored in memory. For this reasonreason, we ask toplease be mindful of whatthe data you store:store.

  • Only store attributes that you actually plan on using.using
  • Do not make attributes/attributes or attribute values overly verboseverbose; (they do not need to be human readable)human-readable
  • Keep userIds to a reasonable length

 

Back to top