Website API Implementation
The Website API is a crucial step in setting up your Thirty-One Circles account.
The API provides three pieces of information to the platform
- User identifiers (email/phone number)
- Consent information
- ID identifiers (Google Analytics User ID / Transaction ID)
By getting this information simultaneously, we can then use this as a key to unlock your first-party data.
The API is implemented by putting a short code snippet on your website. The API can be implemented directly on the website or through a tag management system like Google Tag Manager (GTM). As the data needed is often the same as other platforms, if you already have a tag management system, Thirty-One Circles can often be implemented without further web-developer assistance.
NOTE: The API is compatible with standard tag management and server-side tagging if you use this approach.
There are three key events and one optional event to track.
- The first key event is – Cookie Banner Consent Updated; this should fire the “Permissions updated” template when: The Cookie Banner settings have changed or been set for the first time AND email or hashed email data is present. Do not fire this event on user cookie banner changes without email or hashed email data.
- The second event is – User Login; this should fire the “Login” API template when the user logs into the website and their user data becomes available.
- The third event is – Transaction; this should fire the “Transaction” API template when the user completes a purchase on the website.
Optionally (but best practice)
- When a user changes their email, you can fire the “Change Email” template to reflect this in the data.
While each template is unique, each requires information from the website to be inserted into it. The section where the template needs data needs inserted is in orange and contains several parameters for different pieces of data.
It is recommended to provide as complete a template as possible however the data can be divided into required and optional fields.
- c2: Advertising Consent passed as either 1 or 0 for Has / Has not given consent, respectively. A null value can be passed if the user has not set the consent (for instance, if they have not interacted with the cookie banner when they log in).
- em or ha: User email (unencrypted) or hashed user email, respectively (please click here for hashing instructions). It is necessary to provide either email or hashed email, but it is not required to send both.
Required for the transaction template:
- transaction_id: The same transaction ID passed to Google Analytics
Required for email change template:
- previous_em or previous_ha: The previous email or hashed email of the user (either can be sent only as only one is required)
- gaUserId: The same user ID passed to Google Analytics
- ph: The phone number of the user. If passed, this must include the country code of the user. (For example, a UK number must start with 44)
Once you have implemented the API, please get in touch with a member of our support team at email@example.com or your account representative who will double check that the data is pulling through correctly into our system. If at any stage you need support in the implementation reach out as we are happy to provide a helping hand for your team.
Data from the API will now create new and update your existing customer records automatically each day. While this data is being collected, you can start building audiences and wait for sufficient audience size, or you can backdate our audience data with your own to quick-start the process (click here to find out more).