ConveYour API

Developers! If you are trying to synch your roster of employees or reps with ConveYour - we offer information and a quick Tour Guide on working with ConveYour API here.

To get started with integrations, get the Appkey and Token from Settings > Integrations > Analytics (see screenshot below in "Credentials")

Any custom integrations that you may need, but you can't find the information in the Tour Guide please reach out to us.

REST API

The ConveYour Analytics REST API is the lower-level HTTP API used in ConveYour's Analytics.js library and the ConveYour-WP Wordpress plugin.

What is it?

You use this API to add and update contacts in your ConveYour as well as record events that relate to a contact.
The API consists of two methods, identify and track.
It's a subset of ConveYour's larger REST API.

Identify API Call

Use the identify method to add/update contacts, users, or employees in your ConveYour account.
Learn More Here >>

Use cases

Sync your corporate employee data with ConveYour.

This is an incredibly valuable feature for your company. Your company can sync virtually any employee data point to ConveYour and then use that data to segment employees or automate the delivery of messages. For example, you could send sales promotion levels to ConveYour for each employee and then setup automate SMS messages to congratulate them when they reach a certain sales level.

Here are some great examples of company employee data that could be synced to ConveYour.

Obviously names, email, mobile
Career sales numbers
Started Date
Birthday
Weekly, Monthly, Quarterly performance numbers
Region, division, location.
Name of direct report

Sync your membership site or app users with ConveYour.

ConveYour is the perfect tool for managing and engaging with the users in your membership site or app. You can send targeted, timely SMS & email messages (with video) to your users based on their current user state.

Here are some great examples of how you can use the data on your users to create better engagement in your membership site or app.

Automatically track when a user was "last seen".
Automate SMS messages thanking users for upgrading to X plan.
Segment and engage with your highest LTV clients.
Offer a pricing plan level that allows them to receive ConveYour video messages from you on a weekly basis.

Track Method

Use the track method to record events on a given contact in ConveYour.

Let's say you have a contact, Jill, in ConveYour. Jill is part of your sales team and you want to keep a running tab of when she makes a sale and for how much. Maybe you want to send her a congratulatory text message when she hits 10 sales for the week.

You could do this by sending ConveYour an event through the track method.

Each event you send to ConveYour consists of a verb-based event name and some properties to give the event some fidelity.

Based on our Jill scenario.. Our event might look like this..

event : made_sale properties amount : 1000 customer : John Doe

Credentials

Step 1. Get your API Keys.

Go to Settings > Integrations, and click on Analytics:

settings > integrations

Step 2. Copy your domain, App Key, and Token over to your code project.

app key and token

or integrate Javascript on your site page:

copy javascript

Step 3. Site setup..

Identify Examples

Raw HTTP Example

POST /api/analytics/identify 
Host: subdomain.conveyour.com
x-conveyour-appkey: REDACTED
x-conveyour-token: REDACTED
Content-Type: application/json
Accept: application/json

{
  "id": "[email protected]",
  "traits": {
    "first_name": "Stephen",
    "last_name": "Rhyne",
    "career_sales": 500000,
    "tags": {
      "remove": [
        "tag1"
      ],
      "add": [
        "tag2"
      ]
    },
    "counter": {
      "$inc": 2
    }
  }
}

Passing Traits

To match up trait keys with existing fields in ConveYour, make sure to use your field's underlying name. You can get the underlying field name from a field's context menu in your settings.
Settings > Fields

Learn more about ConveYour fields located in settings >>

You can pass new traits that have not been added to ConveYour yet! However, we suggest creating the field first in settings/fields. (learn more from article linked above) Creating the field ahead of time let's you set the desired field format of text, number, date, list, etc. Note: if you do send new fields "on-the-fly" we will do our best to infer what type the field should be.

Updating List Fields

The tags field in ConveYour is of type list. You can make your own list fields as well.

Add or remove values on an existing list like this..

{
  "tags": {
    "remove": [
      "tag1"
    ],
    "add": [
      "tag2"
    ]
  }
}

You can also increment an integer field value with..

{"counter" : { "$inc" : 1 } }

Identify Multiple Contacts in One HTTP Call

You can mass add/update many contacts in ConveYour efficiently by passing us an array of identification objects (vs a single object).

Example...

[
  {
    "id": "20432766",
    "traits": {
      "first_name": "Jackie",
      "last_name": "McDaniels",
      "career_sales": 125000
    }
  },
  {
    "id": "20432721",
    "traits": {
      "first_name": "Charlie",
      "last_name": "Wilson",
      "career_sales": 50000
    }
  }
]

IMPORTANT!

Make sure the properties.id value matches the id you use to identify contacts otherwise ConveYour will have no way to match events to a stored contact.

Keep your data manageable and actionable by limiting the number of properties you include in your event objects. Send only the data you need, please. We block storing event objects with more than 15 key/value pairs. Try to reuse property keys as often as you can. If you need help planning your analytics, please get in touch with us.

Track Examples

cURL Example

curl -X POST \
-H "x-conveyour-appkey: REDACTED" \
-H "x-conveyour-token: REDACTED" \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Cache-Control: no-cache" \
-d '{"id" : "20432766","events" : [{"event" : "purchased_item","properties" : {"amt" : 39}}]}' 
"https://subdomain.conveyour.com/api/analytics/track"