Leadspace offers an enrichment service through its API. This article presents the technical specifications and requirements in order to send enrichment request to Leadspace using Single API requests.

Setup

As part of the setup process, Leadspace provides an API key (bearer token) and a program ID. This key authenticates the program: A given customer may hold multiple unique API keys, one for each program.

Please store the API key and the program ID in a secure manner. The bearer token is the key used for the programming, but the Program ID can be helpful when troubleshooting with Leadspace. It is our recommendation to add the program ID as a comment in your code.

Transport

All API calls are done by using HTTPS protocol.

Encoding

Most of the requests and responses are textual, with UTF-8 encoding for Unicode based text.

Data format

The data format for API calls is JSON (as defined in RFC 7159). All requests made to Leadspace must be in a valid JSON format. Dates and timestamps, when present, are represented in ISO 8601 format, in UTC.

Example: 2015-05-03T15:38:45Z

Endpoint

Base URL is: 

https://apigw.leadspace.com

All other endpoints in this document, unless explicitly stated otherwise, are relative to the base URL above.

Authentication

All requests to Leadspace's API should include the standard HTTP Authorization header. The Authorization header should be set in the following format:

'Authorization':'Bearer API_KEY’

The username (program ID) and the secret (token\API_KEY) will be provided to the user via email.

Leadspace offers two authentication methods:

1. Perpetual token
2. Oauth 2.0

Perpetual Token Rotation

1. Due to security reasons, it is highly recommended to replace the API perpetual token every six months, starting from the completion of the integration period (or, “token lifecycle”). If the perpetual token is not rotated, it will expire after a period of 2 years after is is generated and sent to you.
2. Leadspace will generate a new token and provide it by an email.
3. Leadspace will send a notification before the end of the token life cycle that the rotation of tokens is expected.
4. Once successfully migrated to the new API token, Leadspace will deprecate the old token.

API - single Enrichment

Request

URL

https://apigw.leadspace.com/enrichment/enrich/single

HTTP Method

POST

Request body

In the request body, supply data with the following structure:

SAMPLE REQUEST SCHEMA:

{
"person": {
"email": "",
"title": "",
"first_name": "",
"last_name": "",
"person_phone": "",
"person_country": "",
"linkedinUrl": "",
"pid": ""
},
"company": {
"lsid": "",
"ugLsid": "",
"name": "",
"website": "",
"companyLinkedinUrl": "",
"address": {
"state": "",
"city": "",
"postalcode": "",
"street": "",
"country": ""
}
},
"external_id": "",
"custom_fields": [ 
{
"name": "",
"value": ""
}
]
}

Possible Responses

Rate Limiting

The max rate limit for Single API is 30 TP/s or transactions per second, where a single transaction is a single API call. This means you can send up to 1,800 records per minute before exceeding the TP/s. Any record that exceeds this limitation will receive a 429 response as indicated in the matrix below.

Detailed Responses by Status code

Response for Status code 429 ("Rate limit exceeded")

This response is due to reaching (or potentially exceeding) the maximum concurrent requests limit of the given customer.

Rate Limiting Policy - Leadspace's rate limiting policy is based on the customer’s program type tiered SLA. The SLA is set as the number of possible transactions per seconds (TPS). Each additional request which will exceed the SLA will be rejected.

* Response for Status code 401 ("Credentials are required to access this resource")

The response may or may not include a body, but the body should be ignored what so ever.

* Response for Status code 500 to 504 ("Server Error" and its variants)

The body of the response may or may not exist.

* Response for Status code 200

The response of status code 200, as listed above, has the following schema:

Schema definitions for the results data

Attached is a spreadsheet version of the request and response fields matrix in this article. Also for your convenience, please find below links to other articles about the Leadspace API V3, that will help you through the integration process:

Leadspace API - Format Changes v2 vs v3

API V3 OAuth 2.0 Diagram