Website API Implementation

Why:

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.

What:

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.

How:

To implement the API navigate to https://thirtyonecircles.com/app/audiences/connections and select manage next to API input. The templates that are displayed can be copied directly into Google Tag Manager (or other tag management software) ready to be configured off the correct events and parameters. 

The code will look like:

There are three key events and one optional event to track.

  1. 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.
  2. 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.
  3. 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)  

  1. When a user changes their email, you can fire the “Change Email” template to reflect this in the data.

PARAMETER GUIDE

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.

Required

  • 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)

Optional

  • 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)
  • ph_ha1 and ph_ha2: SHA256 hash of the phone number (please review the hashing guide for the correct formatting that can be provided instead of the raw phone number. 

CONSENT + CONDITIONAL FIRING

All API calls must be fired as strictly necessary and always be set to fire. Failure to do reduces GDPR compliance. 

During API implementation we recommend updating your cookie policy to reflect this.

In detail: Thirty-One Circles acts as a consent management platform on your behalf, adding your customers to targeting audience and removing them based on their current consent level. If Thirty-One Circles was fired conditionally only with "Advertising Cookies", your customers would only ever be added to audiences and not removed (as Thirty-One Circles would not be informed of the change) this is why Thirty-One Circles API tags must always fire to ensure your GDPR compliance. 

Once you have implemented the API, please get in touch with a member of our support team at support@thirtyonecircles.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.

When:

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).

Back to Support

More questions?

Contact our support team at support@thirtyonecircles.com who are always ready to offer advice and assistance. 

Thirty-One Circles Logo