Identify

Identify your customers to Mantle so it can automatically enrich customer data and perform actions via third party platforms such as Shopify or Stripe. This is done by providing Mantle with details of the merchant from your app’s hosted platform to the /identify endpoint.

When building a typical Shopify app and interacting with the Shopify API, you will create an access_token for each merchant who installs your app. This access_token can be acquired after the Shopify OAuth process has completed. More details can be found in the documentation of Shopify’s GraphQL Authentication.

POST https://appapi.heymantle.com/v1/identify

POST `/v1/identify`

Identify your customer to Mantle.

Header parameters

X-Mantle-App-Idstring

The App Id when you create an API key in your Mantle dashboard.

X-Mantle-App-Api-Keystring

The API key found in the Mantle dashboard. This is used to identify your users to Mantle and should be kept secret, and used only in server-side code.

Body parameters

platformstring

Platform name, such as “shopify” or “stripe”

platformIdstring

Customer ID on the platform, this is the Shopify Shop ID or Stripe customer ID

myshopifyDomainstring

If platform is shopify, this is the unique myshopify.com domain for the shop

namestring

Customer name

emailstring

Customer email

platformPlanNamestring

The name of the plan on the platform, only applicable for Shopify. This field will be populated automatically if an access_token is provided.

customFields<string,object>

Key-value pairs of custom fields to store on the customer.

accessTokenstring

Customer access token for the platform API - The access token obtained from authenticating with your customer.

createdAtdate

Date the customer was created or first seen. Defaults to now if not provided.

curl --request POST \
  --url https://appapi.heymantle.com/v1/identify \
  --header 'X-Mantle-App-Api-Key: string' \
  --header 'X-Mantle-App-Id: string' \
  --header 'Content-Type: application/json' \
  --data '
{
  "platform": "shopify",
  "platformId": "123456",
  "myshopifyDomain": "testshop.myshopify.com",
  "name": "testshop",
  "email": "[email protected]",
  "accessToken": "shpat_1234567890"
}
'

While setting custom fields for your customer:

curl --request POST \
  --url https://appapi.heymantle.com/v1/identify \
  --header 'X-Mantle-App-Api-Key: string' \
  --header 'X-Mantle-App-Id: string' \
  --header 'Content-Type: application/json' \
  --data '
{
  "platform": "shopify",
  "platformId": "123456",
  "myshopifyDomain": "testshop.myshopify.com",
  "name": "testshop",
  "email": "[email protected]",
  "accessToken": "shpat_1234567890",
  // Add custom field parameters
  "customFields": {
    "custom1": "value1",
    "custom2": "value2"
  }
}
'

Example response

{
  "apiToken": "e7cb87da-37db-4466-ada0-a67babdf45da"
}

On a successful response, you’ll receive an apiToken. This token is necessary for making queries to other Mantle endpoints. Store it in the database of the app’s shop model alongside the Shopify access token (if applicable), as this will be used by future requests to the Mantle API.