Interacting with profile

Observation and event tracking

Gravito has powerful capabilities with which you can send observations about profiles and the API can aggregate it and provide you results in near real time, with this the web visits of every users can be tailored based on his/her previous behavior.

post
Identify Gravito or Observed Profile

https://handshake.gravito.net/api/ap
This method will be the first call towards Gravito's Handshake API , where a Gravito observed profile is created or if the user already logged into to Gravito, then details about the logged in profile is returned. There is no parameter or request body mandatory for this request initially. Please see the response section to see the sample response. The parts of the response includes the ConsentSet for the logged in user for the specific requesting domain All parameters in this method are boolean query parameters.
Request
Response
Request
Query Parameters
includeSharedProfileHistory
optional
boolean
Return the list of event tagged under the shared profile if you have registered as a customer. The latest values of keys as well as list of key values per domain is returned.
includeProfileHistory
optional
boolean
Returns a big list of all the event and keyvalues captured against the profile. Default value is false
includeCampaign
optional
boolean
Returns the content of any web based campaigns that the profile is part of. Default value is false
includeProfile
optional
boolean
Returns the latest event captured for that domain. Default value is false. Property "consolidatedProfile" will be passed with the latest event recorded.
Response
200: OK
{
"source": "gravitoUid"/"gravitoOpUid",
"id": "<specificid>",
"tcAgreed": false,
"consentDataSet": [
{
"name": "Web",
"value": true,
"type": 1,
"lastUpdated": "2019-02-08T11:22:24.2078879Z"
},
{
"name": "Mobile",
"value": true,
"type": 1,
"lastUpdated": "2018-11-02T12:59:03.7456298Z"
},
{
"name": "Email",
"value": true,
"type": 1,
"lastUpdated": "2018-06-26T08:24:02.2965514Z"
},
{
"name": "SMS",
"value": false,
"type": 1,
"lastUpdated": "2018-06-26T08:24:02.2965514Z"
},
{
"name": "Call",
"value": false,
"type": 1,
"lastUpdated": "2018-06-26T08:24:02.2965514Z"
},
{
"name": "Snail mail",
"value": true,
"type": 1,
"lastUpdated": "2018-11-23T12:19:55.7902445Z"
},
{
"name": "Data Collection",
"value": true,
"type": 0,
"lastUpdated": "2018-06-26T08:24:02.2965525Z"
},
{
"name": "Analytics",
"value": true,
"type": 0,
"lastUpdated": "2018-06-26T08:24:02.2965525Z"
},
{
"name": "Targeting",
"value": true,
"type": 0,
"lastUpdated": "2018-06-26T08:24:02.2965525Z"
},
{
"name": "Cross Device",
"value": false,
"type": 0,
"lastUpdated": "2018-06-26T08:24:02.2965528Z"
},
{
"name": "Sharing Data",
"value": true,
"type": 0,
"lastUpdated": "2018-06-26T08:24:02.2965528Z"
},
{
"name": "Reidentification",
"value": true,
"type": 0,
"lastUpdated": "2018-10-29T13:21:29.8818477Z"
}
],
"consolidatedProfile": {
"event": "pageView",
"pageName": "We are Gravito < Gravito Ltd"
},
"profileHistory": [
{
"Key": "event",
"Value": "pageView"
},
{
"Key": "pageName",
"Value": "Register < Gravito Ltd"
}],
"campaignContents": [],
"sharedConsolidatedProfile": {
"event": "consent",
"consentString": "latestValueUnderCustomership"
},
"sharedProfile": [
{
"domain": "domain 1",
"keyValues": {
"event": "consent",
"consentString": "consentString"
}
},
{
"domain": "domain 2",
"keyValues": {
"event": "consent",
"consentString": "consentString"
}
}
]
}

post
Register a Gravito Profile under your domain

https://api.gravito.net/api/account/register
This endpoint is used to collect profiles under your domain, and can be used to register the user with basic information like first name, last name, phone number etc with the email. Also based on the need, you can pass on specific Gravito consents to mark the consent for a specific channel for the profile. A typical use case is a contact collection form, with which you can collect user tagged with a specific segment Parameters consents: The expected consent names are as below. Channel wise communication consents: Web, Email, SMS, Mobile, Call, Snail mail Data consents Data Collection, Analytics, Cross Device, Sharing Data, Reidentification mapToDomain: Based on the request coming in, when you need the request to act under a different domain, you can send this optional parameter to map the user, the segment assignment etc to this. "mapToDomain" if present takes priority over the request origin. Also, please validate the request to make sure that, both the domains should be related and should be white-listed domains under the same customer-ship, you are operating under needsConfirmation: This flag denotes whether a confirmation email needs to be sent on registration. Works together with the following two parameters to redirect the user on confirmation and how long the link is valid reDirectLinkOnConfirmation: Link to which the user is redirected to on confirmation reDirectLinkValidForInHours: Time in hours the redirect link is valid for (default: 24). Values from 2 to 168 is allowed This is a sample of the request you can send. Email is mandatory to create the profile with. { "email": "string", "firstname": "string", "lastname": "string", "needsConfirmation": true, "mapToDomain":"string", "reDirectLinkOnConfirmation": "string", "reDirectLinkValidForInHours": 0, "phoneNumber": "string", "countryCode": "string", "tagSegments": [ "string" ], "untagSegments": [ "string" ], "consents": [ { "name": "string", "value": true } ] }
Request
Response
Request
Response
200: OK
Successful creation or identification of a profile with that email address will return you the Gravito Id and whether a profile was created or was something that was already existing. Using the firstLogin flag.
{
"firstLogin":false,
"id":<Gravito Id>
}
400: Bad Request
If you pass wrong Consent names that Gravito cannot understand. If you pass as confirmation needed but without the link to redirect the user to if you pass non supported number of hours for the redirection link to be valid(2- 168 hours). Default is 24 hours if you try to map the request to a domain which is not related to the requesting domain.
{"error":"Sorry, invalid consent name(Note: Case sensitive eg: Web, Email). Please check with admin to get the supported consent names!"}
{
"error": "Error while creating user. Please try again! : Sorry, redirect url is mandatory if confirmation required!"
}
{
"error": "Error while creating user. Please try again! : Sorry, link expiry has to be in hours and between 1 and 168(7 days)"
}
{
"error": "Error while creating user. Please try again! : Sorry, Domains not related"
}

Sample request is mentioned below with out registration confirmation needed

{
"email": "String(collected from a form for eg:)",
"firstName": "string",
"lastName": "string",
"countryCode": "string",
"phoneNumber": "sring",
"untagSegments": [
"segmentToMoveUserOutOf"
],
"tagSegments": [ "segmentToMoveUserTo" ],
"consents": [
{
"name": "Email",
"value": true
},{
"name": "SMS",
"value": false
}
]
}));
})();

Confirmation Email

In case you need confirmation email to be sent to the user, please make sure that a transactional campaign is setup for the specific Segment which you are tagging to the user, with the handle {{G_MAGIC_LINK}} under a button or as a link so that the user can be redirected to the specific page as needed.

Notes

Note: If confirmation is required for the user, Gravito by default will skip the consent check for the user and will only apply the consents which you are sending with the requests once the user confirms by clicking on the link.

If you need segments to be created on the fly, for eg: product combinations, page combinations, country language combinations etc, then please make sure that you request your Customer Admin user to set the flag for "Allow Segment Creation on the Fly" under the specific domain for which you are sending the request.

post
Gravito Identity Federation

https://api.gravito.net/api/gp/federate
This end point can be used to federate the Gravito identity with the consents. Gravito Identity can have two parts, - GravitoUid (Gravito Id) which is unique to a email address - GravitoOpUid (Gravito Observed Profile Id) which is a specific id for a GravitoUid per device or session or browser to get details of the user per device.
Request
Response
Request
Response
200: OK
This is the success output
{
"Domain": "<registered Domain>",
"GravitoUid": "<gravitoId>",
"GravitoOpUid": "<gravitoOpId>",
"AccessToken": null,
"ProfileConsents": [
{
"name": "Web",
"value": false,
"type": 1,
"lastUpdated": "2019-06-10T15:43:25.2308018+00:00"
},
{
"name": "Mobile",
"value": true,
"type": 1,
"lastUpdated": "2019-02-27T07:03:18.36024Z"
},
{
"name": "Email",
"value": true,
"type": 1,
"lastUpdated": "2018-06-26T08:24:02.2965514Z"
},
{
"name": "SMS",
"value": false,
"type": 1,
"lastUpdated": "2018-06-26T08:24:02.2965514Z"
},
{
"name": "Call",
"value": false,
"type": 1,
"lastUpdated": "2018-06-26T08:24:02.2965514Z"
},
{
"name": "Snail mail",
"value": false,
"type": 1,
"lastUpdated": "2018-06-26T08:24:02.2965525Z"
},
{
"name": "Data Collection",
"value": true,
"type": 0,
"lastUpdated": "2018-06-26T08:24:02.2965525Z"
},
{
"name": "Analytics",
"value": true,
"type": 0,
"lastUpdated": "2018-06-26T08:24:02.2965525Z"
},
{
"name": "Targeting",
"value": true,
"type": 0,
"lastUpdated": "2018-06-26T08:24:02.2965525Z"
},
{
"name": "Cross Device",
"value": false,
"type": 0,
"lastUpdated": "2018-06-26T08:24:02.2965528Z"
},
{
"name": "Sharing Data",
"value": true,
"type": 0,
"lastUpdated": "2019-06-07T10:20:41.4121588+00:00"
},
{
"name": "Reidentification",
"value": true,
"type": 0,
"lastUpdated": "2019-06-07T10:20:41.4122003+00:00"
}
],
"IsSuccess": true
}
401: Unauthorized
This happens when you are not passing in the correct domain Key
{
"ErrorCode": 401,
"GravitoErrorCode": "GRA7004",
"Description": "Please review your access credentials for the api: DomainKey",
"DocumentationLink": "docs.gravito.net"
}

This is the sample json input. Different parameters in this input depends on the scenarios how you are using it

{
"email":"<string>",
"domain":"<string>",
"gravitoUid": "<string>",
"gravitoOpUid": "<string>",
"profileConsents": [
<List of Consents>
],
"untagSegments": [
"segmentToMoveUserOutOf"
],
"tagSegments": [ "segmentToMoveUserTo" ],
}

This api can be used in 4 different scenarios

  • Scenario 1: Gravito Profile Unknown.

    • In this case the email alone is passed to the endpoint .

    • The endpoint responds with a GravitoUid for the email claim in the jwt token.

    • The Url also generates a GravitoOpUid for the email for the specific session/device

    • The consent set(existing user consents if available, else default consent set, after adding the issuer domain )

  • Scenario 2: Gravito Profile known, but new session/device

    • In this case the email as well as GravitoUid is passed into the endpoint

    • The endpoint generated a GravitoOpUid for the email for the specific session/device

    • The consent set (existing user consents if available, else default consent set, after adding the issuer domain)

  • Scenario 3: Gravito Profile known, GravitoOpUid Known.

    • In this case the Email , GravitoUid, and GravitoOpUid is passed to the endpoint.

    • The endpoint return the consent set(existing user consents if available, else default consent set, after adding the issuer domain)

  • Scenario 4: Changing consents

    • In this case Email, GravitoUid and GravitoOpUid is passed to the end point, plus a list of changed consents

    • The endpoint updates the consent set for the user, logs it under his profile as a Domain activity and returns the new set of Gravito Consents

If you need segments to be created on the fly, for eg: product combinations, page combinations, country language combinations etc, then please make sure that you request your Customer Admin user to set the flag for "Allow Segment Creation on the Fly" under the specific domain for which you are sending the request.

//Example consent set
[
{
"name": "Web",
"value": false,
"type": 1
},
{
"name": "Mobile",
"value": true,
"type": 1,
"lastUpdated": "2019-02-27T07:03:18.36024Z"
}
]

get
Listen for events and tagging to segments

https://handshake.gravito.net/api/listen
This endpoint can be used to tag any observation to the profile as a key value pair. It also has the feature to tag a preexisting segment to the user. This can be achieved using specific keys. The events you pass can be accessed shared under 3 realms 1. Under the specific domain 2. Under the domains under the specific customer 3. Publicly Note: All events passed can be accessed under the same domain and customer-ship(list of domains registered under the same customer) under the property using query parameters from the identify API Under the event key value pair if you pass &shared=true with a list of events they will be marked as public events which any domain can access publicly
Request
Response
Request
Query Parameters
guid
optional
string
For case where the cookies might not propagate as part of the request Gravito allows you to pass the Gravitoid with the request. This is specifically used together with tag and untag segment parameters
gopuid
optional
string
For case where the cookies might not propagate as part of the request, Gravito allows you to pass the Observed Profile Id with the request. This query parameter is considered only if the observed profile cannot be resolved from the cookie
untagSegment
optional
string
This parameter can be used to untag a preexisting segment from a user
tagSegment
optional
string
This parameter can be used to tag a preexisting segment to a user.
event
optional
string
An event you are tracking. Ideally any value can be passed to the API and it will keep track of the event as a key value pair
Response
204: No Content

Sample Requests

Here is a sample request to send a key value pair. This Key value pair will be available in profile when requested, under the domain as well as other domains under the customer-ship

GET https://handshake.gravito.net/api/listen?event=consent&consentString=value

The request below shows how to send a request where the key value pair passed together with the "shared=true" will make it available publicly to any other domain even outside the customer-ship

GET https://handshake.gravito.net/api/listen?event=pubicConsent&publicConsentString=value&shared=true

The response will be a 204