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 Leadfeeder Premium account which has access to the Google Analytics profile of the website you wish to explore the visitors from. If you’re not already using Leadfeeder, you can sign up for a 14-day premium trial on our website.

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

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",
                "linkedin_url": "https://www.linkedin.com/company/leadfeeder"
            },
            "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",
                "linkedin_url": null,
                "employee_count": 550
            },
            "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 “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
linkedin_url String Address of company’s linkedin profile
employee_count Integer Estimate number of employees

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",
            "linkedin_url": "https://www.linkedin.com/company/leadfeeder",
            "employee_count": 22
        },
        "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 “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
linkedin_url String Address of company’s linkedin profile
employee_count Integer Estimate number of employees

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,
                "lead_id": "xgLE1188E3o4T3NAs1rP2h_9xkc83iKW6BnBBGApPh2B1"
            }
        },
        {
            "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",
                "visit_length": 80,
                "started_at": "2018-04-11T20:22:00.000Z",
                "campaign": "HomePage Split",
                "date": "2018-04-11",
                "hour": 13,
                "lead_id": "bJurQFBGKMfJLqP4JEGFLm_p6q3nDbB2C4m9KjK9gndy"
            }
        }
    ]
}

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 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
page_depth Date 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)
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

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.

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,
                "lead_id": "xgLE1188E3o4T3NAs1rP2h_9xkc83iKW6BnBBGApPh2B1"
            }
        },
        {
            "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",
                "visit_length": 80,
                "started_at": "2018-04-11T20:22:00.000Z",
                "campaign": "HomePage Split",
                "date": "2018-04-11",
                "hour": 13,
                "lead_id": "bJurQFBGKMfJLqP4JEGFLm_p6q3nDbB2C4m9KjK9gndy"
            }
        }
    ]
}

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
page_depth Date 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)
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

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.

Get visits for custom feed leads

curl "https://api.leadfeeder.com/accounts/15186/custom-feeds/78ecd432-eae2-11e7-9189-2514b69fbed3/visits?page[leads]=50&page[number]=0&start_date=2018-03-19&end_date=2018-04-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,
                "lead_id": "xgLE1188E3o4T3NAs1rP2h_9xkc83iKW6BnBBGApPh2B1"
            }
        },
        {
            "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",
                "visit_length": 80,
                "started_at": "2018-04-11T20:22:00.000Z",
                "campaign": "HomePage Split",
                "date": "2018-04-11",
                "hour": 13,
                "lead_id": "bJurQFBGKMfJLqP4JEGFLm_p6q3nDbB2C4m9KjK9gndy"
            }
        }
    ]
}

This endpoint retrieves a list of Visits for all Leads from a specific time interval and in selected custom feed. Please note that because of technical restrictions this endpoint’s pagination is different from the others.

HTTP Request

GET https://api.leadfeeder.com/accounts/<account_id>/custom-feeds/<custom_feed_id>?start_date=<date>&end_date=<date>

URL Parameters

Parameter Required Type Description
account_id yes Integer ID of the Account
custom_feed_id yes String ID of the Custom feed (for all leads feed pass “all_leads”)
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[leads] no Integer (1-100) Visits of how many leads should be returned 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
page_depth Date 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)
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

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.

Exporting feeds

The export-requests service is intened 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 attrbutes

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 attrbutes

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"
      },
      "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)
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.
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.