Print Friendly and PDF
Follow

Leadspace Single API v3 - Technical Specifications

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 IDThis 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:

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

 

API - single Enrichment

Request

URL

/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.website

string

URL of the company's website

 

company.address

nested object

   

company.address.country

string

   

company.address.state

string

   

company.address.city

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:

{
"external_id": null,
"person": {
      "last_name": null,
       "first_name": null,
       "email": null,
        "title": null
},

"company": {
       "name": null,
       "website": null,
       "address": {
              "city": null,
              "state": null,
              "country": null
},
"custom_fields":[
         {
              "name":"Name",
              "value": "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

 

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.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

 

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. 

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.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

company.family_tree.site_is_subsidiary

boolean

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

Nullable

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>

   



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

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request

0 Comments

Please sign in to leave a comment.