Leady API

We welcome any feedback on the API or its documentation. For contacts see below. Thank you!

Why Open API?

We believe our clients have the right to be fully in charge of all their data collected by Leady. And because effortless use and seamless integration is our priority, we introduce Open API.

So our clients can review all session and actions we (Leady) collected on their behalf. Also, details on referenced companies and persons can be reached. Some additional technical stuff is readable. Later we provide tools to filter and manage the data.

The communication is based on the standard HTTP and JSON protocols, a simple, powerful and fully open tools.

Authentication

We provide each user with an individual, secret, long-lasting access token that can be requested by the api-token-get call below. Your registered e-mail address and valid password needs to be provided with this call.

In case you want to reset you token, for example when it leaks out of your control, use the api-token-reset call to regenerate a new random value. However please note, that all present accesses will be lost instantly.

Live interaction

First, get your token using the INTERACT button in the api-token-get call, fill in your Email and Password, click SEND REQUEST and save the resulting token.

Second, expand the Authentication tab on the bottom of the sidebar, click token, paste the token to the Token line and submit. From now on, until you reload the page, you can use the calls that require the Authorization header.

Time

Please note that all time values are in UTC. You are responsible for the conversion from and to your time zone.

Pagination

Sometimes you would get too many output records in a single response. In this case, the cursor-based pagination is used for best performance. Provided the previous or next page of results exist, use the appropriate link in your list response to retrieve it.

Throttling

If your application goes a little wild and calls the Leady API too often, it might get throttled. That is to say, once the HTTP Response Code is 429, the client should cease requesting for the number of seconds found in the Retry-After header of the response.

The limits are set individually for different types of data.

If you run into this during your normal work, please contact us to sort it out.

Contact

Anytime you experience an issue regarding API or its documentation, or in case you find out some missing functionality, do not hesitate to let us know. We would also love to hear your tips or just chat with you.

Please contact us via info@leady.com

# For your convenience we offer examples
# based on the ubiquitous curl tool:
$ curl "https://api.leady.com/v1/" \
  -X "GET" \
  -H "Authorization: Token {your_access_token}" \
  -H "Content-type: application/json; charset=utf-8"

Except for the api-token-get call, the Authorization header is mandatory.

# Install the Python client library
$ pip install coreapi

<!-- Load the JavaScript client library -->
<script src="//impr.cz/s/leady/rest_framework/js/coreapi-0.1.1.js"></script>
<script src="/schema.js"></script>

api-token-get

read

POST /v1/api-token-get/

In exchange to your login credentials (e-mail and password) returns your individual access API token.

Usage is limited to 20 requests per hour.

Request Body

The request body should be a "application/json" encoded object, containing the following items.

Parameter	Description
`email` required	E-mail address you use to login to your Leady account
`password` required	Your Leady password

Example request

$ curl 'https://api.leady.com/v1/api-token-get/' \
  -H 'Content-type: application/json; charset=utf-8' \
  -X 'POST' \
  -d '{
          "email": "...",
          "password": "..."
      }'

import coreapi

# Initialize a client & load the schema document
client = coreapi.Client()
schema = client.get("https://api.leady.com/")

# Interact with the API endpoint
action = ["api-token-get", "create"]
params = {
    "email": ...,
    "password": ...,
}
result = client.action(schema, action, params=params)

var coreapi = window.coreapi  // Loaded by `coreapi.js`
var schema = window.schema    // Loaded by `schema.js`

// Initialize a client
var client = new coreapi.Client()

// Interact with the API endpoint
var action = ["api-token-get", "create"]
var params = {
    email: ...,
    password: ...,
}
client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
})

api-token-reset

reset

POST /v1/api-token-reset/

Resets your individual access API token to a new random value that is also returned.

Usage is limited to 20 requests per hour.

Request Body

The request body should be a "application/json" encoded object, containing the following items.

Parameter	Description
`email` required	E-mail address you use to login to your Leady account
`password` required	Your Leady password

Example request

$ curl 'https://api.leady.com/v1/api-token-reset/' \
  -H 'Content-type: application/json; charset=utf-8' \
  -X 'POST' \
  -d '{
          "email": "...",
          "password": "..."
      }'

import coreapi

# Initialize a client & load the schema document
client = coreapi.Client()
schema = client.get("https://api.leady.com/")

# Interact with the API endpoint
action = ["api-token-reset", "create"]
params = {
    "email": ...,
    "password": ...,
}
result = client.action(schema, action, params=params)

var coreapi = window.coreapi  // Loaded by `coreapi.js`
var schema = window.schema    // Loaded by `schema.js`

// Initialize a client
var client = new coreapi.Client()

// Interact with the API endpoint
var action = ["api-token-reset", "create"]
var params = {
    email: ...,
    password: ...,
}
client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
})

resources

list

GET /v1/resources/

All the resources (websites) you have access to are returned.

Usage is limited to 100 requests per day.

Query Parameters

The following parameters belong to the URL query string.

Parameter	Description
`cursor`	Pagination cursor (optional)

Response Fields

The meaning of each key in the resulting object(s) is as follows:

Field	Description
`domain`	Domain name of the tracked website without the leading 'www.', lower cased. If it starts with the dot, all subdomains (not just 'www') will be tracked as well.
`status`	Current resource status: waiting (no visits yet), active, expired, no-expire
`partner_code`	Special partner code from prior to website registration, if given.
`csv_secret`	Secret key to access the daily export CSV files via special URL.
`timeout_days_contacted`	Contacted status validity days
`timeout_days_won`	Won status validity days
`timeout_days_lost`	Lost status validity days
`territories`	Territories currently active on this resource. Contact us to enable more.
`form_tracker_enabled`	Is automatic form submission tracking enabled?
`session_list_url`	Link to this resource's session listing
`saved_filters_url`	Link to this resource's saved filter listing

Example request

$ curl 'https://api.leady.com/v1/resources/' \
  -H 'Authorization: Token {your_access_token}' \
  -H 'Content-type: application/json; charset=utf-8' \
  -X 'GET'

import coreapi

# Initialize a client & load the schema document
client = coreapi.Client()
schema = client.get("https://api.leady.com/")

# Interact with the API endpoint
action = ["resources", "list"]
params = {
    "cursor": ...,
}
result = client.action(schema, action, params=params)

var coreapi = window.coreapi  // Loaded by `coreapi.js`
var schema = window.schema    // Loaded by `schema.js`

// Initialize a client
var client = new coreapi.Client()

// Interact with the API endpoint
var action = ["resources", "list"]
var params = {
    cursor: ...,
}
client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
})

read

GET /v1/resources/{domain}/

A single resource (website) by domain is returned.

Usage is limited to 100 requests per day.

Path Parameters

The following parameters make up the URL path:

Parameter	Description
`domain` required

Response Fields

Same as above.

Example request

$ curl 'https://api.leady.com/v1/resources/{domain}/' \
  -H 'Authorization: Token {your_access_token}' \
  -H 'Content-type: application/json; charset=utf-8' \
  -X 'GET'

import coreapi

# Initialize a client & load the schema document
client = coreapi.Client()
schema = client.get("https://api.leady.com/")

# Interact with the API endpoint
action = ["resources", "read"]
params = {
    "domain": ...,
}
result = client.action(schema, action, params=params)

var coreapi = window.coreapi  // Loaded by `coreapi.js`
var schema = window.schema    // Loaded by `schema.js`

// Initialize a client
var client = new coreapi.Client()

// Interact with the API endpoint
var action = ["resources", "read"]
var params = {
    domain: ...,
}
client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
})

sessions

list

GET /v1/resources/{domain}/sessions/

Returns the sessions (leads) bound to given resource that started in the given time frame (last 30 days if you don't specify any boundaries).

The listing of sessions is in order in which they occurred.

Currently, sessions get created either by person (e-mail) or by company access. The person itself might also be identified to belong to some company, but that's still a person-type session.

Usage is limited to 600 requests per hour and resource.

Path Parameters

The following parameters make up the URL path:

Parameter	Description
`domain` required

Query Parameters

The following parameters belong to the URL query string.

Parameter	Description
`cursor`	Pagination cursor (optional)
`period_start`	The UTC date/time from which you are interested in sessions. Examples: 2017-1-1 or 2017-1-1 8:00:00
`period_end`	The UTC date/time up to which you are interested in sessions.
`seconds_spent_min`	Filter sessions having at least this number of seconds.
`seconds_spent_max`	Filter sessions having at most this number of seconds.
`action_count_min`	Filter sessions having at least this number of actions.
`action_count_max`	Filter sessions having at most this number of actions.
`session_type`	Filter only 'person' or 'company' sessions.
`saved_filter_id`	Apply the advanced filter you previously saved for this resource through the Leady web application.

Response Fields

The meaning of each key in the resulting object(s) is as follows:

Field	Description
`session_type`	Session type: 'person' or 'company'
`company`	Short version of company structure (with link to full info) if company is known, `null` otherwise
`person`	E-mail address and link to full info about person if known, `null` otherwise
`first_timestamp`	Timestamp of first action (session start)
`last_timestamp`	Timestamp of last action (session end)
`referrer`	Session referrer URL if known, empty otherwise
`search_engine_query`	Keywords typed by the user if found in the referrer, `null` if not
`action_count`	Total number of actions recorded in this session
`seconds_spent`	Total number of seconds the user spent on this session
`action_list_url`	Link to this session's list of actions
`id`	Primary key identifier

Example request

$ curl 'https://api.leady.com/v1/resources/{domain}/sessions/' \
  -H 'Authorization: Token {your_access_token}' \
  -H 'Content-type: application/json; charset=utf-8' \
  -X 'GET'

import coreapi

# Initialize a client & load the schema document
client = coreapi.Client()
schema = client.get("https://api.leady.com/")

# Interact with the API endpoint
action = ["sessions", "list"]
params = {
    "domain": ...,
    "cursor": ...,
    "period_start": ...,
    "period_end": ...,
    "seconds_spent_min": ...,
    "seconds_spent_max": ...,
    "action_count_min": ...,
    "action_count_max": ...,
    "session_type": ...,
    "saved_filter_id": ...,
}
result = client.action(schema, action, params=params)

var coreapi = window.coreapi  // Loaded by `coreapi.js`
var schema = window.schema    // Loaded by `schema.js`

// Initialize a client
var client = new coreapi.Client()

// Interact with the API endpoint
var action = ["sessions", "list"]
var params = {
    domain: ...,
    cursor: ...,
    period_start: ...,
    period_end: ...,
    seconds_spent_min: ...,
    seconds_spent_max: ...,
    action_count_min: ...,
    action_count_max: ...,
    session_type: ...,
    saved_filter_id: ...,
}
client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
})

read

GET /v1/resources/{domain}/sessions/{session_id}/

Get the list of actions (roughly page views) bound to given session.

Usage is limited to 600 requests per hour and resource.

Path Parameters

The following parameters make up the URL path:

Parameter	Description
`domain` required
`session_id` required

Response Fields

The meaning of each key in the resulting object(s) is as follows:

Field	Description
`action_timestamp`	Action timestamp
`seconds_spent`	Number of seconds the user spent on the page if known
`location`	Location URL with query string
`category`	Action category: pageview, identify or event (generic)
`action`	Action value or identification e-mail
`label`	Action details if provided
`value`	Action numeric details if provided, `null` otherwise

Example request

$ curl 'https://api.leady.com/v1/resources/{domain}/sessions/{session_id}/' \
  -H 'Authorization: Token {your_access_token}' \
  -H 'Content-type: application/json; charset=utf-8' \
  -X 'GET'

import coreapi

# Initialize a client & load the schema document
client = coreapi.Client()
schema = client.get("https://api.leady.com/")

# Interact with the API endpoint
action = ["sessions", "read"]
params = {
    "domain": ...,
    "session_id": ...,
}
result = client.action(schema, action, params=params)

var coreapi = window.coreapi  // Loaded by `coreapi.js`
var schema = window.schema    // Loaded by `schema.js`

// Initialize a client
var client = new coreapi.Client()

// Interact with the API endpoint
var action = ["sessions", "read"]
var params = {
    domain: ...,
    session_id: ...,
}
client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
})

companies

read

GET /v1/companies/{id}/{secure_token}/

Returns the full company profile.

This call is protected by an individual token and is to be accessed directly from the sessions list call.

Usage is limited to 320 requests per hour.

Path Parameters

The following parameters make up the URL path:

Parameter	Description
`id` required
`secure_token` required

Response Fields

The meaning of each key in the resulting object(s) is as follows:

Field	Description
`id`	Primary key identifier
`regno`	Registration number for CZ/SK companies (numeric value)
`regno_str`	Registration number for CZ/SK companies
`name`	Business name
`territory`	Territory under which the company is listed
`email`	Business e-mail
`website`	Company homepage URL
`phones`	List of company contact phones if any
`contact_persons`	List of contact person names
`address`	Postal address: Street and number
`city`	Postal address: City
`zipcode`	Postal address: ZIP code
`region`	Postal address: Region
`region_nuts`	Postal address: Region NUTS code
`global_country`	Country where the business resides
`legal_form`	Legal form of the business
`turnover`	Turnover category
`turnover_pretty`	Turnover category (short)
`turnover_numeric`	Turnover category (numeric lower bound)
`turnover_currency`	Turnover currency 'CZK' or 'EUR'
`magnitude`	Number of employees category
`magnitude_pretty`	Number of employees category (short)
`magnitude_numeric`	Number of employees category (numeric lower bound)
`industry`	Major business industry
`merk_url`	Link to CZ/SK company information in Merk database
`merk_api_url`	Link to CZ/SK company information in Merk REST API

Example request

$ curl 'https://api.leady.com/v1/companies/{id}/{secure_token}/' \
  -H 'Authorization: Token {your_access_token}' \
  -H 'Content-type: application/json; charset=utf-8' \
  -X 'GET'

import coreapi

# Initialize a client & load the schema document
client = coreapi.Client()
schema = client.get("https://api.leady.com/")

# Interact with the API endpoint
action = ["companies", "read"]
params = {
    "id": ...,
    "secure_token": ...,
}
result = client.action(schema, action, params=params)

var coreapi = window.coreapi  // Loaded by `coreapi.js`
var schema = window.schema    // Loaded by `schema.js`

// Initialize a client
var client = new coreapi.Client()

// Interact with the API endpoint
var action = ["companies", "read"]
var params = {
    id: ...,
    secure_token: ...,
}
client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
})

persons

read

GET /v1/persons/{id}/{secure_token}/

Returns the full person profile, social media accounts and all available information.

This call is protected by an individual token and is to be accessed directly from the sessions list call.

Usage is limited to 320 requests per hour.

Path Parameters

The following parameters make up the URL path:

Parameter	Description
`id` required
`secure_token` required

Response Fields

The meaning of each key in the resulting object(s) is as follows:

Field	Description
`email`	E-mail address of the person
`company`	Short version of company structure (with link to full info) if the person relates to any, `null` if not recognized
`image_url`	Image url
`gender`	Gender
`facebook_url`	Link to Facebook profile if available
`twitter_url`	Link to Twitter profile if available
`linkedin_url`	Link to LinkedIn profile if available
`organizations`	Organizations

Example request

$ curl 'https://api.leady.com/v1/persons/{id}/{secure_token}/' \
  -H 'Authorization: Token {your_access_token}' \
  -H 'Content-type: application/json; charset=utf-8' \
  -X 'GET'

import coreapi

# Initialize a client & load the schema document
client = coreapi.Client()
schema = client.get("https://api.leady.com/")

# Interact with the API endpoint
action = ["persons", "read"]
params = {
    "id": ...,
    "secure_token": ...,
}
result = client.action(schema, action, params=params)

var coreapi = window.coreapi  // Loaded by `coreapi.js`
var schema = window.schema    // Loaded by `schema.js`

// Initialize a client
var client = new coreapi.Client()

// Interact with the API endpoint
var action = ["persons", "read"]
var params = {
    id: ...,
    secure_token: ...,
}
client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
})

saved-filters

list

GET /v1/resources/{domain}/saved-filters/

Returns filters you saved for specified resource.

Usage is limited to 60 requests per hour and resource.

Path Parameters

The following parameters make up the URL path:

Parameter	Description
`domain` required

Query Parameters

The following parameters belong to the URL query string.

Parameter	Description
`cursor`	Pagination cursor (optional)

Response Fields

The meaning of each key in the resulting object(s) is as follows:

Field	Description
`name`	Filter name
`color`	Filter color
`filter_data`	Filter data
`created`	Filter creation timestamp
`created_by`	E-mail address of person who created the filter
`is_shared`	When enabled, all other users having access to this website will also be able to use, edit or delete this filter.
`id`	Primary key identifier

Example request

$ curl 'https://api.leady.com/v1/resources/{domain}/saved-filters/' \
  -H 'Authorization: Token {your_access_token}' \
  -H 'Content-type: application/json; charset=utf-8' \
  -X 'GET'

import coreapi

# Initialize a client & load the schema document
client = coreapi.Client()
schema = client.get("https://api.leady.com/")

# Interact with the API endpoint
action = ["saved-filters", "list"]
params = {
    "domain": ...,
    "cursor": ...,
}
result = client.action(schema, action, params=params)

var coreapi = window.coreapi  // Loaded by `coreapi.js`
var schema = window.schema    // Loaded by `schema.js`

// Initialize a client
var client = new coreapi.Client()

// Interact with the API endpoint
var action = ["saved-filters", "list"]
var params = {
    domain: ...,
    cursor: ...,
}
client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
})

read

GET /v1/resources/{domain}/saved-filters/{id}/

Returns your single saved filter for specified resource.

Usage is limited to 60 requests per hour and resource.

Path Parameters

The following parameters make up the URL path:

Parameter	Description
`domain` required
`id` required

Response Fields

Same as above.

Example request

$ curl 'https://api.leady.com/v1/resources/{domain}/saved-filters/{id}/' \
  -H 'Authorization: Token {your_access_token}' \
  -H 'Content-type: application/json; charset=utf-8' \
  -X 'GET'

import coreapi

# Initialize a client & load the schema document
client = coreapi.Client()
schema = client.get("https://api.leady.com/")

# Interact with the API endpoint
action = ["saved-filters", "read"]
params = {
    "domain": ...,
    "id": ...,
}
result = client.action(schema, action, params=params)

var coreapi = window.coreapi  // Loaded by `coreapi.js`
var schema = window.schema    // Loaded by `schema.js`

// Initialize a client
var client = new coreapi.Client()

// Interact with the API endpoint
var action = ["saved-filters", "read"]
var params = {
    domain: ...,
    id: ...,
}
client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
})

blacklist

list

GET /v1/resources/{domain}/blacklist/

Leady offers blacklisting (hiding) sessions from companies the user selected by reg.no. or homepage. This endpoint lists the definitions for given resource saved by any user.

Usage is limited to 2000 requests per hour and resource.

Path Parameters

The following parameters make up the URL path:

Parameter	Description
`domain` required

Query Parameters

The following parameters belong to the URL query string.

Parameter	Description
`cursor`	Pagination cursor (optional)

Response Fields

The meaning of each key in the resulting object(s) is as follows:

Field	Description
`id`	Primary key identifier
`reason`	Blacklisting reason (own_visit,competitor,present_customer,other_reason,report_bug)
`territory`	Territory under which the blacklisted company is listed, works with `regno` below
`regno`	Reg. no. of company to blacklist
`homepage`	Home page of company to blacklist. Either this or `regno` is set if item was imported.
`matched_company`	Short version of blacklisted company structure (with link to full info) if matched
`created_by`	Person who created the blacklist item
`created`	Blacklist item creation timestamp

Example request

$ curl 'https://api.leady.com/v1/resources/{domain}/blacklist/' \
  -H 'Authorization: Token {your_access_token}' \
  -H 'Content-type: application/json; charset=utf-8' \
  -X 'GET'

import coreapi

# Initialize a client & load the schema document
client = coreapi.Client()
schema = client.get("https://api.leady.com/")

# Interact with the API endpoint
action = ["blacklist", "list"]
params = {
    "domain": ...,
    "cursor": ...,
}
result = client.action(schema, action, params=params)

var coreapi = window.coreapi  // Loaded by `coreapi.js`
var schema = window.schema    // Loaded by `schema.js`

// Initialize a client
var client = new coreapi.Client()

// Interact with the API endpoint
var action = ["blacklist", "list"]
var params = {
    domain: ...,
    cursor: ...,
}
client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
})

turnovers

list

GET /v1/turnovers/

Returns all turnover items referenced by companies registered in specified country.

Usage is limited to 1000 requests per day.

Query Parameters

The following parameters belong to the URL query string.

Parameter	Description
`country` required	Use 'cs' or 'sk' to select country.

Response Fields

The meaning of each key in the resulting object(s) is as follows:

Field	Description
`id`	Primary key identifier
`turnover`	Original category string
`pretty`	Short string
`currency`	Currency: CZK, EUR
`numeric`	Numeric lower bound of the category

Example request

$ curl 'https://api.leady.com/v1/turnovers/' \
  -H 'Authorization: Token {your_access_token}' \
  -H 'Content-type: application/json; charset=utf-8' \
  -X 'GET'

import coreapi

# Initialize a client & load the schema document
client = coreapi.Client()
schema = client.get("https://api.leady.com/")

# Interact with the API endpoint
action = ["turnovers", "list"]
params = {
    "country": ...,
}
result = client.action(schema, action, params=params)

var coreapi = window.coreapi  // Loaded by `coreapi.js`
var schema = window.schema    // Loaded by `schema.js`

// Initialize a client
var client = new coreapi.Client()

// Interact with the API endpoint
var action = ["turnovers", "list"]
var params = {
    country: ...,
}
client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
})

magnitudes

list

GET /v1/magnitudes/

Returns all magnitude items referenced by companies registered in specified country. Magnitude is the size of the company in terms of the number of employees.

Usage is limited to 1000 requests per day.

Query Parameters

The following parameters belong to the URL query string.

Parameter	Description
`country` required	Use 'cs' or 'sk' to select country.

Response Fields

The meaning of each key in the resulting object(s) is as follows:

Field	Description
`id`	Primary key identifier
`magnitude`	Original category string
`pretty`	Short string
`numeric`	Numeric lower bound of the category

Example request

$ curl 'https://api.leady.com/v1/magnitudes/' \
  -H 'Authorization: Token {your_access_token}' \
  -H 'Content-type: application/json; charset=utf-8' \
  -X 'GET'

import coreapi

# Initialize a client & load the schema document
client = coreapi.Client()
schema = client.get("https://api.leady.com/")

# Interact with the API endpoint
action = ["magnitudes", "list"]
params = {
    "country": ...,
}
result = client.action(schema, action, params=params)

var coreapi = window.coreapi  // Loaded by `coreapi.js`
var schema = window.schema    // Loaded by `schema.js`

// Initialize a client
var client = new coreapi.Client()

// Interact with the API endpoint
var action = ["magnitudes", "list"]
var params = {
    country: ...,
}
client.action(schema, action, params).then(function(result) {
    // Return value is in 'result'
})