This API is meant for just for refreshing, receiving the Intent fields for the purposes of refreshing Intent values.
Setup
As part of the setup process, Leadspace provides an API key (textual) 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.
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
API calls and requests: JSON (as defined in RFC 7159).
Date and timestamps: ISO 8601 format, in UTC - Example: 2015-05-03T15:38:45Z.
Endpoint
The Base URL https://apigw.leadspace.com/v1/intent/score/
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”).
- 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.
Input Fields
Request
URL - https://apigw.leadspace.com/v1/intent/score/
HTTP Method
POST
Request body
In the request body, please make sure to supply data with the following structure:
| Property Name |
Value |
Description |
| *company.name |
string |
Name of the company |
| company.website | string | URL of the company's website |
| company.country | string | The company country input |
| company.state | string | The company state input |
| company.city | string | The company city input |
| external_id | Text | Optional field to use to track internal system IDs (ex: SFDC Account ID) |
| external_bulk_id | Text | Optional field to use to tag particular bulk requests |
{
"data":[
}
"company": {
"name": null,
"website": null,
"phone": null,
"address":{
"country": null,
"state": null,
"city": null
},
"external_id":null
}
}
],
"external_bulk_id":null
}
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
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.
HTTP Method: GET
API URL: https://apigw.leadspace.com/v3/enrichment/results/<JobID>
Ex: https://apigw.leadspace.com/v3/enrichment/results/a4b6e123-8905-4dff-a966-50c3ce8f78ft
Response for Status Code 200
| Property Name | Status |
Description |
| status | string |
Can be one of the following:
|
| external_id | string | The corresponding external_id from the request's object |
| data | nested object | See schema below |
The Schema
| Property Name | Value | Description |
| results | ||
| status | string |
Success |
| data | nested object | |
| data.status |
Can be one of the following:
|
|
| data.domain_used | string | The domain used on the request |
| data.domain_intent | string |
Company's top surging intent topics (if empty - "No Surging Topics") |
| data.intent_modeling_scores.project_name |
string | The customer intent modeling project name |
| data.intent_modeling_scores.project_score | string |
As defined in the project: By default: 0-1 No Intent 1-75 Low 75-95 medium 95-100 high |
|
company.intent_modeling.new_high_intent_flag |
String |
No |
| data.intent_modeling_scores.surging_topics | array | The customer intent modeling drivers |
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" |
For your convenience, please find below links to other articles regarding the Leadspace API v3, that will help you through the integration process: