Ingest API

Description

The Encharge Ingest API lets you create/update people and submit events from your app's backend directly to Encharge. The API exposes a single endpoint.

See this documentation as a Postman Collection.

Don't use this API, if you are building an integration with Encharge to be used by our mutual customers. For example, if your product is a form builder and you'd like to send leads to Encharge, use the Rest API. The Ingest API is the wrong tool for the job and will result in poor experience for our mutual users.

Authentication

Get your write key for the Ingest API in Your Account.

Endpoints

Use the below endpoint to create/update people and submit events from your app's backend directly to Encharge. See below for sample events

/

POST https://ingest.encharge.io/v1/

Create/update person or record events for existing people.

Headers

Name	Type	Description
X-Encharge-Token	string	Write key for your account.
Content-Type	string	Content-type must be application/json

Request Body

Name	Type	Description
name	string	Name of your event. If you are using this API to create/update people, you can use "identify" as the event name.
user	object	Properties for the current user. email or userId is required to uniquely identify this person. Any other fields in properties will be added as custom fields to people.
properties	object	Properties for this event.
sourceIp	string	IP of the end user, if available.

200

Send date fields formatted as ISO 8601 datetime values. For example, 2020-10-27T07:58:19+00:00 or 2020-10-27T07:58:19Z.

Pass the IP of the user (as property ip in the user object) to automatically populate the user country and timezone. Alternatively, you might set the sourceIp as shown above.

You can pass comma-separated tags property in the user object to easily add tags to the user. For example: {"user": { "userId": 123, "tags": "tag1, tag2"}}

Sample Ingest API calls

Below you can find some samples on how to use the Ingest API. While these are using the curl script, you can import them into Postman to get sample snippets for your preferred language/lib.

User registered

A sample call to create the user upon registration. The event has properties describing the user's plan and trial.

curl --location --request POST 'https://ingest.encharge.io/v1' \
--header 'content-type: application/json' \
--header 'X-Encharge-Token: your-write-key' \
--data-raw '{
  "name": "Registered user",
  "user": {
  	"email": "[email protected]",
  	"userId": "1234567890",
  	"firstName": "Jon",
  	"lastName": "Snow"
  },
  "properties": {
	  "plan": "Premium",
    "trial": {
    	"startDate": "2020-03-06T14:24:03.522Z",
    	"length": 14
    }
  }
}'

Action taken

A sample call about an action that the user performed in your app (created a page). In this case, the user is identified with their userId and the event has no properties.

curl --location --request POST 'https://ingest.encharge.io/v1' \
--header 'content-type: application/json' \
--header 'X-Encharge-Token: your-write-key' \
--data-raw '{
  "name": "Created Page",
  "user": {
  	"userId": "1234567890"
  }
}'

Form submitted

A sample call to record a form submission by a user. The user email is supplied to identify the user and the properties are the form fields.

curl --location --request POST 'https://ingest.encharge.io/v1' \
--header 'content-type: application/json' \
--header 'X-Encharge-Token: your-write-key' \
--data-raw '{
  "name": "Form Submitted",
  "user": {
    "email": "[email protected]"
  },
  "properties": {
	  "Message": "Hello, I'd like to order some paper."
  }
}'

CORS issues with the Ingest API

Pass the write key in the URL instead as a header. For example:

https://ingest.encharge.io/v1/your-write-key

Alternatively, you can use the Javascript Event Tracking library.

Special Events

Encharge defines the following special events:

Alias

Use this event to change the userId and/or email of a user in your Encharge account.

Please note that you can provide both an email and a User Id.

The event has the following extra properties:

• type Should be set to "alias"

• previousEmail If changing the email address, the previous email of the user. Optional.

• user.email If changing the email address, the new email of the user. Optional.

• previousUserId If changing the User Id, the previous User Id. Optional.

• user.userId If changing the User Id, the new User Id. Optional.

Sample call:

curl --location --request POST 'https://ingest.encharge.io/v1' \
--header 'content-type: application/json' \
--header 'X-Encharge-Token: your-write-key' \
--data-raw '{
  "type": "alias",
  "previousUserId": "abc",
  "previousEmail": "[email protected]",
  "user": {
  	"userId": "123",
        "email": "[email protected]"
  }
}'

Group (Create/Update Custom Objects)

Create or Update a Custom Object (including Companies) in Encharge.

Additionally, if an Email or a User ID is provided, an Encharge user will be associated with the object. A new user will be created if the email or user ID does not exist in Encharge.

The event has the following extra properties:

• type Should be set to "group"

• objectType The name of the object to create/update (e.g. company). Make sure to create the object schema beforehand, either in the Encharge app or via the API.

• properties Dictionary of object fields to associate with the object in Encharge. Any unexisting fields will be ignored.

  • If you want to update an existing object in Encharge, make sure to pass id or externalId in the properties.

• user.userId If you want to associate the object with a user in Encharge, pass the User Id here. Optional.

• user.email If you want to associate the object with a user in Encharge, pass the user email here. Optional.

Sample call:

curl --location --request POST 'https://ingest.encharge.io/v1' \
--header 'content-type: application/json' \
--header 'X-Encharge-Token: your-write-key' \
--data-raw '{
  "type": "group",
  "objectType": "company",
  "properties": {
    "name": "House Stark",
    "externalId": "abc"
  },
  "user": {
  	"userId": "123",
        "email": "[email protected]"
  }
}'