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.

Authentication

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

Endpoints

post
/

https://ingest.encharge.io/v1/
Create/update person or record events for existing people.
Request
Response
Request
Headers
X-Encharge-Token
required
string
Write key for your account.
Content-Type
required
string
Content-type must be application/json
Body Parameters
name
required
string
Name of your event. If you are using this API to create/update people, you can use "identify" as the event name.
user
required
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
optional
object
Properties for this event.
sourceIp
optional
string
IP of the end user, if available.
Response
200: OK

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."
}
}'