NAV
curl

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 Requests status 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 name and employee_count attributes for lead objects and country for 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",
                "industries": [{ "name": "Technology, Information and Internet" }, { "name": "Software Development" }],
                "first_visit_date": "2015-09-18",
                "status": "new",
                "dealfront_id": "VqNyvp8Bwz",
                "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",
                "industries": [{ "name": "Market Research" }, { "name": "Public Relations and Communications Services" }],
                "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 (based on legacy industry classification)
industries Array List of industries (based on updated industry classification)
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
dealfront_id String ID of the company in Dealfront
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",
                "industries": [{ "name": "Technology, Information and Internet" }, { "name": "Software Development" }],
                "first_visit_date": "2015-09-18",
                "status": "new",
                "dealfront_id": "VqNyvp8Bwz",
                "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",
                "industries": [{ "name": "Market Research" }, { "name": "Public Relations and Communications Services" }],
                "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 (based on legacy industry classification)
industries Array List of industries (based on updated industry classification)
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
dealfront_id String ID of the company in Dealfront
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",
            "industries": [{ "name": "Technology, Information and Internet" }, { "name": "Software Development" }],
            "first_visit_date": "2015-09-18",
            "status": "new",
            "dealfront_id": "VqNyvp8Bwz",
            "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 (based on legacy industry classification)
industries Array List of industries (based on updated industry classification)
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
dealfront_id String ID of the company in Dealfront
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:

  1. Submit a request for a report to be created.
  2. Check on the status of the report.
  3. 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 Requests status 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.