API - Work With Data

API authentication

A personal token is needed to use the API, sign up to get yours:

Sign up for free

Log in

Getting started

The API base url is https://api.workwithdata.com/v1/
An authorization header is required in the following format: "Authorization: Bearer <your_token>"

Endpoints

extract/<table>

Available tables: companies (more tables to be added soon)

Query parameters (optional):

Parameter name	Type	Definition	Possible values
limit	Optional	Maximum number of rows to be returned	Integer >= 1
f	Optional	Number of filters to apply to the companies table	Integer >= 1
fcol[x]	Required if f exists	Name of the filtering column x	See available data below
fval[x]	Required if f exists	Value of the filter on the column X
fop[x]	Required if f exists	Operator used to filter the column x	Depending on the type of fcol[X] For texts: = (exact match) != (exact exclusion) Includes (approximate match) Excludes (approximate exclusion) For numbers: >= <= > < = !=

To create the right query paramaters, we recommend you to first create the data you want to extract on the dataset page and then use the structure of the dataset page for the API.

Fields available for the filtering in query paramaters:

company (text): name of the company
sector (text) : values from the GICS
industry (text) : values from the GICS
website (text): the full URL of the company’s website
domain (text): the URL of the company’s website without protocol and prefix
foundation_year (number): year where the company was founded
city (text): city of the headquarter
country (text): country of the headquarter
employees (number): number of employees
employee_type (text): if the number of employees is estimated by us or not (possible values: estimate/actual)
revenues (number): in $
revenue_type (text): if the revenue is estimated by us or not (estimate/actual)
talking_points (text): concatenation of different descriptions of the companies, coming from different sources such as the website or social media
stack (text)
linkedin_link (text): link to the LinkedIn profile of the company
linkedin_followers (number): number of followers on LinkedIn
twitter_link (text): link to the Twitter profile of the company
twitter_followers (number): number of followers on Twitter
facebook_link (text): link to the Facebook profile of the company
instagram_link (text): link to the Instagram profile of the company

Response

Your JSON API results are in the following format:

Parameter name	Definition
currency	String(3) - the currency of your subscription
is_paid	Boolean - True if the data is paid, False if it is free
price	Float - Amount that is added to your next invoice in the currency of your subscription
results	List of dicts- results of the query. Each row is an element of the list
results_length	Integer - Size of the results of your query
returned_length	Integer - Size of the results returned by the API. Usually equals to results_length, except if you reach your monthly API usage limit with a query. When that is the case, we truncate the results so that you don't exceed your limit.

Example:


			{
			"currency": "USD",
			"is_paid": true,
			"price": 0.005,
			"results":
				[{
				"city":null,
				"company":"Tessian",
				"country":"United States",
				"domain":"tessian.com",
				"employee_type":"estimate",
				"employees":225,
				"facebook_link":null,
				"foundation_year":2013,
				"industry":"Software",
				"instagram_link":"https://www.instagram.com/tessianofficial",
				"linkedin_followers":16611,
				"linkedin_link":"https://www.linkedin.com/company/tessian",
				"revenue_type":"estimate",
				"revenues":42275000.0,
				"sector":"Information Technology",
				"stack":"google analytics",
				"talking_points":"Intelligent Cloud Email Security For The Modern Enterprise ...",
				"twitter_followers":2620,
				"twitter_link":"https://twitter.com/tessian",
				"website":"https://www.tessian.com"
				}],
			"results_length": 1,
			"returned_length": 1
			}

Examples

Here are a few examples from which you can create your own:

Exact search for a specific company:
curl -X GET -H "Authorisation: Bearer <your token>" "https://api.workwithdata.com/v1/extract/companies?f=1&fcol0=website&fop0==&fval0=https://www.tessian.com"
Approximate search for a company:
curl -X GET -H "Authorisation: Bearer <your token>" "https://api.workwithdata.com/v1/extract/companies?f=1&fcol0=domain&fval0=tessian&fop0=includes"
Search for companies in France, Paris (2 filters applied):
curl -X GET -H "Authorisation: Bearer <your token>" "https://api.workwithdata.com/v1/extract/companies?f=2&fcol0=city&fop0==&fval0=paris&fcol1=country&fop1==&fval1=france"