API

Connect directly into the data

API access

Sign up to get your API key

API Documentation

The structure of the call parameters are similar to what you can do on the website when querying a dataset.

Authentication

A personal token is needed to use the API. To get your personal token, sign up. Your API key will then be available on this page and in your personal settings

Getting started

  • The base url to use is api.workwithdata.com/v1/
  • The method used is GET
  • The authorization header is required in the following format: "Authorization: Bearer <your token>"

Parameters

Parameter name Type Definition Criteria Possible values
entity Required Name of the table to query See available data below
f Optional Number of filters to apply to the companies table >=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] Optional Operator used to filter the column x Optional if f exists, default value is “=“ Depending on the type of fcol[X]

For texts:
= (exact match)
!= (exact exclusion)
Includes (approximate match)
Excludes (approximate exclusion)

For numbers:
>=
<=
>
<
=
!=

Available data

For the moment, only the table Companies is available through API.

Fields available:

  • 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

Examples

  • Exact search for a specific company:
    curl -X GET -H "Authorisation: Bearer <your token>" "https://api.workwithdata.com/v1/extract?entity=companies&f=1&fcol0=website&fval0=https://www.tessian.com"
  • This is equivalent to (with the operator of the filter being explicit this time):
    curl -X GET -H "Authorisation: Bearer <your token>" "https://api.workwithdata.com/v1/extract?entity=companies&f=1&fcol0=website&fval0=https://www.tessian.com&fop0=="
  • Approximate search for a company:
    curl -X GET -H "Authorisation: Bearer <your token>" "https://api.workwithdata.com/v1/extract?entity=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?entity=companies&f=2&fcol0=city&fop0==&fval0=paris&fcol1=country&fop1==&fval1=france"

Results are currently limited to 50 rows

API results

Your JSON API results are in the following format: 
{"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"
	      }]
	    }