Leadspace is offering 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 (textual) 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 secured manner.

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:

Perpetual token
Oauth 2.0

Perpetual Token Rotation

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”).
The Support team is in charge of generating a new token and will work with you to replace the existing one.
Once you migrate to the new API token, the previous token will be deprecated.

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:

Property name	Value	Description	Notes
person	nested object
person.first_name	string	First name
person.last_name	string	Last name
person.email	string	Email address
person.title	string	Job title
company	nested object
company.name	string	Name of the company
company.lsid	string	LSID of the company	OPTIONAL - if sent will use LSID to match on first.
company.website	string	URL of the company's website
company.address	nested object
company.address.country	string
company.address.state	string
company.address.city	string
company.address.street	string
company.address.postalcode	string
custom_fields	list
custom_fields[]	nested object
custom_fields[].name	string
custom_fields[].value	string
external_id	string	External identifier for the request. If provided, the same value is used in the "external_id" field in the body of the result. This input is not used for the processing itself what so ever.

SAMPLE REQUEST SCHEMA:

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

Possible Responses

Status code	Scenario	Body
200	The job was successfully accepted	-
400	The request failed due to insufficient basic input, or JSON format is invalid	If the JSON format is valid, please make sure you provide the following fields for the enrichment: For Account enrichment: Company Name For Person (Lead/Contact) enrichment: First Name Last Name Company Name/Email Address/Website
401	Unauthorized request (wrong credentials or credentials have expired)	Credentials are required to access this resource
405	Invalid HTTP method	-
415	Bad or missing HTTP headers	-
427	Insufficient credits	Please reach out to the Customer Success Manager and the Support team (at support@leadspace.com) for credits allocation
429	Rate limit was exceeded	-
500-504	Server error	Error code, timestamp, tracking id

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:

Property name	value	description
status	string	Can be one of the following: success failure
external_id	string	The corresponding external_id from the request's object
data	nested object	Specified in the schema below

Schema definitions for the results data

Property name	Value	Description	Notes
enrichment_status	string	The status of enrichment process, can be one of the following values: Not Enriched Company Enriched Person Enriched Person & Company Enriched
person	nested object
person.address	nested object
person.address.country	string
person.address.state	string
person.address.city	string
person.address.region	string
person.verification_status	string	The verification status of the input person, if given, Can be one of the following velues: Moved Verified Not Verified
person.verification_source	string	if person.verification_status is "Verified", this field holds the source type of the verification. Can be one of the following: Social Email Social & Email None
person.original_email	string
person.original_email_verification_status	string	Can be one of the following values: VALID INVALID UNKNOWN None
person.first_name	string	First name
person.last_name	string	Last name
person.title	string	Job title
person.department	string	Job department
person.level	string	Standard job level, can be one of the following values: C Level Board Level VP Level Director Level Manager Level Staff Level Blank value
person.linkedin_profile	string	The lead's LinkedIn profile URL	If the field is empty, it will not be sent
person.data_validation	nested object
person.data_validation.phone	nested object
person.data_validation.phone.status	string	Can be one of the following values: VALID INVALID UNKNOWN None
person.data_validation.phone.normalize_value	string
person.phone	string	Phone
company.data_validation.address	nested object
company.data_validation.address.status	string	Possible values: Valid Unknown Invalid
company.data_validation.address.normalize_value	string	The normalized company address
person.email	string
person.analytics	nested object
person.analytics.job_functions	list
person.analytics.job_functions[]	string
person.analytics.technologies	list
person.analytics.technologies[]	string
person.analytics.scores	list
person.analytics.scores[]	nested object
person.analytics.scores[].profile_name	string	The profile used for this analytics item
person.analytics.scores[].score	nested object
person.analytics.scores[].score.value	decimal		Nullable
person.analytics.max_positive_score_profiles	string
company	nested object
company.name	string	The name of the company
company.original_name	string
company.ls_id	string	Leadspace's company identifier
company.description	string	Company description
company.ownership	string
company.matching_confidence.score	string	Value will be in the range of 5-95, in increments of 10.	This feature will need to be enabled. Please reach out to your CSM if interested. NOTE: This feature will be sunsetting soon.
company.matching_confidence.level	string	Can be one of the following values: HIGH MEDIUM LOW VERY LOW
company.address	nested object
company.address.country	string
company.address.state	string
company.address.city	string
company.address.street	string		The value might also be PO box
company.address.zipcode	string
company.address.region	string
company.phone	string
company.industry	string
company.sub_industry	string
company.linkedin_profile	string	Company's LinkedIn profile
company.facebook_url	string
company.twitter_url	string
company.ticker	string
company.website	string
company.sic	string
company.naics	string
company.size	nested object
company.size.range	string	Free text describing company size in a human readable range. Can be one of the following values: Myself only 10-50 51-200 51-200 201-500 501-1000 1001-5000 5001-10,000 10,001+
company.size.exact	Unsigned integer	The exact number of the company size.	If the field is empty, it will not be sent
company.revenue	nested object
company.revenue.range	string	Free text describing the company's revenue in a human readable range. Can be one of the following values: $0-10 Million $10-50 Million $50-100 Million $100-250 Million $250-500 Million $500M-1 Billion > $1 Billion
company.revenue.exact	unsigned integer	The exact amount of company's revenue	No currency symbol
company.analytics	nested object
company.specialties	nested object
company.analytics.installed_base_technologies	array
company.analytics.installed_base_technologies[]	string
company.analytics.web_site_technologies	array
company.analytics.web_site_technologies[]	string
company.analytics.customTechnologiesCategories	array
company.analytics.customTechnologiesCategories[]	string
company.analytics.company_technologies_categories	array
company.analytics.company_technologies_categories[]	string
company.domain_intent	string	Company's top surging intent topics	This feature will need to be enabled. Please reach out to your CSM if interested.
company.intent_modeling	nested object
company.intent_modeling.project_name	string	Project name would be the name of the intent model.
company.intent_modeling.project_score	string	Project score will be one of the following options: High Medium Low No Intent Not Available	If you have more than one intent model, there will be a line item for each.
company.intent_modeling.new_high_intent_flag	string	No Yes
company.intent_modeling.surging_topics[]	array
company.intent_modeling.surging_topics	string
company.alternateCompanyDomains	string	Company additional/alternate domains
company.data_validation	nested object
company.data_validation.phone	nested object
company.data_validation.phone.status	string	Can be one of the following values: VALID INVALID UNKNOWN None
company.data_validation.phone.normalize_value	string
company.signals.fortune_500_rank	number	1-500
company.signals.g2k_rank	number	1-2000
company.family_tree	nested object	The company's hierarchies in addition to the matched company above	Nullable
company.family_tree.companies	list		Not nullable, may be empty
company.family_tree.companies[]	nested object
company.family_tree.companies[].type	string	The company type. Can be one of the following values: DU GU SITE	DU = Domestic Ultimate GU = Global Ultimate
company.family_tree.companies[].name	string	The name of the company
company.family_tree.companies[].ls_id	string	Leadspace's company identifier
company.family_tree.companies[].address	nested object
company.family_tree.companies[].address.country	string
company.family_tree.companies[].address.state	string
company.family_tree.companies[].address.city	string
company.family_tree.companies[].address.street	string		The value might also be PO box
company.family_tree.companies[].address.zipcode	string
company.family_tree.companies[].address.region	string
company.family_tree.companies[].phone	string
company.family_tree.companies[].website	string
company.family_tree.companies[].sic	string
company.family_tree.companies[].naics	string
company.family_tree.companies[].size	nested object
company.family_tree.companies[].size.range	string	Free text describing company size in a human readable range. Can be one of the following values: Myself only 10-50 51-200 51-200 201-500 501-1000 1001-5000 5001-10,000 10,001+
company.family_tree.companies[].size.exact	Unsigned integer	The exact number of company size.	If the field is empty, it will not be sent
company.family_tree.companies[].revenue	nested object
company.family_tree.companies[].revenue.range	string	Free text describing the company's revenue in a human readable range. Can be one of the following values: $0-10 Million $10-50 Million $50-100 Million $100-250 Million $250-500 Million $500M-1 Billion > $1 Billion
company.family_tree.companies[].revenue.exact	unsigned integer	The exact amount of company's revenue	No currency symbol
total_scores	list
total_scores[]	nested object
total_scores[].profile_name	string
total_scores[].score	nested object
total_scores[].score.value	decimal		Nullable
total_scores[].score.predictiveSignalsSummary	string
total_scores[].score.topPositivePredictiveSignals	string
total_scores[].score.topNegativePredictiveSignals	string
max_positive_total_score_profiles	List <string>

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

API_direct_single_fields.xlsx
20 KB Download