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/
/
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.
​
​
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]"
  }
}'
​
Last modified 1mo ago