Salesforce Setup

This guide is for brand managers and Salesforce administrators connecting a Salesforce org to io.tt. Once setup is complete, every experience signup will flow into Salesforce automatically — no further configuration is needed per campaign.

For developer documentation on the SDK fields and field mapping, see the Salesforce Developer Guide.

Overview

io.tt connects to Salesforce as a native API integration using a Salesforce Connected App. Setup involves three steps, split between your Salesforce administrator and your io.tt account manager:

Step	Who does it	Where
1. Create a Connected App	Salesforce admin	Salesforce Setup
2. Create io.tt custom fields	Salesforce admin	Salesforce Setup → Object Manager
3. Configure the integration	io.tt account manager	io.tt dashboard (on your behalf)

Step 1 — Create a Connected App in Salesforce

Your Salesforce administrator needs to create a Connected App and share the credentials with io.tt.

Create the Connected App

In Salesforce, go to Setup → App Manager → New Connected App
Fill in the basic details (name, contact email)
Under API (Enable OAuth Settings), check Enable OAuth Settings
Set the Callback URL to https://login.salesforce.com/services/oauth2/callback (placeholder — io.tt uses the JWT bearer flow, not user-facing OAuth)
Under Selected OAuth Scopes, add:
- Manage user data via APIs (api)
- Perform requests at any time (refresh_token, offline_access)
Save the Connected App

Once created, provide your io.tt account manager with:

Field	What it is	Where to find it
Instance URL	Your Salesforce org domain	Browser URL bar when logged into Salesforce — e.g. `https://mycompany.my.salesforce.com`
Client ID (Consumer Key)	Identifies the Connected App	Setup → App Manager → your app → View → Consumer Key
Client Secret (Consumer Secret)	Secret for the Connected App	Same location — Click to reveal
API Version	Which Salesforce REST API version to use	e.g. `v59.0` — io.tt defaults to the latest stable version if not specified

Step 2 — Create io.tt Custom Fields in Salesforce

io.tt writes platform metadata to custom fields on the Lead or Contact object. Your Salesforce administrator needs to create these once.

Where to create them

Salesforce Setup → Object Manager → Lead (or Contact) → Fields & Relationships → New

Create each field as Text with the field lengths shown:

Field Label	Field API Name	Type	Length	Purpose
io.tt Participant ID	`io_tt_participant_id__c`	Text	255	Links the Salesforce record back to io.tt
io.tt Experience ID	`io_tt_experience_id__c`	Text	255	Which experience the participant came from
io.tt Experience Name	`io_tt_experience_name__c`	Text	255	Human-readable experience name
io.tt Experience Type	`io_tt_experience_type__c`	Text	50	e.g. `competition`, `loyalty`, `gifting`
io.tt Brand Name	`io_tt_brand_name__c`	Text	255	Brand name

Custom `extra` fields (per experience)

If the experience collects custom form fields (e.g. age range, product preference), each maps to an additional custom field named io_tt_extra_{key}__c. These are created on a per-experience basis — your io.tt account manager will provide the exact list of field names needed before launch.

You only need to create fields for the extra keys your experience actually collects. Coordinate with the developer building the experience form to get this list.

Step 3 — Configure the Integration in io.tt

Your io.tt account manager configures the Salesforce integration on your behalf in the io.tt dashboard. You will need to confirm the following decisions:

Setting	Options	Notes
Object Type	`Lead` or `Contact`	Which Salesforce object participants are written to. Can differ per experience — e.g. a competition goes to Lead, a loyalty programme goes to Contact
Upsert Field	Usually `Email`	The field io.tt uses to upsert records — if a record with a matching value already exists it is updated, otherwise a new one is created. Defaults to `Email` — can be changed to a custom `io_tt_uid__c` field if preferred

What Happens After Setup

Once the integration is live:

Every experience signup is automatically written to Salesforce as a Lead or Contact
Records are upserted — if a matching record already exists (by email), it is updated rather than duplicated
All standard participant fields (name, email, address, marketing consent) are mapped to standard Salesforce fields
io.tt context fields (experience ID, brand name, etc.) are written to the io_tt_* custom fields you created
Custom extra fields from the experience form are written to their matching io_tt_extra_{key}__c fields

No action is required per campaign — once configured at the organisation level, all experiences for that brand route to Salesforce.

Object Type Detail

io.tt writes to either Lead or Contact depending on what's configured for each experience. The two objects have minor field name differences:

io.tt field	Lead field	Contact field
`addressLine1`	`Street`	`MailingStreet`
`locality`	`City`	`MailingCity`
`administrativeDivision`	`State`	`MailingState`
`postalCode`	`PostalCode`	`MailingPostalCode`
`country`	`Country`	`MailingCountry`
`dateOfBirth`	(not available on Lead)	`Birthdate`

If your experience collects date of birth and uses Lead as the object type, that field will not be mapped. In this case, either switch to Contact or store date of birth in an extra field with a matching custom field.

Checklist

Before going live, confirm the following:

Connected App created in Salesforce and credentials shared with io.tt
All io_tt_* custom fields created on the correct object (Lead or Contact)
Custom extra fields created for any additional form fields the experience collects
Object type confirmed (Lead or Contact) with io.tt account manager
Upsert field confirmed (default: Email) with io.tt account manager
io.tt account manager has confirmed the integration is active for the experience

On this page