REST API

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

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.

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.

Image: Source- Rest API

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.co

Non-AU Endpoint

https://crux.lemnisk.co/v2/data

REST Specification:

POST /v2/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.

Maximum request 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.

Request payload

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:

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.

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.

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

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":"[e-mail]"
        },
        "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 [e-mail]", 
    "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:

1. Make sure you follow the schema correctly. Sample schema is provided here.
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.

Sample schema

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.