Introduction
Welcome to the Leadfeeder API documentation!
The Leadfeeder API has a RESTful design, meaning it has an intuitive URL structure and responds to the use of HTTP verbs.
Leadfeeder API response formats follow the JSON API 1.0 convention.
The Leadfeeder API provides information from the web-based version of Leadfeeder. It identifies the businesses of website visitors, so it’s really useful information to integrate with a B2B sales pipeline.
Before you start, you’ll need access to a working Leadfeeder Trial or Premium account. If you’re not already using Leadfeeder, you can sign up for a 14-day premium trial on our website.
Looking for Leadfeeder IP-Enrich API documentation? You can access it here.
Authentication
Leadfeeder API expects an API token to be included in all requests sent to the server.
You can generate your unique authentication token at Leadfeeder API settings
Provide your API token in the Authorization header, as follows:
Authorization: Token token=yourapitoken
If you are building an integration from another app, please include the User-Agent header with all your requests.
User-Agent: yourappname
Example call with Authorization and User-Agent headers:
curl "https://api.leadfeeder.com/..."
-XGET
-H "Authorization: Token token=yourapitoken"
-H "User-Agent: MyCRM"
Rate limiting
curl -XPOST
-H "Authorization: Token token=yourapitoken"
"https://api.leadfeeder.com/accounts"
When the API limit is exceeded the above command returns a
429 Too Many Requestsstatus code and a body with JSON structured like this:
{
"errors": [
{
"title": "Exceeded the API rate limit of 100 requests per minute. Try again later.",
"links": {
"about": "http://docs.leadfeeder.com/api/#rate-limiting"
}
}
]
}
Leadfeeder API allows a maximum of 100 requests per minute for an API token. The subsequent requests will return a 429 Too Many Requests error until the next minute starts. Then the API limit is reset. The limit includes all API requests, regardless of the endpoint URL or response.
The Exporting feeds endpoint enforces an additional limit of 5 requests per minute.
Requesting a subset of attributes
curl "https://api.leadfeeder.com/accounts/6002/leads/25e7ccea-611b-11e5-b180-3b69e435d91d_7xeTMh2VfiAzFd86n7GNJ3?fields[leads]=name,employee_count&fields[locations]=country"
-XGET
-H "Authorization: Token token=yourapitoken"
The above command returns only
nameandemployee_countattributes for lead objects andcountryfor location objects.
{
"data": {
"id": "25e7ccea-611b-11e5-b180-3b69e435d91d_7xeTMh2VfiAzFd86n7GNJ3",
"type": "leads",
"attributes": {
"name": "Leadfeeder Inc.",
"employee_count": 22
},
"relationships": {
"location": {
"data": {
"id": "7xeTMh2VfiAzFd86n7GNJ3",
"type": "locations"
}
}
}
},
"included": [
{
"id": "7xeTMh2VfiAzFd86n7GNJ3",
"type": "locations",
"attributes": {
"country": "Finland"
}
}
]
}
Leadfeeder API supports a JSON API feature called sparse fieldsets which allows requesting just a subset of attributes by adding fields parameter in request’s URL.
Using fields parameter speeds up computations on Leadfeeder servers and decreases the API response size, so it is highly encouraged to request only attributes required by your integration.
Accounts
Get accounts the user has access to
curl "https://api.leadfeeder.com/accounts"
-XGET
-H "Authorization: Token token=yourapitoken"
The above command returns JSON structured like this:
{
"data": [
{
"attributes": {
"name": "Sample account",
"subscription": "lite",
"timezone": "Europe/Helsinki"
},
"id": "6001",
"type": "accounts"
},
{
"attributes": {
"name": "Sample website",
"subscription": "premium",
"timezone": "America/New_york"
},
"id": "6002",
"type": "accounts"
},
{
"attributes": {
"name": "Another account",
"subscription": "lite",
"timezone": "UTC"
},
"id": "6003",
"type": "accounts"
},
]
}
This endpoint retrieves all accounts that can be accessed by the user the API token belongs to.
HTTP Request
GET https://api.leadfeeder.com/accounts
Get a Specific account
curl "https://api.leadfeeder.com/accounts/6002"
-XGET
-H "Authorization: Token token=yourapitoken "
The above command returns JSON structured like this:
{
"data": {
"attributes": {
"name": "Sample website",
"subscription": "premium",
"timezone": "America/New_york"
},
"id": "6002",
"type": "accounts"
}
}
This endpoint retrieves the details of a specific account.
HTTP Request
GET https://api.leadfeeder.com/accounts/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the account to retrieve |
Custom feeds
Get custom feeds list for an Account
curl "https://api.leadfeeder.com/accounts/<account_id>/custom-feeds "
-XGET
-H "Authorization: Token token=yourapitoken "
The above command returns JSON structured like this:
{
"data": [
{
"id": "all_leads",
"type": "custom_feeds",
"attributes": {
"name": "All leads",
"criteria": []
}
},
{
"id": "new_leads",
"type": "custom_feeds",
"attributes": {
"name": "New leads",
"criteria": [
{
"search_value": 0,
"excluded": true,
"criterion_type": "assignee",
"display_value": "Any assignee"
}
]
}
},
{
"id": "recommended_leads",
"type": "custom_feeds",
"attributes": {
"name": "Top leads",
"criteria": [
{
"search_value": 3,
"excluded": false,
"criterion_type": "pageviews",
"display_value": 3
},
{
"search_value": 0,
"excluded": false,
"criterion_type": "industry_code",
"display_value": "Any industry"
},
{
"search_value": 8,
"excluded": true,
"criterion_type": "industry_code",
"display_value": "Telecommunications"
},
{
"search_value": 0,
"excluded": true,
"criterion_type": "assignee",
"display_value": "Any assignee"
}
]
}
},
{
"id": "followed_companies",
"type": "custom_feeds",
"attributes": {
"name": "Followed companies",
"criteria": [
{
"search_value": "9999999",
"excluded": false,
"criterion_type": "followed",
"display_value": "Sample User"
}
]
}
},
{
"id": "9999383",
"type": "custom_feeds",
"attributes": {
"name": "Canada",
"criteria": [
{
"search_value": "CA",
"excluded": false,
"criterion_type": "country_code",
"display_value": "Canada"
}
]
}
},
{
"id": "999991535",
"type": "custom_feeds",
"attributes": {
"name": "Blog",
"criteria": [
{
"search_value": "/blog/",
"excluded": false,
"criterion_type": "page_url",
"display_value": "/blog/"
}
]
}
}
]
}
This endpoint retrieves all custom feeds for an Account.
HTTP Request
GET https://api.leadfeeder.com/accounts/<account_id>/custom-feeds
URL Parameters
| Parameter | Description |
|---|---|
| account_id | ID of the Account for which to retrive the custom feeds |
Get a Specific custom feed
curl "https://api.leadfeeder.com/accounts/6002/custom-feed/999991535"
-XGET
-H "Authorization: Token token=yourapitoken "
The above command returns JSON structured like this:
{
"data": {
"id": "9999991535",
"type": "custom_feeds",
"attributes": {
"name": "Blog",
"criteria": [
{
"search_value": "/blog/",
"excluded": false,
"criterion_type": "page_url",
"display_value": "/blog/"
}
]
}
}
}
This endpoint retrieves a specific custom feed.
HTTP Request
GET https://api.leadfeeder.com/accounts/<account_id>/custom-feeds/<custom_feed_id>
URL Parameters
| Parameter | Description |
|---|---|
| account_id | ID of the Account the custom feed belongs to |
| custom_feed_id | ID of the custom feed to retrieve |
Leads
Get leads
curl "https://api.leadfeeder.com/accounts/6002/leads?start_date=2015-09-01&end_date=2015-09-15"
-XGET
-H "Authorization: Token token=yourapitoken"
The above command returns JSON structured like this:
{
"data": [
{
"id": "400360f2-6131-11e5-90dc-638a476d8c19_6xeTMh2VfiAzFd86n7GNJ3",
"type": "leads",
"attributes": {
"name": "Leadfeeder Inc.",
"industry": "N/A",
"first_visit_date": "2015-09-18",
"status": "new",
"last_visit_date": "2015-09-21",
"website_url": "https://www.leadfeeder.com",
"phone": "+358504303422",
"linkedin_url": "https://www.linkedin.com/company/leadfeeder",
"twitter_handle": "Leadfeeder",
"facebook_url": "https://www.facebook.com/Leadfeeder",
"logo_url": "https://logos.leadfeeder.com/123/logo.png",
"assignee": null,
"business_id": null,
"revenue": null,
"emailed_to": null,
"view_in_leadfeeder": "https://app.leadfeeder.com/link/9088f1ad86",
"quality": 6,
"visits": 10
},
"relationships": {
"location": {
"data": {
"id": "6xeTMh2VfiAzFd86n7GNJ3",
"type": "locations"
}
}
}
},
{
"id": "40157512-6131-11e5-90dc-638a476d8c19_6xeTMh2VfiAzFd86n7GNJ3",
"type": "leads",
"attributes": {
"name": "Organic Mint",
"industry": "N/A",
"first_visit_date": "2015-09-18",
"status": "new",
"last_visit_date": "2015-09-21",
"website_url": "https://www.organicmint.com",
"phone": null,
"linkedin_url": null,
"twitter_handle": null,
"facebook_url": null,
"employee_count": 550,
"employees_range": { "min": 501, "max": 550 },
"crm_lead_id": 110,
"crm_organization_id": null,
"tags": ["tag1", "tag2"],
"logo_url": "https://logos.leadfeeder.com/123/logo.png",
"assignee": "user@company.com",
"business_id": "KVK Number 123",
"revenue": "EUR 395752792.0",
"emailed_to": "user@example.com,user@company.com",
"view_in_leadfeeder": "https://app.leadfeeder.com/link/9088f1ad85",
"quality": 4,
"visits": 15
},
"relationships": {
"location": {
"data": {
"id": "6xeTMh2VfiAzFd86n7GNJ3",
"type": "locations"
}
}
}
}
],
"included": [
{
"id": "6xeTMh2VfiAzFd86n7GNJ3",
"type": "locations",
"attributes": {
"country": "Finland",
"country_code": "FI",
"region": "Uusimaa",
"region_code": null,
"city": "Helsinki",
"state_code": null
}
}
],
"links": {
"self": "https://api.leadfeeder.com/accounts/6002/leads?end_date=2015-09-22&page%5Bnumber%5D=1&page%5Bsize%5D=10&start_date=2015-09-11",
"next": "https://api.leadfeeder.com/accounts/6002/leads?end_date=2015-09-22&page%5Bnumber%5D=2&page%5Bsize%5D=2&start_date=2015-09-11",
"last": "https://api.leadfeeder.com/accounts/6002/leads?end_date=2015-09-22&page%5Bnumber%5D=2&page%5Bsize%5D=2&start_date=2015-09-11"
}
}
This endpoint retrieves list of leads in an Account on a specific time interval. The leads list can be filtered by specifying a custom feed. The total number of results is limited to the first 10000 leads.
HTTP Request
GET https://api.leadfeeder.com/accounts/<account_id>/leads?start_date=<date>&end_date=<date>
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| account_id | yes | Integer | ID of the Account for which to retrive the custom feeds |
| start_date | yes | Date (yyyy-mm-dd) | |
| end_date | yes | Date (yyyy-mm-dd) | |
| custom_feed_id | no | String | Limit leads to a custom feed. Default is all leads |
| page[number] | no | Integer | The page number for paginated response. Default is 1. |
| page[size] | no | Integer (1-100) | The number of leads to return per page. Default is 10. |
Response
Type: leads
| Attribute | Type | Description |
|---|---|---|
| name | String | Company name |
| industry | String | Name of industry |
| first_visit_date | Date (yyyy-mm-dd) | Date of first visit |
| status | String | [Deprecated] No longer used in the app and can be inferred from: assignee, emailed_to and crm_lead_id. “handled” - if any action has been done on this lead (e.g. assigned, emailed, sent to CRM) or “new” otherwise |
| last_visit_date | Date (yyyy-mm-dd) | Date of last visit |
| website_url | String | Company webpage address |
| phone | String | Company phone number |
| linkedin_url | String | Address of company’s Linkedin profile |
| twitter_handle | String | Company’s Twitter user handle |
| facebook_url | String | Company’s Facebook page address |
| employee_count | Integer | Estimate number of employees |
| employees_range | object | Latest available employee count information. A min value of 10_001, and max value being null means that the company has more than 10001 employees. Both min and max equal to null signify there is currently no available employee count information. |
| crm_lead_id | Integer | ID of the lead in the CRM |
| crm_organization_id | Integer | ID of the account/organization in the CRM |
| tags | Array | List of Lead tags |
| logo_url | String | URL to Company logo |
| assignee | String | Email of User assigned to Lead |
| business_id | String | Company business ID |
| revenue | String | Company revenue estimate |
| emailed_to | String | Comma separated list of emails the Lead has been sent to |
| view_in_leadfeeder | String | Link to lead within Leadfeeder app |
| visits | Integer | Number of visits in selected interval |
| quality | Integer (0-10) | Lead quality based on visits in selected interval |
Type: locations
| Attribute | Type | Description |
|---|---|---|
| country | String | Country name |
| country_code | String | Two letter country code (ISO 3166-1 alpha-2) |
| region | String | Name of the region |
| city | String | Name of the city |
| state_code | String | Two letter state code (US only) |
Get leads for custom feed
curl "https://api.leadfeeder.com/accounts/6002/custom-feeds/661122/leads?start_date=2015-09-01&end_date=2015-09-15"
-XGET
-H "Authorization: Token token=yourapitoken"
The above command returns JSON structured like this:
{
"data": [
{
"id": "400360f2-6131-11e5-90dc-638a476d8c19_6xeTMh2VfiAzFd86n7GNJ3",
"type": "leads",
"attributes": {
"name": "Leadfeeder Inc.",
"industry": "N/A",
"first_visit_date": "2015-09-18",
"status": "new",
"last_visit_date": "2015-09-21",
"website_url": "https://www.leadfeeder.com",
"phone": "+358504303422",
"linkedin_url": "https://www.linkedin.com/company/leadfeeder",
"twitter_handle": "Leadfeeder",
"facebook_url": "https://www.facebook.com/Leadfeeder",
"logo_url": "https://logos.leadfeeder.com/123/logo.png",
"assignee": null,
"business_id": null,
"revenue": null,
"emailed_to": null,
"view_in_leadfeeder": "https://app.leadfeeder.com/link/9088f1ad86",
"quality": 6,
"visits": 10
},
"relationships": {
"location": {
"data": {
"id": "6xeTMh2VfiAzFd86n7GNJ3",
"type": "locations"
}
}
}
},
{
"id": "40157512-6131-11e5-90dc-638a476d8c19_6xeTMh2VfiAzFd86n7GNJ3",
"type": "leads",
"attributes": {
"name": "Organic Mint",
"industry": "N/A",
"first_visit_date": "2015-09-18",
"status": "new",
"last_visit_date": "2015-09-21",
"website_url": "https://www.organicmint.com",
"phone": null,
"linkedin_url": null,
"twitter_handle": null,
"facebook_url": null,
"employee_count": 550,
"employees_range": { "min": 501, "max": 550 },
"crm_lead_id": 110,
"crm_organization_id": null,
"tags": ["tag1", "tag2"],
"logo_url": "https://logos.leadfeeder.com/123/logo.png",
"assignee": "user@company.com",
"business_id": "KVK Number 123",
"revenue": "EUR 395752792.0",
"emailed_to": "user@example.com,user@company.com",
"view_in_leadfeeder": "https://app.leadfeeder.com/link/9088f1ad85",
"quality": 4,
"visits": 15
},
"relationships": {
"location": {
"data": {
"id": "6xeTMh2VfiAzFd86n7GNJ3",
"type": "locations"
}
}
}
}
],
"included": [
{
"id": "6xeTMh2VfiAzFd86n7GNJ3",
"type": "locations",
"attributes": {
"country": "Finland",
"country_code": "FI",
"region": "Uusimaa",
"region_code": null,
"city": "Helsinki",
"state_code": null
}
}
],
"links": {
"self": "https://api.leadfeeder.com/accounts/6002/leads?end_date=2015-09-22&page%5Bnumber%5D=1&page%5Bsize%5D=10&start_date=2015-09-11",
"next": "https://api.leadfeeder.com/accounts/6002/leads?end_date=2015-09-22&page%5Bnumber%5D=2&page%5Bsize%5D=2&start_date=2015-09-11",
"last": "https://api.leadfeeder.com/accounts/6002/leads?end_date=2015-09-22&page%5Bnumber%5D=2&page%5Bsize%5D=2&start_date=2015-09-11"
}
}
This endpoint retrieves list of leads in an Account on a specific time interval and for given custom feed. The leads list can be filtered by specifying a custom feed. The total number of results is limited to the first 10000 leads.
HTTP Request
GET https://api.leadfeeder.com/accounts/<account_id>/custom-feeds/<custom_feed_id>/leads?start_date=<date>&end_date=<date>
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| account_id | yes | Integer | ID of the Account for which to retrive the custom feeds |
| custom_feed_id | yes | String | Limit leads to a custom feed |
| start_date | yes | Date (yyyy-mm-dd) | |
| end_date | yes | Date (yyyy-mm-dd) | |
| page[number] | no | Integer | The page number for paginated response. Default is 1. |
| page[size] | no | Integer (1-100) | The number of leads to return per page. Default is 10. |
Response
Type: leads
| Attribute | Type | Description |
|---|---|---|
| name | String | Company name |
| industry | String | Name of industry |
| first_visit_date | Date (yyyy-mm-dd) | Date of first visit |
| status | String | [Deprecated] No longer used in the app and can be inferred from: assignee, emailed_to and crm_lead_id. “handled” - if any action has been done on this lead (e.g. assigned, emailed, sent to CRM) or “new” otherwise |
| last_visit_date | Date (yyyy-mm-dd) | Date of last visit |
| website_url | String | Company webpage address |
| phone | String | Company phone number |
| linkedin_url | String | Address of company’s Linkedin profile |
| twitter_handle | String | Company’s Twitter user handle |
| facebook_url | String | Company’s Facebook page address |
| employee_count | Integer | Estimate number of employees |
| employees_range | object | Latest available employee count information. A min value of 10_001, and max value being null means that the company has more than 10001 employees. Both min and max equal to null signify there is currently no available employee count information. |
| crm_lead_id | Integer | ID of the lead in the CRM |
| crm_organization_id | Integer | ID of the account/organization in the CRM |
| tags | Array | List of Lead tags |
| logo_url | String | URL to Company logo |
| assignee | String | Email of User assigned to Lead |
| business_id | String | Company business ID |
| revenue | String | Company revenue estimate |
| emailed_to | String | Comma separated list of emails the Lead has been sent to |
| view_in_leadfeeder | String | Link to lead within Leadfeeder app |
| visits | Integer | Number of visits in selected interval |
| quality | Integer (0-10) | Lead quality based on visits in selected interval |
Type: locations
| Attribute | Type | Description |
|---|---|---|
| country | String | Country name |
| country_code | String | Two letter country code (ISO 3166-1 alpha-2) |
| region | String | Name of the region |
| city | String | Name of the city |
| state_code | String | Two letter state code (US only) |
Get a Specific Lead
curl "https://api.leadfeeder.com/accounts/6002/leads/25e7ccea-611b-11e5-b180-3b69e435d91d_7xeTMh2VfiAzFd86n7GNJ3"
-XGET
-H "Authorization: Token token=yourapitoken"
The above command returns JSON structured like this:
{
"data": {
"id": "25e7ccea-611b-11e5-b180-3b69e435d91d_7xeTMh2VfiAzFd86n7GNJ3",
"type": "leads",
"attributes": {
"name": "Leadfeeder Inc.",
"industry": "Computers & Internet",
"first_visit_date": "2015-09-18",
"status": "new",
"last_visit_date": "2015-09-21",
"website_url": "https://www.leadfeeder.com",
"phone": null,
"linkedin_url": "https://www.linkedin.com/company/leadfeeder",
"twitter_handle": "Leadfeeder",
"facebook_url": "https://www.facebook.com/Leadfeeder",
"employee_count": 22,
"employees_range": { "min": 1, "max": 22 },
"crm_lead_id": 11,
"crm_organization_id": "",
"tags": ["tag1", "tag2"],
"logo_url": "https://logos.leadfeeder.com/123/logo.png",
"assignee": "user@company.com",
"business_id": "KVK Number 123",
"revenue": "EUR 23423.0",
"emailed_to": "user@example.com,user@company.com",
"view_in_leadfeeder": "https://app.leadfeeder.com/link/9088f1ad85",
"visits": 45
},
"relationships": {
"location": {
"data": {
"id": "7xeTMh2VfiAzFd86n7GNJ3",
"type": "locations"
}
}
}
},
"included": [
{
"id": "7xeTMh2VfiAzFd86n7GNJ3",
"type": "locations",
"attributes": {
"country": "Finland",
"country_code": "FI",
"region": "Uusimaa",
"region_code": null,
"city": "Helsinki",
"state_code": null
}
}
]
}
This endpoint retrieves a specific Lead.
HTTP Request
GET https://api.leadfeeder.com/accounts/<account_id>/leads/<lead_id>
URL Parameters
| Parameter | Description |
|---|---|
| account_id | ID of the Account the custom feed belongs to |
| lead_id | ID of the lead to retrieve |
Response
Type: leads
| Attribute | Type | Description |
|---|---|---|
| name | String | Company name |
| industry | String | Name of industry |
| first_visit_date | Date (yyyy-mm-dd) | Date of first visit |
| status | String | [Deprecated] No longer used in the app and can be inferred from: assignee, emailed_to and crm_lead_id. “handled” - if any action has been done on this lead (e.g. assigned, emailed, sent to CRM) or “new” otherwise |
| last_visit_date | Date (yyyy-mm-dd) | Date of last visit |
| website_url | String | Company webpage address |
| phone | String | Company phone number |
| linkedin_url | String | Address of company’s Linkedin profile |
| twitter_handle | String | Company’s Twitter user handle |
| facebook_url | String | Company’s Facebook page address |
| employee_count | Integer | Estimate number of employees |
| employees_range | object | Latest available employee count information. A min value of 10_001, and max value being null means that the company has more than 10001 employees. Both min and max equal to null signify there is currently no available employee count information. |
| crm_lead_id | Integer | ID of the lead in the CRM |
| crm_organization_id | Integer | ID of the account/organization in the CRM |
| tags | Array | List of Lead tags |
| logo_url | String | URL to Company logo |
| assignee | String | Email of User assigned to Lead |
| business_id | String | Company business ID |
| revenue | String | Company revenue estimate |
| emailed_to | String | Comma separated list of emails the Lead has been sent to |
| view_in_leadfeeder | String | Link to lead within Leadfeeder app |
| visits | Integer | Total number of visits for lead |
Type: locations
| Attribute | Type | Description |
|---|---|---|
| country | String | Country name |
| country_code | String | Two letter country code (ISO 3166-1 alpha-2) |
| region | String | Name of the region |
| city | String | Name of the city |
| state_code | String | Two letter state code (US only) |
Visits
Get all visits of a lead
curl "https://api.leadfeeder.com/accounts/6002/leads/25e7ccea-611b-11e5-b180-3b69e435d91d_7xeTMh2VfiAzFd86n7GNJ3/visits?start_date=2015-09-01&end_date=2015-09-15"
-XGET
-H "Authorization: Token token=yourapitoken"
-g
The above command returns JSON structured like this:
{
"data": [
{
"id": "5b4f313e-46de-11e8-b981-05bebed8e58b",
"type": "visits",
"attributes": {
"source": "Top leads email",
"medium": "email",
"referring_url": null,
"page_depth": 1,
"visit_route": [
{
"hostname": "www.leadfeeder.com",
"page_path": "/",
"previous_page_path": "(entrance)",
"time_on_page": 0,
"page_title": "Website Visitor Tracking Software - Leadfeeder",
"page_url": "http://www.leadfeeder.com/",
"display_page_name": "/"
}
],
"keyword": null,
"visit_length": 0,
"started_at": "2018-04-13T06:23:00.000Z",
"campaign": null,
"date": "2018-04-12",
"hour": 23,
"lf_client_id": 1,
"ga_client_ids": [
"123.123"
],
"country_code": "US",
"device_type": "smartphone",
"lead_id": "xgLE1188E3o4T3NAs1rP2h_9xkc83iKW6BnBBGApPh2B1"
},
"relationships": {
"location": {
"data": {
"id": "6xeTMh2VfiAzFd86n7GNJ3",
"type": "locations"
}
}
}
},
{
"id": "0977b688-46de-11e8-a510-076914c6fac2",
"type": "visits",
"attributes": {
"source": "Google",
"medium": "cpc",
"referring_url": null,
"page_depth": 4,
"visit_route": [
{
"hostname": "www.leadfeeder.com",
"page_path": "/?campaignid=1",
"previous_page_path": "(entrance)",
"time_on_page": 18,
"page_title": "Website Visitor Tracking Software - Leadfeeder",
"page_url": "http://www.leadfeeder.com/?campaignid=1",
"display_page_name": "/?campaignid=1"
},
{
"hostname": "www.leadfeeder.com",
"page_path": "/?campaignid=2",
"previous_page_path": "/?campaignid=1",
"time_on_page": 40,
"page_title": "Website Visitor Tracking Software - Leadfeeder",
"page_url": "http://www.leadfeeder.com/?campaignid=2",
"display_page_name": "/?campaignid=2"
},
{
"hostname": "www.leadfeeder.com",
"page_path": "/pricing/",
"previous_page_path": "/?campaignid=2",
"time_on_page": 22,
"page_title": "Pricing for all stages of growth",
"page_url": "http://www.leadfeeder.com/pricing/",
"display_page_name": "/pricing/"
},
{
"hostname": "www.leadfeeder.com",
"page_path": "/product/",
"previous_page_path": "/pricing/",
"time_on_page": 0,
"page_title": "Lead Generation for Marketing Teams - Leadfeeder",
"page_url": "http://www.leadfeeder.com/product/",
"display_page_name": "/product/"
}
],
"keyword": "website leads",
"query_term": "how to get fresh leads to my website",
"visit_length": 80,
"started_at": "2018-04-11T20:22:00.000Z",
"campaign": "HomePage Split",
"date": "2018-04-11",
"hour": 13,
"lf_client_id": 2,
"country_code": "US",
"device_type": "smartphone",
"lead_id": "bJurQFBGKMfJLqP4JEGFLm_p6q3nDbB2C4m9KjK9gndy",
"adobe_cookies": [
{
"MCMID":"681245",
"MCAAMB":"RKh123Vc5",
"MCAAMLH":"6"
}
]
},
"relationships": {
"location": {
"data": {
"id": "6xeTMh2VfiAzFd86n7GNJ3",
"type": "locations"
}
}
}
}
],
"included": [
{
"id": "6xeTMh2VfiAzFd86n7GNJ3",
"type": "locations",
"attributes": {
"country": "Finland",
"country_code": "FI",
"region": "Uusimaa",
"region_code": null,
"city": "Helsinki",
"state_code": null
}
}
]
}
This endpoint retrieves list of Visits for a Lead from a specific time interval.
HTTP Request
GET https://api.leadfeeder.com/accounts/<account_id>/leads/<lead_id>/visits?start_date=<date>&end_date=<date>
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| account_id | yes | Integer | ID of the Account |
| lead_id | yes | String | ID of the Lead for which to retrive the visits |
| start_date | yes | Date (yyyy-mm-dd) | |
| end_date | yes | Date (yyyy-mm-dd) | |
| page[number] | no | Integer | The page number for paginated response. Default is 1. |
| page[size] | no | Integer (1-100) | The number of visits to return per page. Default is 10. |
Response
Type: visits
| Attribute | Type | Description |
|---|---|---|
| source | String | Referrer traffic source (e.g. Facebook) |
| medium | String | Referrer traffic medium (e.g. CPC) |
| campaign | String | Value of the utm_campaign or name of AdWords campaign |
| referring_url | String | Referrer URL |
| country_code | String | [Deprecated] ISO 3166-1 alpha-2 country code |
| page_depth | Integer | Number of page views the visit contains |
| visit_route | Array | Array of Hashes describing the visit route. |
| keyword | String | Referrer keyword (search engine search phrase) |
| query_term | String | [Deprecated] Search query triggering the AdWords campaign |
| visit_length | Integer | Duration of the visit in seconds |
| started_at | Datetime (ISO8601) | Datetime when the visit happened, rounded to minutes |
| date | Date | [Deprecated] Date when the visit happened |
| hour | Integer (0-23) | [Deprecated] The wall-clock hour when the visit happened (in Account timezone) |
| lead_id | String | ID of a Lead this visit belongs to |
| lf_client_id | String | Visitor’s ID as seen by Leadfeeder |
| ga_client_ids | Array | Visitor IDs as seen by Google Analytics |
| adobe_cookies | Array | Visitor’s Adobe cookies with MCMID, MCAAMB and MCAAMLH. Present only when Adobe cookie extraction is enabled and visitor has Adobe cookies present in browser. For more details about Adobe cookies see https://experienceleague.adobe.com/docs/id-service/using/intro/cookies.html?lang=en and https://experienceleague.adobe.com/docs/id-service/using/id-service-api/methods/getvisitorvalues.html?lang=en |
| device_type | String | Identified device type (e.g. “smartphone”) |
visit_route sub-type:
| Attribute | Type | Description |
|---|---|---|
| hostname | String | Hostname of the visited page |
| page_path | String | Path part of the visited page URL |
| previous_page_path | String | Path of previous visited page or “(entrance)” |
| time_on_page | Integer | Time spent on page in seconds. |
| page_title | String | Title of the visited page |
| display_page_name | String | Page name displayed as specified in Leadfeeder settings. Either path, full url or title. |
Type: locations
| Attribute | Type | Description |
|---|---|---|
| country | String | Country name |
| country_code | String | Two letter country code (ISO 3166-1 alpha-2) |
| region | String | Name of the region |
| city | String | Name of the city |
| state_code | String | Two letter state code (US only) |
Get all visits
curl "https://api.leadfeeder.com/accounts/6002/visits?start_date=2015-09-01&end_date=2015-09-15"
-XGET
-H "Authorization: Token token=yourapitoken"
-g
The above command returns JSON structured like this:
{
"data": [
{
"id": "5b4f313e-46de-11e8-b981-05bebed8e58b",
"type": "visits",
"attributes": {
"source": "Top leads email",
"medium": "email",
"referring_url": null,
"page_depth": 1,
"visit_route": [
{
"hostname": "www.leadfeeder.com",
"page_path": "/",
"previous_page_path": "(entrance)",
"time_on_page": 0,
"page_title": "Website Visitor Tracking Software - Leadfeeder",
"page_url": "http://www.leadfeeder.com/",
"display_page_name": "/"
}
],
"keyword": null,
"visit_length": 0,
"started_at": "2018-04-13T06:23:00.000Z",
"campaign": null,
"date": "2018-04-12",
"hour": 23,
"lf_client_id": 1,
"ga_client_ids": [
"123.123"
],
"country_code": "US",
"device_type": "smartphone",
"lead_id": "xgLE1188E3o4T3NAs1rP2h_9xkc83iKW6BnBBGApPh2B1"
},
"relationships": {
"location": {
"data": {
"id": "6xeTMh2VfiAzFd86n7GNJ3",
"type": "locations"
}
}
}
},
{
"id": "0977b688-46de-11e8-a510-076914c6fac2",
"type": "visits",
"attributes": {
"source": "Google",
"medium": "cpc",
"referring_url": null,
"page_depth": 4,
"visit_route": [
{
"hostname": "www.leadfeeder.com",
"page_path": "/?campaignid=1",
"previous_page_path": "(entrance)",
"time_on_page": 18,
"page_title": "Website Visitor Tracking Software - Leadfeeder",
"page_url": "http://www.leadfeeder.com/?campaignid=1",
"display_page_name": "/?campaignid=1"
},
{
"hostname": "www.leadfeeder.com",
"page_path": "/?campaignid=2",
"previous_page_path": "/?campaignid=1",
"time_on_page": 40,
"page_title": "Website Visitor Tracking Software - Leadfeeder",
"page_url": "http://www.leadfeeder.com/?campaignid=2",
"display_page_name": "/?campaignid=2"
},
{
"hostname": "www.leadfeeder.com",
"page_path": "/pricing/",
"previous_page_path": "/?campaignid=2",
"time_on_page": 22,
"page_title": "Pricing for all stages of growth",
"page_url": "http://www.leadfeeder.com/pricing/",
"display_page_name": "/pricing/"
},
{
"hostname": "www.leadfeeder.com",
"page_path": "/product/",
"previous_page_path": "/pricing/",
"time_on_page": 0,
"page_title": "Lead Generation for Marketing Teams - Leadfeeder",
"page_url": "http://www.leadfeeder.com/product/",
"display_page_name": "/product/"
}
],
"keyword": "website leads",
"query_term": "how to get fresh leads to my website",
"visit_length": 80,
"started_at": "2018-04-11T20:22:00.000Z",
"campaign": "HomePage Split",
"date": "2018-04-11",
"hour": 13,
"lf_client_id": 2,
"country_code": "US",
"device_type": "smartphone",
"lead_id": "bJurQFBGKMfJLqP4JEGFLm_p6q3nDbB2C4m9KjK9gndy",
"adobe_cookies": [
{
"MCMID":"681245",
"MCAAMB":"RKh123Vc5",
"MCAAMLH":"6"
}
]
},
"relationships": {
"location": {
"data": {
"id": "6xeTMh2VfiAzFd86n7GNJ3",
"type": "locations"
}
}
}
}
],
"included": [
{
"id": "6xeTMh2VfiAzFd86n7GNJ3",
"type": "locations",
"attributes": {
"country": "Finland",
"country_code": "FI",
"region": "Uusimaa",
"region_code": null,
"city": "Helsinki",
"state_code": null
}
}
]
}
This endpoint retrieves list of Visits for all Leads from a specific time interval.
HTTP Request
GET https://api.leadfeeder.com/accounts/<account_id>/visits?start_date=<date>&end_date=<date>
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| account_id | yes | Integer | ID of the Account |
| start_date | yes | Date (yyyy-mm-dd) | |
| end_date | yes | Date (yyyy-mm-dd) | |
| page[number] | no | Integer | The page number for paginated response. Default is 1. |
| page[size] | no | Integer (1-100) | The number of leads to return per page. Default is 10. |
Response
Type: visits
| Attribute | Type | Description |
|---|---|---|
| source | String | Referrer traffic source (e.g. Facebook) |
| medium | String | Referrer traffic medium (e.g. CPC) |
| campaign | String | Value of the utm_campaign or name of AdWords campaign |
| referring_url | String | Referrer URL |
| country_code | String | [Deprecated] ISO 3166-1 alpha-2 country code |
| page_depth | Integer | Number of page views the visit contains |
| visit_route | Array | Array of Hashes describing the visit route. |
| keyword | String | Referrer keyword (search engine search phrase) |
| query_term | String | [Deprecated] Search query triggering the AdWords campaign |
| visit_length | Integer | Duration of the visit in seconds |
| started_at | Datetime (ISO8601) | Datetime when the visit happened, rounded to minutes |
| date | Date | [Deprecated] Date when the visit happened |
| hour | Integer (0-23) | [Deprecated] The wall-clock hour when the visit happened (in Account timezone) |
| lead_id | String | ID of a Lead this visit belongs to |
| lf_client_id | String | Visitor’s ID as seen by Leadfeeder |
| ga_client_ids | Array | Visitor IDs as seen by Google Analytics |
| adobe_cookies | Array | Visitor’s Adobe cookies with MCMID, MCAAMB and MCAAMLH. Present only when Adobe cookie extraction is enabled and visitor has Adobe cookies present in browser. For more details about Adobe cookies see https://experienceleague.adobe.com/docs/id-service/using/intro/cookies.html?lang=en and https://experienceleague.adobe.com/docs/id-service/using/id-service-api/methods/getvisitorvalues.html?lang=en |
| device_type | String | Identified device type (e.g. “smartphone”) |
visit_route sub-type:
| Attribute | Type | Description |
|---|---|---|
| hostname | String | Hostname of the visited page |
| page_path | String | Path part of the visited page URL |
| previous_page_path | String | Path of previous visited page or “(entrance)” |
| time_on_page | Integer | Time spent on page in seconds. |
| page_title | String | Title of the visited page |
| display_page_name | String | Page name displayed as specified in Leadfeeder settings. Either path, full url or title. |
Type: locations
| Attribute | Type | Description |
|---|---|---|
| country | String | Country name |
| country_code | String | Two letter country code (ISO 3166-1 alpha-2) |
| region | String | Name of the region |
| city | String | Name of the city |
| state_code | String | Two letter state code (US only) |
Exporting feeds
The export-requests service is intended for mass exporting all leads or leads from
user defined custom feed.
Due to the time taken to produce this report, you need to:
- Submit a request for a report to be created.
- Check on the status of the report.
- When it is ready, download it.
Request a feed export
curl -XPOST \
-H "Authorization: Token token=yourapitoken" \
-d "account_id=6002" \
-d "custom_feed_id=all_leads" \
-d "start_date=2015-07-01" \
-d "end_date=2015-07-14" \
"https://api.leadfeeder.com/export-requests"
The above command returns JSON structured like this:
{
"data": {
"id": "06ac7d56-34fe-11e5-8094-4fbabdb782e1",
"type": "export_requests",
"attributes": {
"status": "pending",
"created_at": "2015-07-28T07:55:34Z",
"status_url": "https://api.leadfeeder.com/export-feed/06ac7d56-34fe-11e5-8094-4fbabdb782e1",
"download_url": null
}
}
}
When the Export requests limit is exceeded the above command returns a
429 Too Many Requestsstatus code and a body with JSON structured like this:
{
"errors": [
{
"title": "Exceeded the Export requests rate limit of 5 requests per minute. Try again later.",
"links": {
"about": "http://docs.leadfeeder.com/api/#exporting-feeds"
}
}
]
}
HTTP Request
POST https://api.leadfeeder.com/export-requests
URL Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
| account_id | yes | Integer | The ID if the account you wish the generate the report from |
| end_date | yes | Date (yyyy-mm-dd) | End date |
| custom_feed_id | yes | String | The ID if the feed you wish the generate the report from |
| start_date | yes | Date (yyyy-mm-dd) | Start date |
Response
Response type: export_requests
Response attributes
| Attribute | Type | Description |
|---|---|---|
| created_at | Datetime | Timestamp when the request was created |
| download_url | URL | URL from which to download the completed report. null unless status is processed. |
| status | String | The status of the request. Either pending, processed or failed. |
| status_url | URL | URL for requesting the status |
Feed export status
curl "https://api.leadfeeder.com/export-requests/06ac7d56-34fe-11e5-8094-4fbabdb782e1"
-XGET
-H "Authorization: Token token=yourapitoken "
The above command returns JSON structured like this:
{
"data": {
"id": "06ac7d56-34fe-11e5-8094-4fbabdb782e1",
"type": "export_requests",
"attributes": {
"status": "processed",
"created_at": "2015-07-28T07:55:34+00:00",
"status_url": "https://api.leadfeeder.com/export-feed/06ac7d56-34fe-11e5-8094-4fbabdb782e1",
"download_url": "https://api.leadfeeder.com/download/ee9de62d-d54b-4cd6-a703-77217a399dbf.json"
}
}
}
This endpoint will tell you the status of your feed export request. The status might be pending, failed or processed. When the request has been processed, a download_url will be included.
HTTP Request
GET https://api.leadfeeder.com/export-requests/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of export request |
Response
Response type: export_requests
Response attributes
| Attribute | Type | Description |
|---|---|---|
| created_at | Datetime | Timestamp when the request was created |
| download_url | URL | URL from which to download the completed report. null unless status is processed. |
| status | String | The status of the request. Either pending, processed or failed. |
| status_url | URL | URL for requesting the status |
Downloading the report
The once the request is processed (request status is processed) the report
can be downloaded using the URL provided in the download_url attribute.
Sample report
curl -XGET "https://api.leadfeeder.com/download/ee9de62d-d54b-4cd6-a703-77217a399dbf.json"
{
"data": [
{
"attributes": {
"keywords": [],
"quality": 2,
"stats": {
"bounces": 3,
"last_visit": "2015-07-14",
"pageviews": 5,
"visits": 4
}
},
"id": "abcdef|ghijk",
"relationships": {
"lead": {
"data": {
"id": "abcdef|ghijk",
"type": "leads"
}
}
},
"type": "timeline_rows"
},
{
"attributes": {
"keywords": [],
"quality": 1,
"stats": {
"bounces": 5,
"last_visit": "2015-07-14",
"pageviews": 5,
"visits": 5
}
},
"id": "ab1234|cd1234",
"relationships": {
"lead": {
"data": {
"id": "ab1234|cd1234",
"type": "leads"
}
}
},
"type": "timeline_rows"
}
],
"included": [
{
"attributes": {
"first_visit_date": "2015-07-01",
"industry": "N/A",
"last_visit_date": "2015-07-01",
"name": "Leadfeeder Inc.",
"status": "new",
"website_url": "https://www.leadfeeder.com",
"linkedin_url": "https://www.linkedin.com/company/leadfeeder",
"twitter_handle": "Leadfeeder",
"facebook_url": "https://www.facebook.com/Leadfeeder"
},
"id": "abcdef|ghijk",
"relationships": {
"location": {
"data": {
"id": "ghijk",
"type": "locations"
}
}
},
"type": "leads"
},
{
"attributes": {
"city": "Helsinki",
"country": "Finland",
"country_code": "FI",
"region": "Uusimaa",
"region_code": null,
"state_code": null
},
"id": "ghijk",
"type": "locations"
}
]
}
HTTP Request
GET https://api.leadfeeder.com/download/<unique_filename>
URL Parameters
| Parameter | Description |
|---|---|
| unique_filename | The unique filename generated for your report |
Types in response
Type: feed_items
| Attribute | Type | Description |
|---|---|---|
| keywords | Array | Search terms used by the lead to find your website |
| quality | Integer | Quality score calculated by Leadfeeder. Ranges from 1 to 10. |
| stats | Hash | Statistics for the lead on the interval. Includes bounces, last_visit, pageviews and visits. |
| Relationship | Included | Description |
|---|---|---|
| leads | yes | The lead related to the row |
Type: leads
| Attribute | Type | Description |
|---|---|---|
| first_visit_date | Date | Date when the lead first visited |
| industry | String | lead’s industry (N/A if not available) |
| last_visit_date | Date | Date when the lead last visited |
| name | String | Name of the lead |
| status | String | Status of the lead in Leadfeeder. Either new or handled |
| website_url | String | Website URL of the lead (null if not available) |
| linkedin_url | String | LinkedIn URL of the lead (null if not available) |
| twitter_handle | String | Twitter user handle associated with the lead (null if not available) |
| facebook_url | String | Facebook page URL associated with the lead (null if not available) |
| Relationship | Included | Description |
|---|---|---|
| location | yes | The geographical location of the lead |
Type: locations
| Attribute | Type | Description |
|---|---|---|
| city | String | Name of the city |
| country | Date | Name of the country in English |
| country_code | String | ISO 3166-1 alpha-2 country code |
| region | String | Name of the region. |
| region_code | null | Currently not used |
| state_code | String | Two letter state code for US locations |
Errors
Leadfeeder API uses HTTP response codes to indicate request success or failure reason.
In addition to the response code, the response body contains an error message formatted according to the JSON API error guidelines
Error codes in use are:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request – The request contains wrong or incorrectly formatted arguments. |
| 401 | Unauthorized – The API token used is incorrect. |
| 402 | Premium required – Account does not have Leadfeeder Premium subscription. |
| 403 | Forbidden – The user whose API token is used does not have required privileges to the resource or the token has been disabled. |
| 404 | Not Found – The resource was not found. |
| 429 | Too Many Requests – The limit of the number of requests per minute has been exceeded. |
| 500 | Internal Server Error – There was an error processing the request. |