This page will help you get started with the Audience API.

📘

Beta

This product is currently in Beta. Contact your account manager for details.

Leverage Simon’s contact profiles to power a more targeted, personalized experience everywhere you already reach your customers.

Through the use of contact profile data, marketers can retrieve a user's information, like a contact’s name, campaigns received, journey membership — and more — to customize the content provided to that user. This information can be used to power one-off experiences or to power your personalization service. Some examples include:

  • Use the Audience API to personalize the content or product recommendations served to a customer based on unique customer profile information (i.e. total spend, location, or last purchase date)
  • Enable a customer service or front-of-house staff member to have better context on a customer by embedding customer profile information in your internal tools

Authentication

The Audience API uses Bearer Authentication, or token authentication, to manage access. To request a bearer token, contact your Client Solutions Manager. The bearer token should be provided in the header of each request, e.g.

-H "Authorization: Bearer <YOUR TOKEN>"

Keep your tokens safe. It's recommended that you store your token in a password manager or secrets store; like 1Password or Vault.

Token rotation or deletion

Please reach out to the Customer Success team if you would like for a token to be rotated or deleted. Please avoid sending any tokens via email or slack to ensure they stay secure - you can reference them by their last 3 digits, or the email used to create them.


Make a Request

Once you have received your bearer token, make a test request to the API to confirm that everything is up and running. In the script below, replace <YOUR_BEARER_TOKEN> with the token received, and replace <CONTACT_EMAIL_ADDRESS> with the email of a contact in your Simon account that you'd like to fetch.

curl -X GET -H 'Accept: application/json' -H "Authorization: Bearer <YOUR_API_TOKEN>" 'https://api.simondata.com/audience/v2/contacts?identity=email:<CONTACT_EMAIL_ADDRESS>'

The Contact Object

A successful response contains a Contact object, with key-value pairs containing the contact's properties. It's important to note that only one Contact object can be returned at a time. The keys available in the response are based on the fields configured within your Simon account. In order for a field to appear in the API response, it must be configured as "content" in your Simon account. To read more about content fields, see here.

{
  "email_address": "[email protected]",
  "first_name": "Tom",
  "address_city": "New York",
  "address_state": "NY",
  "flow_variant_membership": [
    "142309",
    "203850-Variant A",
  ],
  "total_lifetime_value_jde": "$241.56"
}

Errors

Simon uses conventional HTTP response codes to indicate the success or failure of an API request. For example, a 404 would indicate that the requested customer identifier does not exist. See more on the endpoint reference.

Code

Status

Description

200

OK

Request sent successfully

400

Bad Request

This may occur because the requested contact does not exist.

403

Forbidden

429

Rate Limited

Request frequency too high. See Rate Limit for more details.

500

Server Error

The request was not completed due to an internal server error.


Rate Limit

There is a limit of 50 requests/second that is applied across all requests made by your organization. This means that the rate limit will apply to all requests coming from your organization, even if they are issued with separate bearer tokens. If you need a rate limit increase, please contact your account manager with your request and use case details.