REST API
Detailed technical documentation on the Lemnisk REST API to send your website or app data to your destinations via Lemnisk.
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
Step 1: Click on +Create New Source
Step 2: Select the source type as REST API and click Proceed
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.
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.
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 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.
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
REST Specification:
POST /data HTTP/1.1
Host: au-crux.lemnisk.coNon-AU Endpoint
https://crux.lemnisk.co/v3/data
REST Specification:
POST /v3/data HTTP/1.1
Host: crux.lemnisk.coHeaders 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 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:
properties
Object
Additional properties of event in the form of param:value
userid
String
User ID or anonymous ID for this event.
eventname
String
Name of the event.
type
String
Accepts either of the two values: “identify” or “track”.
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.
Response
Content-Type
The response body content type for each request (whether success or failure) will be application/json.
Status Code
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
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
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
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:
Make sure you follow the schema correctly. Sample schema is provided here.
Make sure to send the correct value for
srcidanduseridsince they are mandatory fields.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.
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
If you have an unanswered question or to know more about the Lemnisk REST API you can contact us.
Last updated