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 Bulk 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.
The key authenticates the program, and if needed, Leadspace can provide several 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 use HTTPS protocol.
Encoding
Most of the requests and responses are textual. The encoding is UTF-8 to represent 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
The Base URL is https://apigw.leadspace.com.
All the additional endpoints will be variations on the above URL.
Authentication
The requests to Leadspace's API should include the standard HTTP Authorization header and use the HTTP Basic Authentication.
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 by an 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 - Bulk Enrichment
Request
URL - https://apigw.leadspace.com/enrichment/enrich/bulk
HTTP Method
POST
Request body
In the request body, please make sure to supply data with the following structure:
| Property name | Value | Description | Notes |
| data | list | The list of objects (defined below). | max. 500 items/records per POST |
| data[] | nested object | ||
| data[].person | nested object | ||
| data[].person.first_name | string | First name | |
| data[].person.last_name | string | Last name | |
| data[].person.email | string | Email address | |
| data[].person.title | string | Job title | |
| data[].person.phone | string | If provided, Phone Validation fields will be provided in the Response. | |
| data[].linkedinUrl | string | If provided, can be used for person enrichment matching. | |
| person.address.country | string | If provided, used for the Phone Validation fields will be provided in the Response. | |
| data[].company | nested object | ||
| data[].company.name | string | The name of the company | |
| data[].company.lsid | string | The LSID of the company | OPTIONAL - if sent will use LSID to match first. |
| data.[].company.ugLsid | string | The UG Company ID of the company | |
| data[].company.website | string | The URL of the company's website | |
| data[].company.phone | string | If provided, Phone Validation fields will be provided in the Response. | |
| data[].company.companyLinkedinUrl | string | ||
| data[].company.address | nested object | ||
| data[].company.address.country | string | ||
| data[].company.address.state | string | ||
| data[].company.address.city | string | ||
| company.address.street | string | ||
| company.address.postalcode | string | ||
| company.duns | string | ||
| data[].custom_fields | list | ||
| data[].custom_fields[] | nested object | ||
| data[].custom_fields[].name | string | ||
| data[].custom_fields[].value | string |
|
|
| data[].external_id | string | An external identifier for the request. If provided, the same value will be provided in the "external_id" field in the body of the result. This input is not used for the processing and enrichment. | |
| external_bulk_id | string | The external identifier for the entire request. If provided, the same value will be provided in the "external_bulk_id" field in the body of the result. This input is not used for the processing and enrichment. | |
| callbackUrl | string | The URL Leadspace will call back when the bulk processing will be completed | Optional |
Sample Bulk REQUEST (2 records):
{
"data": [
{
"person": {
"email": "",
"title": "",
"first_name": "",
"last_name": "",
"person_phone": "",
"person_country": "",
"linkedinUrl": ""
},
"company": {
"lsid": "",
"ugLsid": "",
"name": "",
"website": "",
"domain": "",
"companyLinkedinUrl": "",
"address": {
"state": "",
"city": "",
"postalcode": "",
"street": "",
"country": "United States"
}
},
"external_id": "",
"custom_fields": [
{
"name": "",
"value": ""
}
]
},
{
"person": {
"email": "",
"title": "",
"first_name": "",
"last_name": "",
"person_phone": "",
"person_country": ""
},
"company": {
"lsid": "",
"ugLsid": "",
"name": "",
"website": "",
"domain": "",
"companyLinkedinUrl": "",
"address": {
"state": "",
"city": "",
"postalcode": "",
"street": "",
"country": "United States"
}
},
"external_id": "",
"custom_fields": [
{
"name": "",
"value": ""
}
]
}
]
}
Possible Responses
| Status code | Scenario | Description | Retrievable |
| 202 | The Bulk job has successfully accepted | A link with polling endpoint URI | N/A |
| 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 |
No |
| 401 | Unauthorized request (wrong credentials or credentials have expired) | Credentials are required to access this resource. | No |
| 427 | Insufficient credits or program ID is invalid | Please reach out to the Customer Success Manager and the Support team (at support@leadspace.com) for credits allocation | No |
| 5XX | Server error |
The error will contain the following details: Error code, timestamp, tracking id, details Please reach out to the Support team for assistance. |
Yes |
The response for the status code 202 ("Accepted")
The response body contains the polling endpoint URL in the following format:
| Property name | Value | Description |
| id | /<apiversion>/enrichment/results/<Leadspace bulk ID> | The polling endpoint URI to extract the bulk results |
Callback URL JSON response format
In case the callback URL was used and implemented in the request, the callback URL response format will be in the following format:
| Property name | Value | Description |
| bulkId | string | The bulk ID |
| callbackMethod | nested object | |
| callbackMethod.callbackUrl | string | The URL the API is calling back |
| callbackMethod.pollingUrl | string | URL for polling the bulk once it’s completed processing |
| bulkStatus | string | Retrieves the detailed status of the bulk. |
|
Property values:
|
||
| successRecords | integer | The number of records that were processed successfully |
| personEnriched | integer | The number of records where the person was enriched successfully |
| companyEnriched | integer | The number of records where the company was enriched successfully |
General JSON response format
The body of the response may or may not exist in a JSON format.
In case it exists in a JSON format, it is structured using the following schema:
| Property name | value | description |
| error | string | Error description |
| tracking_id | string | Leadspace tracking identifier, for further inspection of this request |
| request_timestamp | timestamp | The timestamp assigned to the given request once reached Leadspace's servers. |
| details | string | The details of an error |
Rate Limiting Policy
Default rate limit for our API service is 30 TP/s or transactions per second, with one transaction being a single API up to 500 records. This means that theoretically, you can send 15,000 records per second using the Bulk API.
However, the Leadspace API V3 service doesn't enforce any limitations to the number of concurrent connections to the API. The rate limit of the Bulk API is the rate in which Leadspace will start processing the leads in the Bulk request. Leadspace can keep up to 100000 leads in the backlog, while other requests are being processed.
API - Bulk Enrichment - Polling
Request
URL
/v3/enrichment/results/<Leadspace bulk ID>
HTTP Method
GET
The Authentication Header should include the API key.
Possible Responses
| Status code | Scenario | Body |
|---|---|---|
| 200 | The request is done | See detailed schema below |
| 204 | The request is still processing | |
| 401 | Unauthorized request | - |
| 404 | The results are not found | - |
| 500-504 | Server error | Error code, timestamp, tracking id |
The Response for Status code 200
The response of the status code 200, as listed above, has the following schema:
| Property name | Value | Description |
|---|---|---|
| results | list | |
| results[] | nested object | |
| results[].status | string |
Can be one of the following:
|
| results[].errors | list | Leadspace errors for the current record (see record-level error section below). |
| results[].errors[] | nested object | |
| results[].errors[].code | integer | Leadspace error code |
| results[].errors[].description | string | Additional information about the error. Might be null. |
| results[].external_id | string | The corresponding external_id from the request's object |
| results[].data | nested object | See schema below |
| external_bulk_id | string | If provided |
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.address | string | Person Street Address |
| person.address.zipcode | string | Person Zipcode |
| 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 |
Record-Level Errors
The record-level error will appear when the bulk request was valid, but the process failed for an individual record. Record-level errors may contain the following values:
| Error code | Error description | Comment |
| 1100 | Internal Error | Leadspace internal error. |
| 1200 | Invalid Input | Record did not pass advanced input validations. For example, records for which the First and Last Names were not provided will be tagged as "Invalid Input" |
Related Articles