---
description: >-
  Detailed technical documentation on the Lemnisk REST API to send your website
  or app data to your destinations via Lemnisk.
---

# REST API



{% hint style="info" %}
This document acts as a reference for the REST API documentation. Please ensure that you have an agreed-upon **Event Tracking Plan** from your Lemnisk Customer Success Point of Contact in conjunction with this document for the correct and complete implementation.
{% endhint %}

The Lemnisk REST tracking API works as a source for collecting data; you can use it to track your customer events across any web or mobile platform (Android and iOS). Whenever you make a call to an API, the request hits our servers where we route the data to one of the destinations configured for this source.

## Steps to configure REST API as Source

Go to -> **Data Pipeline** -> **Sources**&#x20;

**Step 1**: Click on **+Create New Source**

**Step 2:** Select the source type as REST API and click **Proceed**

<figure><img src="https://1782533751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FazJDZwzHkmWIbkYOetQH%2Fuploads%2FR6AKBJJtdJvrcQzlGTcR%2Fimage.png?alt=media&#x26;token=f4ebcabc-bc87-446d-8e74-8f6b2e304073" alt=""><figcaption></figcaption></figure>

**Step 3:** Set up the source

**Source name:** Add a unique name to the source and click the "Create" button.

## **Authentication**

Every API call must be authenticated with the respective `x-api-key` and `x-api-passkey` header. You can find these keys in the pop-up as shown in the note below.

{% hint style="info" %}
**Note:**

Copy the following API keys from the pop-up while creating the source.

Note: The `x-api-key` and `x-api-passkey` values will not be shown once you close the popup so ensure to copy the keys in a safe place.

![](https://1782533751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FazJDZwzHkmWIbkYOetQH%2Fuploads%2FjPOPRcdXBABda0dbN2oo%2Fimage.png?alt=media\&token=e28928d9-13d3-4413-961f-e4e33ff34e26)
{% endhint %}

If any of the values for these headers is malformed or not present, the request will fail with `401 Unauthorized` error.

## Test the Integration

To test the integration, configure the REST API credentials and click on "TEST". Send a request to the [endpoint](#endpoint) mentioned in the documentation if we receive the request successfully, a success message will be shown indicating successful source configuration.

**Payload:** The correct format for the payload to send events will be displayed here. You can copy the payload and use it while sending API requests.

<figure><img src="https://1782533751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FazJDZwzHkmWIbkYOetQH%2Fuploads%2Fvv3dOTfjsUy6jwD877gL%2FHTTP.png?alt=media&#x26;token=c4853691-5f97-43bd-8e69-ffb279ed84ea" alt=""><figcaption><p><em>Image: Source- Rest API</em></p></figcaption></figure>

## **Making a Request**

### Supported event types

The REST API source only supports `identify` and `track` event types.

### Supported HTTP  methods

The REST API supports `POST` and `DELETE` methods. `POST` is used to create or update a profile at Lemnisk. `DELETE` is used to delete an object from the user profile or delete the profile entirely.

### **Endpoint**

**Australia (AU) Endpoint**

[https://au-crux.lemnisk.co/data](https://au-crux.lemnisk.co/data)

REST Specification:

```
POST /data HTTP/1.1
Host: au-crux.lemnisk.co
```

**Non-AU Endpoint**

[https://crux.lemnisk.co/v3/data](https://crux.lemnisk.co/v2/data)

REST Specification:

```
POST /v3/data HTTP/1.1
Host: crux.lemnisk.co
```

### **Headers and Authentication**

You need to pass `x-api-key` and `x-api-passkey` in the headers.

### **Limits**

#### **Maximum Payload Size**

The REST API allows a maximum of `500KB` size per call. If these limits are exceeded, the API will respond with a `400 Bad Request`.

#### **Rate Limit**

The REST API ingests at _`40 requests per second`_. You would receive a 429 HTTP Status code if you exceed that.

### **Request payload** <a href="#httpapi-2.5requestpayload" id="httpapi-2.5requestpayload"></a>

{% tabs %}
{% tab title="POST Request" %}
A sample payload for ingesting 1 record is given below.

```
{
    "properties": {
        "param1": "data1",
        "param2": "data2",
        "param3": "data3",
        "paramX": "datax",
        "email": "<email of the user>",
        "mobile": <mobile of the user>"
    },
    "userid": "CXOOOOOO",
    "eventname": "event name",
    "type": "identify/track"
}
```

The parameter definition for accepted fields is provided below:

<table data-header-hidden><thead><tr><th>Parameter</th><th width="188.66666666666669">Type</th><th>Description</th></tr></thead><tbody><tr><td><em>properties</em></td><td>Object</td><td>Additional properties of event in the form of <code>param:value</code></td></tr><tr><td><em>userid</em></td><td>String</td><td>User ID or anonymous ID for this event.</td></tr><tr><td><em>eventname</em></td><td>String</td><td>Name of the event.</td></tr><tr><td><em>type</em></td><td>String</td><td>Accepts either of the two values: “identify” or “track”.</td></tr></tbody></table>

To send PII data, please add `email` and `mobile` to the `properties` block. Ensure that the email is in lowercase and the mobile number follows the [E.164 format](https://en.wikipedia.org/wiki/E.164).
{% endtab %}

{% tab title="DELETE Request" %}
A sample payload to delete 3 records is given below:

```
[
    {
        "properties": {
            "id":"someid to identify this object"
        },
        "object":"Segment"
    },
    {
        "properties": {
            "id":"someid to identify this object"
        },
        "object":"Lead"
    },
    {
        "properties": {
            "id":"someid to identify this object"
        },
        "object":"__profile"
    }
]
```

**Points to consider while sending a `DELETE` request:**

1. `object` parameter is used to identify which object to delete from the user profile. If you're using Salesforce CRM or Microsoft Dynamics 365 CRM to send data to Lemnisk, you can use the `object` parameter to specify which object/entity (Lead, Segment etc.) to be delete from the profile.
2. If you want to delete the entire profile from the CDP, send `__profile` in the `object` param.
3. The `id` param should contain the user profile id to uniquely identify a user.
{% endtab %}
{% endtabs %}

## **Response** <a href="#httpapi-3.response" id="httpapi-3.response"></a>

### Content-Type <a href="#httpapi-3.1content-type" id="httpapi-3.1content-type"></a>

The response body content type for each request (whether success or failure) will be `application/json`.

### Status Code <a href="#httpapi-3.2statuscode" id="httpapi-3.2statuscode"></a>

| **Code**                    | **Reason**                                                                |
| --------------------------- | ------------------------------------------------------------------------- |
| `200 Success`               | Data Processed successfully                                               |
| `401 Unauthorized`          | api-key/api-passkey passed in the request headers is missing or incorrect |
| `400 Bad Request`           | Incorrect request payload structure                                       |
| `500 Internal server error` | Some error in processing                                                  |
| `429 Too Many Requests`     | Client exceeded the rate limit for the endpoint.                          |

### Parameter Definition <a href="#httpapi-3.3parameterdefinition" id="httpapi-3.3parameterdefinition"></a>

The response structure consists of a JSON array with two keys - `id` and `message`. The response will provide the status of each record in the request payload. Accordingly, if a call consists of 4 records, then the response will consist of an array of 4 JSON objects.

| **Parameter** | **Type** | **Description**                                             |
| ------------- | -------- | ----------------------------------------------------------- |
| _`message`_   | Object   | Additional properties of event in the form of `param:value` |
| _`id`_        | String   | User ID or anonymous ID for this event                      |

### Sample Request and Response <a href="#httpapi-3.4samplerequestandresponse" id="httpapi-3.4samplerequestandresponse"></a>

**POST request**

Request:

```
curl -L -X POST 'https://crux.lemnisk.co/v2/data' -H 'Content-Type: application/json' -H 'x-api-key: 3u3y6UlyDz3qa7nKB6Rv28jOPf0MmoLj4eiTQAI2' -H 'x-api-passkey: IYTNvUQAxYsITFcbY' --data-raw '[
    {
        "properties": {
            "city": "",
            "referralKey": "",
            "source": "hdfc",
            "landingPageId": "",
            "medium": "offline"
        },
        "userid": "CXOOOOOO",
        "eventname": "Request Blue Credit Card Information",
        "type": "track",
        "srcid": "1"
    },
    {
        "properties": {
            "city": "",
            "referralKey": "",
            "source": "hdfc",
            "landingPageId": "",
            "medium": "offline"
        },
        "userid": "",
        "eventname": "Opened Bank Account",
        "type": "track",
        "srcid": "1"
    },
    {
        "properties": {
            "city": "",
            "referralKey": "",
            "source": "Facebook",
            "landingPageId": "",
            "medium": "online"
        },
        "userid": "CXOOOOO2",
        "eventname": "Clicked on Ad",
        "type": "track",
        "srcid": "2"
    }
]'
```

Response:

```
[
    {
    "message": "Data Processed successfully", 
    "id": "2510c39011c5be704182423e3a695e91"
    },
    {
    "message": "Invalid input request. Incorrect userid.", 
    "id": ""
    },
    {
    "message": "Data Processed successfully", 
    "id": "2510c39011c5be704182423e3a695e93"
    }
]
```

**DELETE Request**

Request:

```
curl --location --request DELETE 'https://crux.lemnisk.co/v3/data' \
--header 'Content-Type: application/json' \
--header 'x-api-key: xxxx' \
--header 'x-api-passkey: xxxx' \
--data-raw '[
    {
        "properties": {
            "id":"23423"
        },
        "object":"Segment"
    },
    {
        "properties": {
            "id":"67541"
        },
        "object":"Lead"
    },
    {
        "properties": {
            "email":"john.doe@xyz.com"
        },
        "object":"__profile"
    }
]'
```

Response:

```
[
    {
    "message": "Segment object deleted from user profile successfully.", 
    "id": "2510c39011c5be704182423e3a695e91"
    },
    {
    "message": "Lead object deleted from user profile successfully.", 
    "id": "2510c39011c5be704182423e3a69345"
    },
    {
    "message": "User Profile not found with email as john.doe@xyz.com", 
    "id": ""
    }
]
```

## **FAQs** <a href="#httpapi-4.faqs" id="httpapi-4.faqs"></a>

This section will find answers to most of your questions and solutions to some of the most common problems you may encounter while using the Lemnisk REST API.

**Q1. Which event types are supported with the Lemnisk** REST **API?**

The Lemnisk REST API supports `identify` and `track` events.

**Q2. I am receiving** `400 Bad Request` **repeatedly. What should I do?**

`400 Bad Request` error means that there is something wrong with the request payload. Follow the below steps to make sure your payload is correct:

1. Make sure you follow the schema correctly. Sample schema is provided [here](https://vizury.atlassian.net/wiki/spaces/~440270343/pages/2496430085/HTTP+API#2.5-Request-payload).
2. Make sure to send the correct value for `srcid` and `userid` since they are **mandatory** fields.
3. Validate your JSON before making an API call. In Postman, you can easily spot the errors with a red line and a red spot in the scroll bar. Take a look at the picture below for reference.

<figure><img src="https://1782533751-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FazJDZwzHkmWIbkYOetQH%2Fuploads%2FMYwmTjnp0KiNnwtckgy0%2FFAQ%20HTTP.png?alt=media&#x26;token=ed029653-61c6-43b7-b10a-af2a29c0e06e" alt=""><figcaption><p><em>Sample schema</em> </p></figcaption></figure>

&#x20;  4\. If the error persists, please contact us.

**Q3. How do I get the `x-api-key` and the `x-api-pass-key` ?**

You can view the x-api-key and x-api-passkey while creating the REST API source.

## **Contact Us** <a href="#httpapi-5.contactus" id="httpapi-5.contactus"></a>

If you have an unanswered question or to know more about the Lemnisk REST API you can[ contact us.](https://www.lemnisk.co/contactus/)
