Profile API¶
Warning
The Profile API is in a closed beta. This is a preview topic about the Profile API.
Ask your Amperity representative about how (and when) your tenant can get access to the Profile API so that your brand can use the Profile API to enable real-time use cases.
The Profile API is a RESTful API that supports building custom endpoints against unified customer profiles to enable any downstream real-time workflow.
The Profile API is unique to your tenant. The endpoints that are enabled for your real-time use cases do not exist until you build them.
How the Profile API works¶
Each endpoint is defined by a query that you build in the Queries page, after which it may be generated as an index within the Profile API. A query defines an index, which is set of fields that exists within your unified customer profiles. A unique identifier acts as the lookup key to that index for the downstream real-time workflow.
You can build as many endpoints as your downstream real-time workflows require. Each individual endpoint can represent any section of your unified customer profiles:
Loyalty programs
Profiles built from hashed email addresses to support personalization for omnichannel customers
Extended profile attributes for use with downstream systems, such as Braze, Cordial, and Salesforce Marketing Cloud
Most recent purchases, favorite products, or other aspects of your product catalog
Personalization for websites, product suggestions, etc.
Any set of results that you can return with a query in Amperity can be enabled for use as an endpoint for your tenant’s Profile API. Use any unique identifier in your unified customer profiles as the lookup key, use that lookup key to access individual attributes located at that endpoint, and then the on-demand access to your unified customer profiles to light up your real-time use cases.
Tip
Use more (smaller) indexes instead of fewer (larger) indexes! Build each endpoint to be as specific to your downstream real-time use case requirements as you need it to be.
Profile API endpoints¶
The Profile API has the following endpoints:
Important
The Profile API does not currently enforce a rate limit. A rate limit will be introduced at a point in the near future.
What policies will users need?
The Profile API requires the following policies to be assigned to users within your tenant:
Profile API Administrator This policy allows users to use the Destinations page to manage endpoints in your tenant’s Profile API.
API Key Administrator This policy allows users to use the Users and Activity page to manage API keys and tokens required by Amperity APIs.
These policies may be assigned to the same user.
GET indexes¶
Use the indexes endpoint to get a list of indexes that exist in your tenant’s Profile API.
The URL for this endpoint is:
https://app.amperity.com/attribute/v0/indexes
Note
The URL should not have a trailing slash.
cURL example
curl -H "X-AMPERITY-TENANT: {tenant-id}" \
-H "Authorization: Bearer ${access-token}" \
-H "Content-Type: application/json" \
'https://app.amperity.com/attribute/v0/indexes'
where {tenant-id} is the name of your tenant and {access-token} is the access token.
Response
The response returns a list of endpoints (indexes) that are available within your tenant’s Profile API. For example, a list of three indexes (Braze User Profiles, Product Catalog, and Hashed Email Profiles) will have a response similar to:
{"indexes":
[
{"id":"ix-aBCdeFgh",
"name":"Braze User Profiles",
"field":"external_id",
"build": {
"created_at":"2023-05-31T08:15:00.000Z",
"updated_at":"2023-05-31T08:15:00.000Z",
"build_id":"idb-ABc12dE3FG4"
}
},
{"id":"ix-1AbcD234E",
"name":"Product Catalog",
"field":"product_id",
"build": {
"created_at":"2023-05-31T09:30:00.000Z",
"updated_at":"2023-06-01T09:30:00.000Z",
"build_id":"idb-12abcD3EFG4"
}
},
{"id":"ix-01AbcdE23",
"name":"Hashed Email Profiles",
"field":"hashed_email",
"build": {
"created_at":"2023-05-31T10:45:00.000Z",
"updated_at":"2023-06-01T10:45:00.000Z",
"build_id":"idb-acbdEFGHIj1"
}
}
]
}
POST indexes/{index-id}¶
Use the indexes/{index-id} endpoint to use the lookup key for {index-id} to access individual attributes for that lookup key.
The URL for this endpoint is:
https://app.amperity.com/attribute/v0/indexes/{index-id}
where {index-id} matches the index ID that is configured for that endpoint in Amperity. Individual attributes are available from {index-id} by using the lookup key for that index to return specific named attributes.
Note
The URL should not have a trailing slash.
The lookup key is available from Real-time Profile API list. For the endpoint, open the actions menu and select “Copy Index ID”.
cURL example
curl -H "X-AMPERITY-TENANT: {tenant-id}" \
-H "Authorization: Bearer ${access-token}" \
-H "Content-Type: application/json" \
-d '{"key": "{lookup-key}"}' \
-X POST 'https://app.amperity.com/attribute/v0/indexes/{index-id}'
where {tenant-id} is the name of your tenant and {access-token} is the access token. Update {index-id} to match the index ID for this endpoint, and then specify the {lookup-key} value to return the list of attributes associated with that row.
Response
The structure of the response depends on the attributes that are available within the index. The body of the response is similar to:
{"attributes"
{"value" {"attribute": "value"}, "lookup-key" "lookup-key-value"},
"metadata" {
"build-id" "build-id-value",
"index-id" "index-id-value"}
}
For example, an index that uses “loyalty_id” as the lookup key, and returns “firstname”, “lastname” for loyalty ID “a-01234-b” for a customer named “Dennis Terrell” will have a response similar to:
{
"attributes": {
"value": {
"loyalty_id": "a-01234-b",
"firstname": "Dennis",
"lastname": "Terrell"
},
"key": "a-01234-b"
},
"metadata": {
"build-id": "idb-1ABcD2EFGhI",
"index-id": "ix-aBCdeFgh"
}
}
Note
If an attribute is not unique for the specified lookup key value, a value will be returned, but it may not be the value you were expecting.
Profile API responses¶
The Profile API returns the following HTTP status codes:
HTTP status codes
Status code |
Description |
|---|---|
200 OK |
The requested value(s) for the specified lookup key were returned successfully. |
403 Forbidden |
Verify the access token, index ID, and {tenant-id} used to make the request. |
404 Not Found |
The requested value was not found. For example:
Note A 404 Not Found status code will be returned when the URL contains a trailing slash. |
503 Service Unavailable |
A generic error has occurred. The service may be unavailable. Verify the configuration of the request and the expected response values and try again. |
Queries¶
A query defines the list of attributes that will be available from a Profile API endpoint, along with providing the lookup key that POST requests will use to return attribute values for the specified lookup key. Use the Queries page to build the query. Group all of the queries that support real-time use cases into the same folder.
Tip
All attribute names within a query that is used to build an endpoint for the Profile API should be unique to ensure that all attributes are unique by lookup key value in the index.
There are two requirements for queries that are used to define Profile API endpoints:
One field must be usable as the lookup key for the index. The value for this field must be a unique identifier. For example, the Amperity ID, a loyalty ID, a customer ID, a unique identifier in a downstream workflow (such as the “external_id” used in Braze), a non-hashed email address, a hashed email address, and so on.
Use the unique identifier that works best for your real-time use case. Each endpoint may specify its own lookup key. For example, for website personalization you might use a customer ID or a loyalty ID, but when building your marketing campaigns in Braze that bring your customers to that website, you could use the Braze “external_id” for the index.
There must be at least one attribute in that query that can be returned by the request to the endpoint for the specified lookup key. There is no practical limit to the number of attributes that can be in the index, but it is recommended to keep the list of attributes specific to your real-time use case.
Plan to use a variety of indexes to support a variety of real-time use cases instead of using a single, large index. Some indexes, with the right combination of attributes, may be used to support multiple real-time workflows.
Lookup keys¶
The lookup key for an index is the primary key for that index. The field in the index that acts as the lookup key must be a field that provides a unique identifier, such as the Amperity ID, a loyalty program ID, an ID that is unique in the downstream location from which the Profile API will be used to enable real-time use cases, or some other identifier that allows a POST request to return a series of attributes that are associated with that unique identifier.
Each endpoint must have a lookup key. You can find the lookup key for any endpoint from the Lookup Key column in the Real-time Profile API list:
Important
The lookup key in the request must have an exact match within the index.
For example: “Dennis” must match with an uppercase “D” and “Dennis ” must match with both an uppercase “D” and a trailing character.
Because each endpoint is defined using SQL within the Query Editor, the point at which you will define the consistency for how your downstream real-time use case will access that data is from within the Query Editor.
This should be done before making that query available to the Profile API.
Formatting requirements are often determined by how the downstream real-time use case will access the Profile API endpoint. These requirements include the tools that you will use to access the Profile API and also the individuals within your organization who need to understand how that information should be accessed.
Index IDs¶
The index ID is a unique identifier for an endpoint. To make a POST request to an endpoint you must include the index ID in the URL for the request.
The index ID is available from the Real-time Profile API list. For the endpoint, open the actions menu, and then select “Copy index ID”.
To make a POST request to a specific index, add the index ID to the end of the request URL:
https://app.amperity.com/attribute/v0/indexes/{index-id}
and then use the lookup key in your real-time workflow to return individual attribute values in that index.
Access token¶
Amperity uses a JSON Web Token (JWT) for authentication to the Profile API. A single access token may be used to access any endpoint in your tenant’s Profile API.
The access token is self-generated from the Amperity user interface and authorizes GET and POST requests to all endpoints in the Profile API for your tenant. A self-generated access token ensures that only your team has access to the token and supports organizational security policies like periodic access token rotation.
The access token must be available to each request made to the Profile API.
Tenant ID¶
The tenant ID is a unique identifier for your tenant. To make a GET or POST request to an endpoint you must include the tenant ID in the URL for the request.
The tenant ID is available from the Real-time Profile API list. For the endpoint, open the actions menu, and then select “Copy tenant ID”.
Configure the Profile API¶
The Profile API must be configured for use in Amperity. This is done in a series of steps:
Note
For endpoints that are running in your production environment that are actively being used with real-time workflows, you should be careful about making changes to the list of attributes that are available in the index and to the values that are contained within those attributes. There are two approaches you could take:
Use a sandbox to make changes directly to the “production” index, but run it from the sandbox to validate the changes and the effects those changes may have on the downstream workflow. This approach allows you to keep the same index ID in place and helps prevent disruption to any live Profile API integrations.
Build a new index that contains the changes, and then test those changes incrementally downstream on individual locations within the real-time workflow. This requires updating the index ID in the downstream workflow.
Request to enable¶
To enable the Profile API for your tenant:
|
Contact your support representative via the Amperity Support Portal (or send email to support@amperity.com) and request enabling the Profile API for your tenant. Support will enable the Profile API on your tenant and will let you know when the process is completed. Important Your support representative will use SnapPass to provide the temporary access token for the Profile API. (Amperity is building an interface that will allow you to self-generate the access token for the Profile API. This will ensure that only your team has access to the tokens and will make it easier to follow your organization’s security policies, such as periodically refreshing the access tokens.) |
|
After the Profile API is enabled, the Destinations page is updated to show the list of endpoints available to the Profile API: 
|
Build a query¶
Build a query that contains the attributes you need to enable your downstream real-time workflows. You can use any aspect of your unified customer profiles to light up these workflows. Consider your goals for each real-time workflow, build a query that returns the list of attributes (and lookup key) that enables that real-time workflow.
Important
The real-time Profile API can support an unlimited number of potential use cases. All you need to do is imagine the use case, identify the requirements for building that use case for your downstream workflow, and then build a query in Amperity that can be used to generate an index that contains the attributes you need to light up that use case.
Add API key¶
A data access token enables your downstream real-time use cases to read data the Profile API.
To add a data access token for the Profile API
|
|
Open the Users & Activity page. Under API keys click Add API key. |
|
|
From the Add API key dialog, add the name for the API key, select the Profile API Data Access option, and then click Save. 
|
Generate an access token¶
Access tokens that enable authentication to the Amperity API are managed directly from the Users & Activity page in Amperity.
To generate access tokens
|
|
Open the Users & Activity page. |
|
|
Under API keys find the API key for which you want to generate an access token, and then from the Actions menu select “Generate access token”.
|
|
Select the number of days this token will allow access to the API, after which it will expire. For example, 3 days: 
The token is generated, and then automatically copied to your clipboard. 
Important You are the only person who will have access to the newly-generated access key. Amperity does not save the access key anywhere and it will disappear when you close this dialog. Store the access key in a safe place. |
Add an index¶
An index must be defined for each query that is used to generate an endpoint for the Profile API.
To add an index for the Profile API
|
|
Open the Destinations page and click the Add Index button. This button is located to the right of the Real-time Profile API section header. This opens the Add Index dialog box. 
Give the endpoint a name that clearly describes how it will be used by downstream workflows. The name of an index must be unique and may not contain any of the following characters: Note The name of the index is informational only. Endpoints are listed alphabetically by name; endpoint names are not used within GET or POST requests. |
|
|
Select the query that will be used to generate the fields in the index, and then choose the field in that index that will be used as the lookup key. 
|
|
|
Choose the method by which the index will be generated (over time). There are two options: after a courier group run or manually. Choose None when setting up an index for the first time or for an index that requires asynchronous or infrequent regeneration. 
Tip After you have tested and validated downstream use cases for the index and have identified the frequency at which the index requires regeneration, you may switch from manual to running the index after the specified courier group has completed. The index will be regenerated at same frequency as the courier group run. For example: daily, weekly, or monthly. 
|
|
Save the index. Tip Enable the Generate index on save option to build the index immediately. 
If this save is for an initial test of the endpoint and contains only a small number of rows of data, the amount of time it can take to generate the index is measured in minutes. Use the LIMIT clause in the query to control the size of the index. Note A very large index that is generated for the first time can take a while (up to 6 hours). Please allow the index to finish generating before trying to access it from a downstream workflow. |
Generate the endpoint¶
There are three ways to generate the index, which makes it available as an endpoint in your tenant’s Profile API:
|
|
Generate on save.
|
|
|
Manually. Open the Actions menu for the index, and then select Run. 
Run does one of the following actions:
|
|
|
After courier group completes.
This option regenerates the index and refreshes the data that is available at that endpoint. This option is recommended for indexes that depend on upstream data refreshes and will ensure that the index is regenerated at the same frequency as the upstream data refresh. |
Copy the tenant ID¶
The GET indexes and POST indexes/{index-id} endpoints require the tenant ID to be in the URL for the request.
The tenant ID is available from the Real-time Profile API list. For the endpoint, open the actions menu, and then select “Copy tenant ID”.
Validate the endpoint¶
After the index has generated, validate the endpoint to verify that it is in the list of indexes, and then contains the data that is required by your real-time workflow.
The most direct way to validate the endpoints is to use cURL commands:
Run the GET indexes command to verify the index is in the list of indexes.
Run the POST indexes/{index-id} command to verify that a lookup key returns the correct list of attributes for that key.
Important
The steps to validate the endpoint may be different, depending on the downstream application or toolkit being used to enable your real-time use case. For example, Braze Connected Content has its own syntax (Liquid) for building the interface that interacts with the endpoint in your tenant’s Profile API.
Build into use cases¶
After you have verified that a specific endpoint is accessible and that it contains the data you expect it to contain, you can start building that endpoint into your real-time workflows. See the list of use cases for some ideas as starting points.
The Amperity real-time Profile API can be accessed using cURL, Postman, or any other mechanism that can access a REST API and provide the access token that is required by the request.
Use cases¶
The real-time Profile API can support an unlimited number of potential use cases. All you need to do is imagine the use case, identify the requirements for building that use case for your downstream workflow, and then build a query in Amperity that can be used to generate an index that contains the attributes you need to light up that use case.
The following sections describe some ways to use the Profile API:
Braze Connected Content¶
You can use the Profile API to make extended profile attributes available to Braze using Connected Content .
Important
Connected Content does not write data to user profiles, which means you can use Connected Content to dynamically populate values into messages without consuming data points.
Tip
You can verify the attributes that are returned by the Profile API endpoint directly in the Connected Content preview editor. Use a block similar to:
{% connected_content
https://app.amperity.com/attribute/v0/indexes/ix-aBCdeFgh?lookup-key={{${external_id}}}
%}
{{result text}}
This will return the set of attributes at the “/ix-aBCdeFgh” index for the specified “external_id”.
Braze uses a feature called Connected Content to define reusable blocks of message content that can then be used across a variety of marketing campaign scenarios.
|
|
Build an index that contains the list default user profile attributes, and then extend the profile to include more details from Amperity unified customer profiles. For example: loyalty ID and loyalty tier, predicted CLV tiers, and the rest of the customer profile (address, state, postal, and full name): SELECT
amperity_id AS external_id
,given_name AS first_name
,surname AS last_name
,full_name
,generational_suffix AS gs
,email
,phone
,address
,city AS home_city
,state
,postal
,country
,birthdate AS dob
,gender
,loyalty_id
,loyalty_tier
,loyalty_points
,pclv_tier
FROM Customer_360
|
|
|
Your Profile API access token is a JSON Web Token (JWT) that should be accessible from a safe location and not be embedded directly within your request. Use a “connected_content” block to get the access token, and then cache it with enough time to allow the next request to pull data from the index. In Braze Connected Content load the access token for the Profile API using a block similar to: {% connected_content
https://endpoint
:method post
:headers {
"Authorization": "Bearer refresh-token"
}
:cache_max_age 900
:save auth
%}
where “https://endpoint” is the URL at which the access token is located, and then “refresh-token” is the access token. |
|
|
After the access token is available to Connected Content, use the cached access token to access the index, specify a value for the lookup key (which in Braze is “external_id”), similar to: {% connected_content
https://app.amperity.com/attribute/v0/indexes/index-id
:method post
:headers {
"X-Amperity-Tenant": "tenant-id",
"Authorization": "Bearer {{auth.token}}"
}
:body key=external_id
:content_type application/json
:save result
%}
And then call the cached access token using |
|
|
Add values from the index using the following syntax: {{result.attributes.value.name}}
where “name” is the name of a field in the index: {{result.attributes.value.given_name}}
{{result.attributes.value.surname}}
{{result.attributes.value.phone}}
{{result.attributes.value.loyalty_id}}
{{result.attributes.value.loyalty_points}}
{{result.attributes.value.loyalty_tier}}
For example: Hello {{result.attributes.value.given_name}}. Your
{{result.attributes.value.loyalty_tier}} balance is:
{{result.attributes.value.loyalty_points}}
|
Hashed email profiles¶
A hashed email is an email address that has been encrypted with a hexadecimal string of numbers and letters. This creates a unique digital signature that is always the same even when that email address is used to log into different browsers, website, apps, and devices.
A hashed email
Is anonymous
Is not PII
Cannot be decrypted
Is browser- and device-independent
Enables multi-device, multi-browser, and multi-app tracking
Can be used to anonymously track users across websites, apps, and devices when the email address used to log into a website, app, or device matches the hashed email
and, most importantly, a hashed email can be used to associate a user to a unified customer profile from which your brand can build personalized real-time workflows.
Note
More than one algorithm may be used to hash an email address. Amperity assumes that SHA-256 is the algorithm used for hashing email addresses.
A real-time workflow that relies on hashed email addresses must use a consistent hashing algorithm at each point in the downstream real-time workflow.
Build a query that includes a hashed email address. For example:
SELECT
TO_HEX(SHA256(TO_UTF8(UPPER(TRIM(email))))) AS hashed_email
,given_name AS first_name
,surname AS last_name
,postal AS zip_code
FROM Merged_Customers
Use the hashed email address as the lookup key for the endpoint, generate the index, and then build real-time workflows that your brand can use to personalize website, app, and browser experiences for your customers.
Wireless access points¶
You can use hashed email addresses to associate unified customer profiles to the email addresses that may be used to log into wireless access points.
This use case uses a combination of Profile API endpoints:
An endpoint that contains a unified customer profile that uses a hashed email address as the lookup key.
An endpoint that contains wireless access points unique identifiers as the lookup key. For example, this endpoint could be built using a query similar to:
SELECT wireless_access_point_id ,location_ID ,location_name FROM Locations_Table
For example: A customer logs into the secure wireless that is offered by your hotel or resort using their email address.
A hashed version of that email address is built, and then is used as the lookup key for the endpoint in your Profile API that contains the hashed email profile. The unique ID for the wireless access point is used to look up the hotel or resort.
Use the Profile API to update the welcome screen. For example:
Thank you {{first_name}} for visiting {{location_name}}.
We hope you enjoy your stay.
This message could be extended to include promos or offers or any type of additional messaging your brand chooses.
Loyalty profiles¶
You can use loyalty IDs to personalize welcome messages for your customers after they log into your website.
Build a query that includes the unified customer profile data that your brand wants to use to personalize welcome messages. For example:
SELECT
,amperity_id
,mc.given_name AS first_name
,mc.surname AS last_name
,mc.birthdate
,lt.loyalty_id
,lt.loyalty_tier
,lt.loyalty_points_date
,lt.loyalty_points
FROM Merged_Customers mc
LEFT JOIN Loyalty_Table lt
ON mc.amperity_id = lt.amperity_id
Use the loyalty ID as the lookup key for the endpoint, generate the index, and then build real-time workflows that your brand can use to personalize your website for members of your loyalty program.
For example: A customer logs into your website using their loyalty ID, after which the loyalty ID can be used to look up an individual customer in your loyalty profile endpoint and be used to personalize their experience.
For example, a welcome message shown immediately after logging in:
Welcome back {{first_name}}.
Thank you for being a long-time member of our
{{loyalty_tier}} program.
As of {{loyalty_points_date}}, your loyalty points
total is: {{loyalty_points}}.
This message could be extended to include promos or offers or any type of additional messaging your brand chooses, such as extending the logic to include a message to customers whose birthday falls within the next 30 days:
Welcome back {{first_name}}.
{{ if birthdate = within the next 30 days }}
As a special thank you for being a long-time
member of our {{loyalty_tier}} program, here is
a {{discount_code_id}} discount code that you
may use on your next purchase: {{coupon_id}}.
{{ else }}
Thank you for being a long-time member of our
{{loyalty_tier}} program. As of
{{loyalty_points_date}}, your loyalty points
total is: {{loyalty_points}}.
{{ end }}
Server-side JavaScript in Salesforce¶
AMPscript is a scripting language used by Salesforce Marketing Cloud to render content on a subscriber-by-subscriber basis in real-time. Embed AMPscript variables within HTML emails, text emails, landing pages, SMS messages, and push notifications. These variables are updated at the time a message or notification is sent to (or a page is shown to) a subscriber.
Use Amperity unified customer profiles as values for variables defined by AMPscript. Use Server-Side JavaScript (SSJS) to return data from a Profile API endpoint, and then make that data available to AMPscript.
The following example shows how replace a variable with an email address from a Profile API endpoint just before sending a message.
Use AMPscript to return a value from the subscriber/data extension that is defined within the message template. For example, email:
%%[
SET @Email = email
]%%
Load the values from the Profile API endpoint using SSJS. This will make those values available to AMPscript variables:
<script runat="server">
Platform.Load("core", "1.1.1");
var email = Variable.GetValue("@Email");
//Set up Amperity Profile API call
var url = 'https://app.amperity.com/attribute/v0/indexes/$INDEX-ID';
var contentType = 'application/json';
var payload = '{"key":"' + email + '"}';
var names = ["X-Amperity-Tenant", "Authorization"];
var values = ["$tenant-id", "Bearer $ACCESS-TOKEN"];
var res = HTTP.Post(url, contentType, payload, names, values);
//Process results from Amperity Profile API call
var objResp = Platform.Function.ParseJSON(res.Response[0]);
Variable.SetValue("@AmperityID",objResp.attributes.value.amperity_id);
Variable.SetValue("@FirstName",objResp.attributes.value.firstname);
Variable.SetValue("@LastName",objResp.attributes.value.lastname);
Variable.SetValue("@LifetimeSpend",objResp.attributes.value.lifetimespend);
Variable.SetValue("@FavoriteBrand",objResp.attributes.value.favoritebrand);
Variable.SetValue("@LoyaltyPoints",objResp.attributes.value.loyaltypoints);
Variable.SetValue("@LoyaltyTier",objResp.attributes.value.loyaltytier);
</script>
Update the $INDEX-ID, $tenant-id, and $ACCESS-TOKEN placeholders for the correct index ID, tenant ID, and access token.
Use the Variable.SetValue("@$FIELD",objResp.attributes.value.$FIELD); function to declare the list of fields that are available to SSJS from the Profile API endpoint.