# 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](https://documenter.getpostman.com/view/460427/SVfNwVFU).
{% hint style="danger" %}
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](https://docs.encharge.io/api-documentation#rest-api). The Ingest API is the wrong tool for the job and will result in poor experience for our mutual users.
{% endhint %}
### Authentication
Get your write key for the Ingest API in [Your Account](https://app.encharge.io/account/info).
### 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. |
{% tabs %}
{% tab title="200 " %}
```
```
{% endtab %}
{% endtabs %}
{% hint style="info" %}
Send date fields formatted as ISO 8601 datetime values. For example, `2020-10-27T07:58:19+00:00` or `2020-10-27T07:58:19Z`.
{% endhint %}
{% hint style="info" %}
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.
{% endhint %}
{% hint style="info" %}
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"}}`
{% endhint %}
### 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": "jonsnow@thenorthremembers.com",
"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": "michael@michael-scott-paper-company.com"
},
"properties": {
"Message": "Hello, I'd like to order some paper."
}
}'
```
{% hint style="info" %}
**CORS issues with the Ingest API**
Pass the write key in the URL instead as a header. For example:
Alternatively, you can use the [Javascript Event Tracking](https://docs.encharge.io/getting-started/connecting-your-app-to-encharge/javascript-event-tracking) library.
{% endhint %}
### 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": "jon@snow.com",
"user": {
"userId": "123",
"email": "aegon@targaryen.com"
}
}'
```
#### 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": "jon@snow.com"
}
}'
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.encharge.io/getting-started/connecting-your-app-to-encharge/ingest-api.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.