Skip to main content

Leadspace Discovery API

  • Updated

SETUP

As part of the setup process, Leadspace provides an API Key and a Program ID.

The API 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. The encoding being used is UTF-8 to represent Unicode based text.

DATA FORMAT

The data format being used for the 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 exist, 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, using HTTP Basic Authentication.

Authorization header should be set in the following format: 'Authorization':'Bearer API_KEY’

The username (Program ID) and the secret (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 6 months, starting from the completion of the integration period (or, “token life cycle”).
  2. The Technical Support and Integration team at Leadspace will be in charge of generating the new token and deprecating the existing one in cooperation with the customer.
  3. Leadspace’s Integration Manager will notify the customer 10 working days prior to the end of the token life cycle that a rotation of tokens is expected.
  4. Once the customer has successfully migrated to the new API token, Leadspace’s Integration Manager will deprecate the existing token.

API - BULK DISCOVERY - POST

Request

URL

/v2/expansion/company

HTTP Method

POST

Request body

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

Property Name Value Description Notes
data list List of discovery request objects Up to 500 accounts per bulk request
data[] nested object    
data[].account.companyName string Company name to expand Either company name OR company website are mandatory properties for discovery
data[].account.companyWebsite string Company website to expand Either company name OR company website are mandatory properties for discovery
data[].contact.persona array Array of the persona criteria to be used as a mean to rank the discovery results

Up to 5 personas MAX
data[].contact.contactRegions string Array of the persona regions to be used as a mean to rank the discovery results  
data[].contact.contactCountries string Array of the persona countries to be used as a mean to rank the discovery results Valid only for "United States"
data[].contact.contactState string Array of the persona states to be used as a mean to rank the discovery results  
data[].requiredResultsFields.directPhone boolean Indicates if direct phone is required for the results  
data[].requiredResultsFields.companyPhone boolean  Indicates if company phone is required for the results  
data[].requiredResultsFields.verifiedEmail boolean Indicates if a verified person email is required for the results  
data[].limits.resultPerAccount integer Set the max amount of leads should be retrieved per each expanded account Number of results per account can be between 1-100.
Default is 10 if no value is input.
data[].location.country string Set the required person location. The country value can be either:
  1. One of the countries in the picklist values which can be found in the appendix section at the bottom of this document.
  2. Blank value, this will retrieve only people which have no country value.
  3. To receive all possible locations, do not send this property as part of the request at all.
 Field can receive multiple values separated by "," delimiter.
For example: "United States","United Kingdom"
data[].external_id string  External identifier for a single object in the bulk request. If provided, the same value is used in the "data[].external_id" field in the result body. This input is not used for the processing itself whatsoever.  
external_bulk_id string  External identifier for the entire request. If provided, the same value is used in the "external_bulk_id" field in the result body. This input is not used for the processing itself whatsoever.  
callbackUrl string The URL Leadspace will call back when the bulk processing will be completed Optional

 

SAMPLE REQUEST BODY

{
"data": [
{
"account": {
"companyName": "",
"companyWebsite": "",
"companyCountry": "",
"companyState": "",
"companyCity": ""
},
"contact": {
"persona": [],
"minimumScore": 30,
"contactRegions": [],
"contactStates": [],
"contactCountries": [],
"contactDepartments": [],
"contactJobFunctions": [],
"contactLevels": []
},
"requiredResultsFields": {
"verifiedEmail": false,
"directPhone": false,
"companyPhone": false
},
"limits": {
"resultPerAccount": 1-100
}
}
],
"external_bulk_id": "3243"
}

Possible Responses

Status Code Scenario Description Retriable
202 Bulk job successfully accepted Link with polling endpoint URI N/A
400 Request fails basic input validation or JSON format is invalid Input and JSON format should be reviewed No
401 Unauthorized request (wrong credentials or credentials have expired)   No
403 Program ID is invalid   No
427 Insufficient credits Insufficient credits to process this request No
5XX Server error Error code, timestamp, tracking id, details Yes

Detailed Responses by Status Code

Response for Status code 202 ("Accepted")

The response body contains the polling endpoint URI in the following format:

Property Name Value Description
id /<apiversion>/expansion/results/<Leadspace bulk ID> The polling endpoint uri to extract the bulk results

Callback URL JSON response 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:

  • COMPLETED
  • INSUFFICIENT_CREDITS
  • INTERNAL_ERROR
successRecords integer The amount of records that were processed successfully
personEnriched integer The amount of persons retrieved from the company
companyEnriched integer Indicates if the company was expanded or not

General JSON response format for a request of type POST

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

Details of an error

Rate Limiting Policy

Version 3 of the Leadspace bulk API does not enforce any limitations to the number of concurrent connections with the API.

The rate limit in the bulk API details the rate in which Leadspace will start processing the leads in the bulk request.

While the requests start the processing, Leadspace can keep up to 100,000 leads in the backlog.

API - BULK DISCOVERY - POLLING

Request 

URL

/v1/expansion/results/<Leadspace bulk ID>

HTTP Method

GET

The Authentication Header should include the API Key.

Possible Responses

Status Code

Scenario

Body

200

Request is done

See detailed schema below.

204

Request is still processing

  

401

Unauthorized request

 

404

Results not found

 

500-504

Server error

Error code, timestamp, tracking id.


Response for Status Code 200

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

Property Name

Value

Description

results

list

List of expansion results.

results[]

nested object

  

results[].status

string

Indicates if the expansion request was successful or not. 

Can be one of the following:

  • Success
  • Failure

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[].data

nested object

Contains the data regarding the contacts retrieved as part of the expansion.

results[].data.external_id

string

The corresponding external_id from the request's object.

results[].data.persons[]

list

Result of expansion for a specific company. The list contains all the contact’s data that were expanded from the company.

results[].data.requestDetails

nested object

Contains the request data.

results[].data.requestDetails.companyName

string

The account name that was sent for expansion.

results[].data.requestDetails.compayWebsite

string

The account website that was sent for expansion.

results[].data.requestDetails.country[]

list

The required person location that was sent to expansion.

external_bulk_id

string

  


Schema Definitions for a Single Element in the Results List

(the results status and the sub-object results[].data.persons[])

Property Name

Value

Description

Notes

results[].data.expansionStatus.status

string

Expansion status of specific company.

Values can be:

  • EXPANDED
  • NOT_EXPANDED
  

results[].data.expansionStatus.message

string

Record level status message

  

results[].data.persons

nested object

Contains the persons data that were expanded from the company

  

results[].data.persons.persona

list

Contains the person’s persona scores

  

results[].data.persons.result

nested object

Contains the expansion data for the person\company

  

results[].data.persons.result.person

nested object

    

results[].data.persons.result.person.address

nested object

    

results[].data.persons.result.person.address.country

string

    

results[].data.persons.result.person.address.state

string

    

results[].data.persons.result.person.address.city

string

    

results[].data.persons.result.person.verification_status

string

Verification status of the input person, if given. Can be one of the following:

  • Moved
  • Verified
  • Not Verified
  

results[].data.persons.rPersesult.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
  

results[].data.persons.result.person.first_name

string

First name

  

results[].data.persons.result.person.last_name

string

Last name

  

results[].data.persons.result.person.title

string

Job title

  

results[].data.persons.result.person.department

string

Job department

  

results[].data.persons.result.person.level

string

Job level, can be one of the following:

  • C Level
  • Board Level
  • VP Level
  • Director Level
  • Manager Level
  • Staff Level
  

results[].data.persons.result.person.linkedin_profile

string

Person's LinkedIn profile URL

  

results[].data.persons.result.person.analytics

nested object

    

results[].data.persons.result.person.analytics.job_functions

list

    

results[].data.persons.result.person.analytics.job_functions[]

string

    

results[].data.persons.result.person.analytics.technologies

list

    

results[].data.persons.result.person.analytics.technologies[]

string

    

results[].data.persons.result.person.analytics.scores

list

    

results[].data.persons.result.person.analytics.scores[]

nested object

    

results[].data.persons.result.person.analytics.scores[].profile_name

string

Profile used for this analytics item

  

results[].data.persons.result.person.analytics.scores[].score

nested object

    

results[].data.persons.result.person.analytics.scores[].score.value

decimal

  

Nullable

results[].data.persons.result.person.contactInfo

nested object

Contact details of a specific person in the expanded account

  

results[].data.persons.result.person.contactInfo.directPhone.value

String

Direct phone of the specific person in the expanded account

  

results[].data.persons.result.person.contactInfo.email.value

String

Email address of the specific person in the expanded account

  

results[].data.persons.company

nested object

    

results[].data.persons.company.name

string

Name of the company

  

results[].data.persons.company.ls_id

string

Leadspace's company identifier

  

results[].data.persons.company.description

string

Company description

  

results[].data.persons.company.address

nested object

    

results[].data.persons.company.address.country

string

    

results[].data.persons.company.address.state

string

    

results[].data.persons.company.address.city

string

    

results[].data.persons.company.address.street

string

  

Value might also be PO box

results[].data.persons.company.address.zipcode

string

    

results[].data.persons.company.address.region

string

    

results[].data.persons.company.phone

string

    

results[].data.persons.company.industry

string

    

results[].data.persons.company.sub_industry

string

    

results[].data.persons.company.linkedin_profile

string

    

results[].data.persons.company.website

string

    

results[].data.persons.company.sic

string

    

results[].data.persons.company.naics

string

    

results[].data.persons.company.size

nested object

    

results[].data.persons.company.size.range

string

Free text describing company size in a human readable range.

Can be one of the following:

  • 0 - 25
  • 25 - 100
  • 100 - 250
  • 250 - 1K
  • 1K - 10K
  • 10K - 50K
  • 50K - 100K
  • > 100K
  

results[].data.persons.company.size.exact

Unsigned integer

The exact number of company size

  

results[].data.persons.company.revenue

nested object

    

results[].data.persons.company.revenue.range

string

Free text describing company's revenue in a human readable range. Can be one of the following:

  • $0-1 Million
  • $1-10 Million
  • $10-50 Million
  • $50-100 Million
  • $100-250 Million
  • $250-500 Million
  • $500M-1 Billion
  • > $1 Billion
  

results[].data.persons.company.revenue.exact

unsigned integer

The exact amount of company's revenue

No currency symbol

results[].data.persons.company.analytics

nested object

    

results[].data.persons.company.analytics.installed_base_technologies

array

    

results[].data.persons.company.analytics.installed_base_technologies[]

string 

    

results[].data.persons.company.family_tree

nested object

Companies in addition to the match company above

Nullable

results[].data.persons.company.family_tree.companies

list

  

Not nullable, may be empty

results[].data.persons.company.family_tree.companies[]

nested object

    

results[].data.persons.company.family_tree.companies[].type

string

Company type.

Can be one of the following:

  • DU
  • GU
  • SITE

The abbreviations are:

DU

Domestic Ultimate

GU

Global Ultimate

results[].data.persons.company.family_tree.companies[].name

string

Name of the company

  

results[].data.persons.company.family_tree.companies[].ls_id

string

Leadspace's company identifier

  

results[].data.persons.company.family_tree.companies[].address

nested object

    

results[].data.persons.company.family_tree.companies[].address.country

string

    

results[].data.persons.company.family_tree.companies[].address.state

string

    

results[].data.persons.company.family_tree.companies[].address.city

string

    

results[].data.persons.company.family_tree.companies[].address.street

string

  

Value might also be PO box

results[].data.persons.company.family_tree.companies[].address.zipcode

string

    

results[].data.persons.company.family_tree.companies[].address.region

string

    

results[].data.persons.company.family_tree.companies[].phone

string

    

results[].data.persons.company.family_tree.companies[].website

string

    

results[].data.persons.company.family_tree.companies[].sic

string

    

results[].data.persons.company.family_tree.companies[].naics

string

    

results[].data.persons.company.family_tree.companies[].size

nested object

    

results[].data.persons.company.family_tree.companies[].size.range

string

Free text describing company size in a human readable range.

Can be one of the following:

  • 0 - 25
  • 25 - 100
  • 100 - 250
  • 250 - 1K
  • 1K - 10K
  • 10K - 50K
  • 50K - 100K
  • > 100K
  

results[].data.persons.company.family_tree.companies[].size.exact

Unsigned integer

The exact number of company size.

# of employees

results[].data.persons.company.family_tree.companies[].revenue

nested object

    

results[].data.persons.company.family_tree.companies[].revenue.range

string

Free text describing company's revenue in a human readable range. Can be one of the following:

  • $0-1 Million
  • $1-10 Million
  • $10-50 Million
  • $50-100 Million
  • $100-250 Million
  • $250-500 Million
  • $500M-1 Billion
  • > $1 Billion
  

results[].data.persons.company.family_tree.companies[].revenue.exact

unsigned integer

The exact amount of company's revenue

No currency symbol

results[].data.persons.company.family_tree.site_is_subsidiary

boolean

A flag indicating if the matched company is a subsidiary of the HQ company

Nullable


Record-Level Errors

Record-level errors 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 with empty account name and website will be tagged as "Invalid Input".

1400

Transactions limit has been reached

Insufficient transactions in the program to process this record.


APPENDIX

The following list of countries is the picklist of potential values to insert for the request person location:

Antigua and Barbuda

Nicaragua

Denmark

Lithuania

Slovenia

French Polynesia

Bahamas

Panama

Djibouti

Luxembourg

Somalia

India

Bermuda

Paraguay

Egypt

Macedonia

South Africa

Indonesia

Canada

Peru

Equatorial Guinea

Madagascar

South Sudan

Japan

Caribbean Nations

Saint Lucia

Eritrea

Malawi

Spain

Kiribati

Greenland

Saint Vincent and the Grenadines

Estonia

Mali

Sudan

Korea

Saint Kitts and Nevis

Suriname

Ethiopia

Malta

Svalbard and Jan Mayen

Laos

Turks and Caicos Islands

Trinidad and Tobago

Faroe Islands

Mauritania

Swaziland

Macao

United States

Uruguay

Finland

Mauritius

Sweden

Malaysia

Virgin Islands (U.S.)

Venezueala

France

Mayotte

Switzerland

Maldives

Anguilla

Virgin Islands (British)

French Southern Territories

Moldova

Syria

Marshall Islands

Argentina

Afghanistan

Gabon

Monaco

Tajikistan

Mongolia

Aruba

Aland Islands

Gambia

Montenegro

Tanzania

Myanmar

Barbados

Albania

Georgia

Morocco

Togo

Nauru

Belize

Algeria

Germany

Mozambique

Tunisia

Nepal

Bolivia

Andorra

Ghana

Namibia

Turkey

New Caledonia

Brazil

Angola

Greece

Netherlands

Turkmenistan

New Zealand

Cayman Islands

Antarctica

Guernsey

Niger

UAE

Niue

Chile

Armenia

Guinea

Nigeria

Uganda

Norfolk Island

Colombia

Austria

Guinea-Bissau

Northern Ireland

Ukraine

North Korea

Costa Rica

Azerbaijan

Hungary

Norway

United Kingdom

Northern Mariana Islands

Cuba

Bahrain

Iceland

Oman

Uzbekistan

Pakistan

Curacao

Belarus

Iran

Palestinian Territory

Vatican City State (Holy See)

Palau

Dominica

Belgium

Iraq

Poland

Wales

Papua New Guinea

Dominican Republic

Benin

Ireland

Portugal

Yemen

Philippines

Ecuador

Bosnia and Herzegovina

Isle of Man

Qatar

Zambia

Pitcairn

El Salvador

Botswana

Israel

Reunion

Zimbabwe

Samoa

Falkland Islands (Malvinas)

Bulgaria

Italy

Romania

American Samoa

Singapore

French Guiana

Burkina Faso

Jordan

Russia

Australia

Solomon Islands

Grenada

Burundi

Kazakhstan

Rwanda

Bangladesh

Sri Lanka

Guadeloupe

Cameroon

Kenya

Saint Helena

Bhutan

Taiwan

Guatemala

Cape Verde

Kosovo

San Marino

British Indian Ocean Territory

Thailand

Guyana

Central African Republic

Kuwait

Sao Tome and Principe

Brunei

Timor-Leste

Haiti

Chad

Kyrgyzstan

Saudi Arabia

Cambodia

Tokelau Islands

Honduras

Comoros

Latvia

Scotland

China

Tonga

Jamaica

Cote D'Ivoire (Ivory Coast)

Lebanon

Senegal

Christmas Island

Tuvalu

Martinique

Croatia

Lesotho

Serbia

Cocos (Keeling) Islands

Vanuatu

Mexico

Cyprus

Liberia

Seychelles

Cook Islands

Vietnam

Montserrat

Czech Republic

Libya

Sierra Leone

Federated States of Micronesia

  

Netherlands Antilles

Democratic Republic of the Congo

Liechtenstein

Slovakia

Fiji

  

Related articles