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 using the newest, Leadspace v4 data graph.
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:
- 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”). If the perpetual token is not rotated, it will expire after a period of 2 years after is is generated and sent to you.
- Leadspace will generate a new token and provide it by an email.
- Leadspace will send a notification before the end of the token life cycle that the rotation of tokens is expected.
- 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/singleHTTP 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 | |
| linkedinUrl | string | Person LinkedIn URL | |
| 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.ugLsid | string | UG Company ID for the company | |
| company.website | string | URL of the company's website | |
| company. companyLinkedinUrl | string | URL of the company's LI profile | |
| 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": "",
"linkedinUrl": ""
},
"company": {
"lsid": "",
"ugLsid": "",
"name": "",
"website": "",
"companyLinkedinUrl": "",
"address": {
"state": "",
"city": "",
"postalcode": "",
"street": "",
"country": ""
}
},
"external_id": "",
"custom_fields": [
{
"name": "",
"value": ""
}
]
}
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:
|
| external_id | string | The corresponding external_id from the request's object |
| data | nested object | Specified in the schema below |
Response Schema Definitions: Excel Worksheet of Output Schema Attached
| Property Name | Value | Description |
|---|---|---|
| status | string | Technical status of the response |
| Success | ||
| Invalid Input | ||
| data | nested object | Defines the response data, broken out into person and company nested objects |
| person | nested object | |
| 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.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 | Persona value matched to the person enrichment (Standard or Custom Personas required) |
| person.analytics.scores[].score | nested object | |
| person.analytics.scores[].score.value | decimal | Persona score per name value |
| person.analytics.max_positive_score_profiles | string | List personas that scored the highest if applicable (Standard or Custom Personas required) |
| person.address | nested object | |
| person.address.country | string | Person country |
| person.address.state | string | Person state |
| person.address.city | string | Person city |
| person.address.region | string | Person region |
| 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 | ||
| Social & Email | ||
| person.original_email_verification_status | string | Value returned by our 3rd party email validation vendor. Requires email input in request |
| VALID | ||
| INVALID | ||
| UNKNOWN | ||
| CATCH-ALL | ||
| person.ug_person_id | string | Unique Leadspace person identifier |
| person.original_email | string | Original email input sent in the request |
| person.first_name | string | First name |
| person.last_name | string | Last name |
| person.linkedin_profile | string | The person's LinkedIn profile URL |
| person.data_validation | nested object | |
| person.person_mobile_phone_1 | string | Person mobile phone returned (requires premium mobile number purchase) |
| person.person_mobile_phone_2 | string | Second person mobile phone returned (requires premium number purchase) |
| person.person_mobile_phone_3 | string | Third person mobile phone returned (requires premium number purchase) |
| person.is_retired | string | Boolean true/false. Pulls 'retired' information from social vendor job title |
| person.phone | string | Person phone, alinged with landline or company phone data |
| company | nested object | |
| company.name | string | The name of the company Leadspace match |
| company.description | string | Company description |
| company.address | nested object | |
| company.address.country | string | Company country |
| company.address.state | string | Company state |
| company.address.city | string | Company city |
| company.address.address | string | Company street address |
| company.address.zipcode | string | Company zip/postalcode |
| company.address.region | string | Company region |
| company.longitude | string | Company longitude coordinates |
| company.latitude | string | Company latitude coordinates |
| company.phone | string | Company office phone number |
| company.industry | string | Company industry as derived from NAICS identifier and classification |
| company.website | string | Company website |
| company.sic | string | Company 4 digit SIC identifier |
| company.sicDescription | string | Company SIC description |
| company.naics | string | Company NAICS classification and ID |
| company.naicsDescription | string | Company NAICS description |
| company.employees | nested object | |
| company.employees.exact | number | Exact value of company employees |
| company.employees.range | string | Range of company employees based on exact value |
| company.analytics | nested object | |
| company.analytics.customTechnologiesCategories | array | Names of installed base technology categories (requires tech signal purchase and configuration) |
| company.analytics.customTechnologiesCategories[] | string | Names of installed base technology categories (requires tech signal purchase and configuration) |
| company.analytics.installed_base_technologies | array | Installed base tech signal values, comma separated |
| company.analytics.installed_base_technologies[] | string | Installed base tech signal values, comma separated |
| company.analytics.web_site_technologies | array | Names of website technology categories (requires website tech signals purchase and configuration) |
| company.analytics.web_site_technologies[] | string | Names of website technology categories (requires website tech signals purchase and configuration) |
| company.analytics.company_technologies_categories | array | Website tech signal values, comma separated |
| company.analytics.company_technologies_categories[] | string | Website tech signal values, comma separated |
| company.ls_id | string | Leadspace company identifier (v3 artifact that will be sunset in 2026. Mirrors UG Company ID value) |
| company.ug_company_id | string | Leadspace unique company identifier |
| company.sub_industry | string | Leadspace Sub Industry values, derived from NAICS classification and identifiers |
| company.linkedin_profile | string | Company LinkedIn Profile |
| company.revenue_dollar | nested object | |
| company.revenue_dollar.range | string | Free text describing the company's revenue in US dollars 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_dollar.exact | number | The exact US dollar amount of company's revenue |
| company.family_tree | nested object | The company's hierarchies in addition to the matched company above |
| company.family_tree.companies | list | |
| company.family_tree.companies[] | nested object | |
| company.family_tree.companies[].type | string | The company type. Can be one of the following values: |
| DU (Domestic Ultimate) | ||
| GU (Global Ultimate) | ||
| SITE (Office Level) | ||
| PARENT (Subsidiary Parent) - Requires premium hierarchy purchase | ||
| HQ (Headquarters) - Requires premium hierarchy purchase | ||
| SU (Sub Ultimate) - Requires premium hierarchy purchase | ||
| 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 country |
| company.family_tree.companies[].address.state | string | Company family tree state |
| company.family_tree.companies[].address.city | string | Company family tree city |
| company.family_tree.companies[].address.address | string | Company family tree street address |
| company.family_tree.companies[].address.zipcode | string | Company family tree zipcode |
| company.family_tree.companies[].address.region | string | Company family tree region |
| company.family_tree.companies[].phone | string | Company family tree phone |
| company.family_tree.companies[].website | string | Company family tree website |
| company.family_tree.companies[].sic | string | Company family tree sic |
| company.family_tree.companies[].naics | string | Company family tree naics |
| company.family_tree.companies[].size | nested object | Company family tree size |
| company.family_tree.companies[].employee.range | string | Free text describing company size in a human readable range. |
| Can be one of the following values: | ||
| Myself only | ||
| 18537 | ||
| 51-200 | ||
| 51-200 | ||
| 201-500 | ||
| 501-1000 | ||
| 1001-5000 | ||
| 5001-10,000 | ||
| 10,001+ | ||
| company.family_tree.companies[].employee.exact | Unsigned integer | The exact number of company size. |
| company.family_tree.companies[].revenue_dollar | nested object | |
| company.family_tree.companies[].revenue_dollar.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_dollar.exact | unsigned integer | The exact amount of company's revenue |
| company.ownership | string | Indicates whether the company is publically or privately held |
| company.matching_confidence.level | string | Can be one of the following values: |
| HIGH | ||
| MEDIUM | ||
| LOW | ||
| VERY LOW | ||
| company.original_name | string | The name of the company input from the request |
| company.linkedin_profile | string | Company's LinkedIn profile |
| company.size.exact | number | The exact number of the company size. |
| company.domain_intent | string | Company's top surging intent topics |
| company.intent_modeling_v4 | nested object | |
| company.intent_modeling_v4.model | string | Name of the intent model |
| company.intent_modeling_v4.model_level | array | Project score will be one of the following options: |
| High | ||
| Medium | ||
| Low | ||
| NO_INTENT | ||
| List intent topics matched to the model for the previous 7 days | ||
| company.intent_modeling_v4.source | string | Lists the source of the intent, either LS Intent or Bombora |
| company.intent_modeling_v4.cadence | string | List frequency of model updates, always 'weekly' |
| company.intent_modeling_v4.new_high_intent | string | Boolean that indicates whether there are new drivers for that week. Yes or No |
| company.intent_modeling_v4.industries | array | Lists industries relevant to the intent results for that week |
| company.intent_modeling_v4.top_metros | array | Lists locations from where the intent interest has derived |
| company.intent_modeling_v4.domain_origins | array | Lists the country origins from the domains that searched for intent topics |
| company.specialties | nested object | |
| company.specialties [] | array | Lists company specialty keywords |
| company.hierarchy_level | nested object | |
| company.hierarchy_level.sub_ultimate_flag | string | Boolean indicating whether company is a sub ultimate company. Values are 'Y' or 'N' |
| company.signals | nested object | |
| company.signals.fortune_500_rank | number | 1-500, indicates ranking on F500 |
| company.signals.fortune_1000_rank | number | 1-1000, indicates ranking on F1000 |
| company.signals.g2k_rank | number | 1-2000, indicates ranking on G2K |
| company.funding | nested object | |
| company.funding.last_round_investor_count | number | Indicates how many investors invested during latest round |
| company.funding.total_rounds_count | number | Indicates how many rounds of funding for the company |
| company.funding.last_round_date | string | Last funding round date |
| company.funding.cb_url | string | Crunchbase URL for funding data |
| company.funding.last_round_money_raised | string | Amount of latest round funding in US dollars |
| company.funding.last_round_type | string | Series indicator of funding type for latest round |
| company.investors | nested object | |
| company.investors.cb_url | string | Crunchbase URL showing investor details |
| company.investors.last_investor_name | string | Last investor company name |
| company.investors.company_investors | string | Investor company names |
| company.gu_indicator_flag | string | Boolean, indicates whether company is a GU. 'Y' or 'N' |
| company.du_indicator_flag | string | Boolean, indicates whether company is a DU. 'Y' or 'N' |
| company.company_tree_rank | string | Shows rank of matched company in hierarchy tree. Requires premium hierarchies |
| company.headquarters_branch_flag | string | Headquarter branch indicator |
| company.subsidiary_indicator_code | string | Subsidiary indicator |
| company.site_location_type | string | Indicates what type of company the SITE or main company match aligns with |
| company.primary_location | string | Concatenated location string showing country, state, and city for company |
| company.department_size | nested object | |
| company.department_size.hr | number | Size of HR dept |
| company.department_size.sales | number | Size of Sales dept |
| company.department_size.mgmt | number | Size of Management dept |
| company.department_size.product_mgmt | number | Size of Product Management dept |
| company.department_size.it | number | Size of IT dept |
| company.department_size.administration | number | Size of Administration dept |
| company.department_size.marketing | number | Size of Marketing dept |
| company.department_size.operations | number | Size of Operations dept |
| company.department_size.rnd | number | Size of R&D dept |
| company.department_size.business_dev | number | Size of Business Development dept |
| company.department_size.finance | number | Size of Finance dept |
| enrichment_status | string | The status of enrichment process, can be one of the following values: |
| Not Enriched | ||
| Company Enriched | ||
| Person Enriched | ||
| Person & Company Enriched | ||
| cdi_matched | string | Boolean, returns flag indicating whether a CDI match has been made. 'True' or 'False' values |
| total_scores | list | Score details for predictive/fit models. Requires purchase of predictive model |
| total_scores[] | nested object | |
| total_scores[].profile_name | string | Name of predictive model |
| total_scores[].score | nested object | |
| total_scores[].score.value | number | Numeric predictive model score |
| total_scores[].score.bucket | string | Bucket value of predictive model score. A, B, C, D |
| max_positive_total_score_profiles | list | Array of top scoring predictive models if more than 1. Requires purchase of predictive model |