Personas API

Endpoints:


Get all personas

Description: Returns all personas / contact ID’s within your account.
Endpoint: (GET) /piis/:uid?{params}
Params:

  • start [number, default 0]: pagination start.
  • limit [number, default 20, max 100]: max number of contacts returned from start.
  • search [string, optional]: search personas for the given keyword, supports pagination.
  • aus [param, optional]: see all personas belonging to one or more audience ID’s. /piis/:uid?aus=123,3213 <- would get you all personas in audiences 123 and 3213. Leaving this param blank will get all personas.

Example Request: GET /piis/420?start=80&limit=20

Response body:

{
  "data": {
    "results": [
      {
        "contactID": "560863a606982016ede3e68a0515afa2",
        "srcID": "f5b65153-4578-4fc2-824e-89b0425aacf2",
        "firstName": "Elon",
        "lastName": "Musk",
        "mobilePhone": "8881110000",
        "platform": "cova",
        "favoriteStoreID": null,
        "inserted": 1594598213,
        "optinTime": 1594598213,
        "optoutTime": null,
        "optreqTime": 1594598113,
        "hasRequested": null
      },
      ...
    ],
    "start": 80,
    "total": 18909,
    "limit": 20,
    "size": 20
  },
}
FieldTypeDescription
contactIDstringThe Alpine IQ unique identifier for the contactID
srcIDstringUnique ID the data source (Treez, S3, etc.) has for this contactID
firstNamestringFirst name of contactID
lastNamestringLast name of contactID
mobilePhonestringThe mobile phone number
homePhonestringThe home phone number
platformstringThe source where Alpine gathered this contact (Treez, Cova, Flat file, Loyalty, etc)
favoriteStoreIDINTThe Alpine IQ store ID the contact has set as their favorite
insertedEpochWhen the contact data was inserted into the Alpine IQ big query database (Compliance)
optinTimeEpochWhen the contactID opted in
optoutTimeEpochWhen the contactID opted out
optreqTimeEpochWhen the contactID was sent an an SMS member club optin request
hasRequestedBoolWhether or not the contactID has been sent a request to optin to SMS but has yet to respond (Pending optin request)

Add a single persona to loyalty/ member club

Description: Creates a new loyalty or member club persona. Adding this user will instantly text the phone number for the contact and request a confirmation for optin to loyalty/ club SMS.
Endpoint: (POST) /loyaltyContact/:uid

 {
    firstName: '',
    lastName: '',
    mobilePhone: '',
    email: '',
    address: '',
    favoriteStore: '',
    favoriteStoreID: 1,
}
firstNamestringFirst name of customer
lastNamestringLast name of customer
mobilePhonestringPhone for customer (SMS will be sent here)
emailstringEmail for customer
addressstringAddress of customer (can be full address or just zip code)
favoriteStorestringLeave as empty string or pass the store name if known.
favoriteStoreIDintShould map to an existing store ID based on store locations from: https://docs.alpineiq.com/rest-api-home/store-locations-api/#getAllPersonas

Get personas traits

Description: Returns a little bit more info about a single contact.
Endpoint: (GET) /piis/:uid/:contactID

Response body:

{
  "data": {
    "contactID": "89f2716dbc6326163946cbd14079edf0",
    "srcID": "10666",
    "firstName": "Luci",
    "lastName": "Ball",
    "email": "nick@something.com",
    "homePhone": "1112223333",
    "mobilePhone": "8889992222",
    "platform": "treez",
    "favoriteStoreID": null,
    "signedUp": 1594072778,
    "firstSeen": 1546072778,
    "wallet": "https://lab.alpineiq.com/linkToWalletForPersona",
    "addr": {
      "city": "Santa Clarita",
      "country": "US",
      "zipCode": "81612",
      "state": "CA",
      "street": "15011 StarVenture Dr",
      "lat": 23.94903,
      "long": -120.393
    },
    "actions": [
      {
        "label": "text_received",
        "timestamp": 1595347658,
        "platform": "sms campaign",
        "cmpID": "1052",
        "discID": null
      },
      {
        "label": "text_received",
        "timestamp": 1595364266,
        "platform": "sms campaign",
        "cmpID": "1221",
        "discID": null
      }
    ],
    "inserted": 1596509600,
    "loyalty": true,
    "loyaltySignupTS": 1595295167,
    "browser": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_4) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.1.1 Safari/605.1.15",
    "ip": "53.494.938.93",
    "ageGate": true,
    "optinTime": 1594598113,
    "optoutTime": 1594598113,
    "optreqTime": 1594598113,
    "hasRequested": true,
    "gender": "U",
    "lastSeen": 1594598113
  },
}
FieldTypeDescription
contactIDstringThe Alpine IQ unique identifier for the contactID
srcIDstringUnique ID the data source (Treez, S3, etc.) has for this contactID
firstNamestringFirst name of contactID
lastNamestringLast name of contactID
emailstringThe contacts email
mobilePhonestringMobile phone number
homePhonestringHome phone number
platformstringThe source where Alpine gathered this contact (Treez, Cova, Flat file, Loyalty, etc)
favoriteStoreIDstringThe Alpine IQ store ID the contact has set as their favorite
signedUpepochTime they signed up with your brand. This can pre-date Alpine services
firstSeenepochThe first time Alpine saw this user
lastSeenepochThe last time when Alpine saw an interaction from this user
addrobjAddress for the contact. Lat + Long are appended/ updated by Alpine IQ if a new address is found.
ipstringThe IP for this contact.
actionsobjAny campaigns or actions from 3rd party platforms we are tracking (I.E: When mailchimp sends an email or when Alpine sends an SMS)
insertedEpochWhen the contact data was inserted into the Alpine IQ big query database (Compliance)
loyaltyboolWhether or not they are still part of your member club
loyaltySignupTSEpochTime they signed up for loyalty program/ member club
ageGateboolWhether or not this contact has passed an age gate of anykind
optinTimeEpochWhen the contactID opted in
optoutTimeEpochWhen the contactID opted out
optreqTimeEpochWhen the contactID was sent an an SMS member club optin request
hasRequestedBoolWhether or not the contactID has been sent a request to optin to SMS but has yet to respond (Pending optin request)
genderstringU = unknown otherwise you will get M or F for gender.

Get personas orders

Description: Returns all orders made by a contactID.
Endpoint: (GET) /contact/orders/:uid/:contactID

Response body:

{
  "data": [
    {
      "sku": "4JDQSBG5",
      "productId": "3a550156-46cf-4271-b547-22aa1d4189f8",
      "category": "Sativa Pre-Roll",
      "parentCategory": "Pre-rolls",
      "name": "Tantalus Labs - Sky Pilot - Hybrid - PreRoll - 3 x 0.5g",
      "quantity": 1,
      "timestamp": 1592015580,
      "totalCost": 13.48,
      "totalPrice": 22.79,
      "customAttributes": null
    },
    {
      "sku": "4JDQSBG5",
      "productId": "3a550156-46cf-4a91-93ae-d36ef5049445",
      "category": "510 catridges",
      "parentCategory": "Vapes",
      "name": "Kolab - Project Kolab - Vape Cartridge - Indica - 0.5g",
      "quantity": 1,
      "timestamp": 1592015580,
      "totalCost": 32.94,
      "totalPrice": 52.21,
      "customAttributes": null
    }
  ],
  "code": 200,
  "success": true
}
FieldTypeDescription
skustringSKU for this product
productIdstringProduct ID provided by POS system in most cases.
categorystringCategory of the product
parentCategorystringParent category for the product
namestringName of product
quantityINTQuantity purchased
timestampepochTimestamp of order
totalCostfloatCost to retailer
totalPricefloatTotal checkout price
customAttributesobjCustom attributes for this product set by the POS in most cases

Get personas predicted top products

Description: Returns most likely products a contact will be interested in ranked in order.
Endpoint: (GET) /contact/rankings/:uid/:contactID

Response body:

{
  "data": [
    {
      "SKU": "DZJURKZT",
      "ProductName": "Canaca - Blend 14% - Blend - Pre-Roll - 3 x 0.5g",
      "Brand": "",
      "Category": "3. Pre-Roll"
    },
    {
      "SKU": "0Q62Y5GJ",
      "ProductName": "Twd. - Sativa - Preroll - 1x1g",
      "Brand": "",
      "Category": "3. Pre-Roll"
    },
  ]
}
FieldTypeDescription
SKUstringSKU for this product
ProductNamestringAlpine ID for this product
CategorystringCategory of the product
BrandstringBrand name