Real Time API Guide

Overview

The LaunchPad Real-Time API (also known as LEAP – LaunchPad Enrichment & Append Protocol) enables clients to instantly enrich customer data using LiftBase, our proprietary database of demographics, lifestyles, and interests. By integrating LaunchPad directly into your tech stack, you can personalize customer experiences, enhance segmentation, and optimize marketing campaigns — all in real time.

IMPORTANT: The API does not support all third-party clients, such as cURL. Postman is supported. If this is an absolute requirement, please contact your Account Executive. Support coming soon.

Getting Started

Pre-Requisites

Your LaunchPad account executive will provide you with two key pieces of information:

Access Username (Access_Username): This will be included in your API URL when creating calls.
Access Secret (Access_Secret): Functions like an application secret and is required when generating authentication tokens.

Keep both credentials secure. They are unique to your organization and required for all API usage.

IP Range

To ensure that our firewall does not block calls, please communicate the expected IP ranges from which your team will be making calls.

US Records Only

If you wish to avoid additional costs, please only send to US-based consumers. LiftBase does not have international data.

Authentication (Request Token)

To use the API, you must first obtain an authentication token from the Identity Service.

Endpoint

https://identity.production.liftengine.io/v1/LEAP/<ACCESS_USERNAME>/token

Verb: POST

Payload (Form Post)

{
  "grant_type": "password", 
  "password": "<ACCESS_SECRET>",
  "scope": "openid"
}

Response Example (200 OK)

{
  "id": "some-id",
  "access_token": "<GENERATED_ACCESS_TOKEN>",
  "refresh_token": <GENERATED_REFRESH_TOKEN>",
  "expires_in": 300
}

Important

The access_token is required in the header of all LEAP calls.
An access_token expires after 5 minutes. Use the refresh_token with your Access_Username to request a new one.

Refreshing Tokens

When your token expires, use your Access_Username and refresh_token to request a new one:

https://identity.production.liftengine.io/v1/LEAP/<ACCESS_USERNAME>/token

Verb: POST

Payload (Form Post)

{
  "grant_type": "refresh_token", 
  "password": "<GENERATED_REFRESH_TOKEN>",
  "scope": "openid"
}

Response Example (200 OK)

{
  "id": "<SOME ID>",
  "access_token": "<NEWLY_GENERATED_ACCESS_TOKEN>",
  "refresh_token": <NEWLY_GENERATED_REFRESH_TOKEN>",
  "expires_in": <SECONDS_UNTIL_ACCESS_TOKEN_EXPIRES>
}

Running a Real-Time Job

Once authenticated, you can create a job to enrich data.

Package Code and Version: Your LaunchPad account executive will provide the correct <PACKAGE_CODE> and <VERSION> for your use case. These values determine which enrichment dataset is applied.
Subclient: This header is primarily used by agencies to indicate which of their clients the call is associated with. In some cases, it may be required for proper tracking and billing.

Endpoint

https://leap-realtime.production.liftengine.io/real-time/<ACCESS_USERNAME>/<PACKAGE_CODE>/<VERSION>

Verb: POST

Headers:

Authorization: Bearer <access_token>
Content-Type: application/json
Subclient: <subclient>

Payload (Raw JSON)

{
  "header": ["id", "full_name", "address_line_1", "city", "state", "zip_code"],
  "data": [
    ["1", "Jane Doe", "123 Main St", "Boston", "MA", "02118"],
    ["2", "John Smith", "456 Oak Ave", "New York", "NY", "10001"]
  ]
}

Please see the following section for details.

Request Body Structure

Each request body is composed of two main sections: header and data. These sections define both the structure of your input and the records you want to enrich.

header

The header is an array of column names that describe the data fields being submitted.
Each item in the header represents a field name corresponding to a specific type of customer attribute.

"header": ["id", "full_name", "address_line_1", "city", "state", "zip_code"]

Guidelines

The order of the fields in the header determines the order in which the data in each record is read.
Field names should be unique.
The header must include all required fields for enrichment.
Additional fields can be provided. They will be returned to you as written.

Required Headers

ID (optional but strongly recommended)
Full_Name
First_Name (only required if Full_Name is not provided)
Last_Name (only required if Full_Name is not provided)
Address_Line_1
Address_Line_2 (only required if Address_Line_1 does not contain all necessary street address information)
City
State (standard two-letter US state and territory abbreviations, only)
Zip_Code (five digits with leading zero, where applicable)
Email (only required for specific services and/or certain onboarding programs)

data

The data section contains the actual customer records. Each record is represented as an array of values that map to the fields defined in the header.

The number of elements in each record must match the number of fields in the header.

"data": [
  ["1", "Jane Doe", "123 Main St", "Boston", "MA", "02118"],
  ["2", "John Smith", "456 Oak Ave", "New York", "NY", "10001"]
]

In this example:

"1" maps to "id"
"Jane Doe" maps to "full_name"
"123 Main St" maps to "address_line_1", and so on.

Guidelines

Each record represents a single customer.
You may send between 1 and 250 records per request.
The more records included in a single call, the longer the response time will be.
If you are sending very large batches, consider breaking them into smaller chunks for optimal performance.

Complete Example

{
  "header": ["id", "full_name", "address_line_1", "city", "state", "zip_code"],
  "data": [
    ["1", "Jane Doe", "123 Main St", "Boston", "MA", "02118"],
    ["2", "John Smith", "456 Oak Ave", "New York", "NY", "10001"]
  ]
}

Response

{
  "job_id": "RT-YYYYMMDDHHSSMM-XXXXX",
  "data": [
    ["1","Jane Doe","123 Main St","Boston","MA","02118","22","Male","D","Married",""],
    ["2","John Smith","456 Oak Ave","New York","NY","10001","74","","5","Married","1"]
  ],
  "header": ["id","full_name","address_line_1","city","state","zip_code","Age","Gender","Income","Marital Status","Presence of Children"]
}

Each response is made up of three main sections. Together, they provide a full record of what was processed, the appended data results, and the schema defining the order of each field.

job_id – A unique identifier for the API call.
data – The data array contains the enriched customer records. Each sub-array corresponds directly to one record from the original request, preserving the same order. The difference is that each record now includes additional fields appended from your selected enrichment package.
header – The header in the response defines the complete schema of the returned dataset, including the original input fields submitted in the request and the appended enrichment fields provided by the system.

Notes

Empty strings ("") represent missing or unavailable data for that individual record.
Appended field values depend on your data package (e.g., demographic, lifestyle, or interest data).
Records always maintain a 1:1 relationship between request and response. The first record in the response corresponds to the first record in your original data submission.
Refer to the data dictionary provided by your account executive for a full list of potential values.

Available Packages

You can request a list of available enrichment packages and versions:

Endpoint

https://leap-realtime.prodiuction.liftengine.io/real-time/<ACCESS_USERNAME>

Verb: GET

Headers

Authorization: Bearer <access_token>

{
  "Outdoors01": ["f63c5446", "52ab4f4e"],
  "Sports01": ["f5c8f19c", "1a55f41a"]
}

Package names map directly to <PACKAGE_CODE> and <VERSION> used in job creation.

Best Practices

Credential Management: Keep your Access Username and Access Secret secure. Do not hardcode them in public code repositories.
Token Management: Always refresh tokens before expiry to avoid downtime.
Error Handling:
- 401 Unauthorized: Invalid or expired token, or incorrect credentials
- 400 Bad Request: Missing or invalid fields
Data Privacy: Ensure your use of enrichment data complies with your company’s privacy policy and all applicable regulations.

Support

Our team is here to help with setup and troubleshooting. Please contact your LaunchPad account manager or support team for assistance.

Real Time API Guide

Contents

Overview

Getting Started

Pre-Requisites

IP Range

US Records Only

Authentication (Request Token)

Refreshing Tokens

Running a Real-Time Job

Request Body Structure

header

Required Headers

data

Guidelines

Complete Example

Response

Notes

Available Packages

Best Practices

Support