Introduction Authentication Errors Inline operations Companies API People API Download API Response

Introduction

Welcome to Gazelle API documentation. Our REST API allows you to query our vast dataset of business profiles and companies and receive and get an enriched profile of the item you were looking for. Our two main calls are:

  • Company API, which returns company data
  • People API, which returns contact data for a business profile

                    https
                    :
                    //gz-api.gazelle.vision/public

Authentication

Token based authentication

When using curl or httpie standalone client, one must pass the session along with each request. We will give you a token and the only one thing that you need to do is to pass it in cookies, when you make request. On the right you can see base request with authentication token in cookies, using curl.

HTTP
Base request with authentication token 
                    curl 'https://gz-api.gazelle.vision/public/companies' \
  -H $'Cookie: auth_tkt=your_authentication_token'

Errors

Gazelle uses common HTTP response codes to indicate the status of the API request. In case of an error, Gazelle API will return the correspondent code.

HTTP Status codes
200 OK – Successful request

400 Bad request – Badly formatted request

403 Unauthorized – Your account is not active. Please contact support

405 Method Not Allowed - You are trying to make wrong action like POST request to/companies

500 Server error – There’s a problem on Gazelle’s end

Inline operations

There are few common operations that can be used with some filters in one request.

Comparison:

  • __gt - greater than value
  • __gte - greater and equal than value
  • __lt - less than value
  • __lte - less and equal than value
    • Comparisons are applicable for the folowing filters for Companies API: created_at, founded, industries.naics, locations.countries.count, metrics.global_employees, metrics.global_revenue, updated_at.
    For People API comparisons are applicable for created_at and updated_at filters.
Inclusion:
  • __in - returns objects relevant at least for one value
  • __all - returns objects relevant for each value together
    • All company API filters can be used with inclusion, EXCEPT: _page, _limit, created_at, keywords, locations.countries.codes, roles All people API filters can be used with inclusion, EXCEPT: updated_at
Existing fields:
  • __exists - returns results that have given field filled, you can pass 1 or 0 (True or False)
  • __eq - returns results with equal value for some filter

HTTP
Request example for comparison 
                    GET https
                    :
                    //gz-api.gazelle.vision/public/companies?founded__gt=2008
Request example for inclusion 
                    GET https
                    :
                    //gz-api.gazelle.vision/public/companies?address.country.name__in=Ukraine, France
Request example for existing fields 
                    GET https
                    :
                    //gz-api.gazelle.vision/public/companies?address.country.name__exists=1

Companies API

The company API provides information about any organization you look for to help you get a complete picture, such as overview, location, email, website and smuch more. On the right you can see base url for companies API. To use any filter below you need to add "?" after companies, and for using few filters in one request you need to join them by "&" symbol

Filters:

  • address.admin0.code:
    string
    returns a list of companies with the given address admin0 code.
    Example:
    address.admin0.code=south
  • address.admin0.division:
    string
    returns a list of companies with the given address admin0 division.
    Example:
    address.admin0.division=West Coast
  • address.admin0.name:
    string
    returns a list of companies the given address admin0 name.
    Example:
    address.admin0.name=south
  • address.admin0.region:
    string
    returns a list of companies with the given address admin0 region.
    Example:
    address.admin0.region=West Coast
  • address.admin1.admin_type:
    string Available choices: [state, province]
    returns a list of companies with the given address admin1 type.
    Example:
    address.admin1.admin_type=province
  • address.admin1.code:
    string
    returns a list of companies with the given address admin1 code.
    Example:
    address.admin1.code=UT
  • address.admin1.fips:
    integer
    returns a list of companies with the given address admin1 fips.
    Example:
    address.admin1.fips=05
  • address.admin1.name:
    string
    returns a list of companies with the given address admin1 name.
    Example:
    address.admin1.name=Utah
  • address.admin2.code:
    integer
    returns a list of companies with the given address admin2 code.
    Example:
    address.admin2.code=27027
  • address.admin2.fips:
    integer
    returns a list of companies with the given address admin2 fips.
    Example:
    address.admin2.fips=27
  • address.admin2.name:
    string
    returns a list of companies with the given address admin2 name.
    Example:
    address.admin1.name=Utah
  • address.admin2.sgc:
    integer
    returns a list of companies with the given address admin2 sgc.
    Example:
    address.admin2.sgc=5909
  • address.city:
    string
    returns a list of companies located in the specified city.
    Example:
    address.city=Kyiv
  • address.country.code:
    string
    returns a list of companies with the given country code.
    Example:
    address.country.code=UA
  • address.country.name:
    string
    returns a list of companies with the given country name.
    Example:
    address.country.name=Ukraine
  • address.geo__geobb:
    string
    returns a list of companies within the specified rectangle of geo coordinates.
    Example:
    address.geo__geobb= 35.14506666730433,-124.98046875000001, 31.62345068996294,-117.15820312500001
  • address.postal_code:
    integer
    returns a list of companies with the given postal_code.
    Example:
    address.postal_code=11203
  • address.region.code:
    integer
    returns a list of companies from the given region (specified by its code).
    Example:
    address.region.code=019
  • address.region.name:
    string
    returns a list of companies from the given region (specified by its name).
    Example:
    address.region.name=Europe
  • address.subregion.code:
    integer
    returns a list of companies from the given subregion (specified by its code).
    Example:
    address.subregion.code=151
  • address.subregion.name:
    string
    returns a list of companies from the given subregion (specified by its name).
    Example:
    address.subregion.name=Eastern Europe
  • created_at:
    datetime (string) in format: %Y-%m-%d
    returns a list of companies created at the given date, before or after it.
    Example:
    created_at=2020-02-23
    created_at__gt=2019-02-23
  • description:
    string
    returns a list of companies that have a description, or, if used with a specific string, only filters by it as the the full phrase.
    Example:
    description__exists=1
  • emails.email:
    string(email format)
    returns a list of companies that have the given email among emails.
    Example:
    emails.email=email@example.com
  • export:
    char Available choices: [N, Y]
    returns a list of companies that are marked as exporters or not.
    Example:
    export=N
  • founded:
    integer
    returns a list of companies founded at the given year.
    Example:
    founded=2008
    founded__gte=2008
  • gid:
    string
    returns a company with the specific `gid` (unique).
    Example:
    gid=57abb57d6890a345831de90e
  • import:
    char Available choices: [N, Y]
    returns a list of companies that are marked as importers or not.
    Example:
    import=Y
  • industries.gscore:
    integer
    returns a list of companies with the specific gscore.
    Example:
    industries.gscore=3
  • industries.industry_type:
    string Available choices: [traded, local]
    returns a list of companies from the given industry type.
    Example:
    industries.industry_type=traded
  • industries.naics:
    integer
    returns a list of companies having specified NAICS code.
    Example:
    industries.naics=452311
  • industries.name:
    string
    returns a list of companies from the given industry (specified by its name).
    Example:
    industries.name=Some Supercenter
  • keywords:
    string
    returns a list of companies that include the given keywords (also makes the smart search in the description).
    Example:
    keywords=Blockchain
  • locations.branch:
    string
    returns a list of companies' branches from the given location (specified by the custom format).
    Example:
    locations.branch = US:MD:24024:Frederick:21702
  • locations.countries.codes:
    string of codes
    returns a list of companies which are located in the given countries (by their codes).
    Example:
    locations.countries.codes=DE, FR, AT, LT, RO
  • locations.countries.count:
    integer
    returns a list of companies which are located in some number of countries (specified by the summary number of countries).
    Example:
    locations.countries.count=33
    locations.countries.count__gte=20
  • locations.hq:
    string
    returns a list of companies' HQ from the given location (specified by the custom format).
    Example:
    locations.hq = US:SC:45083:Spartanburg:29303
  • locations.subsidiary:
    string
    returns a list of companies' subsidiaries from the given location (specified by the custom format).
    Example:
    locations.subsidiary = US:OH:39039:Cleveland:44115
  • metrics.global_employees:
    integer
    returns a list of companies with some specified number of global employees.
    Example:
    metrics.global_employees__gte=40
  • metrics.global_revenue:
    integer
    returns a list of companies with some specified global_revenue.
    Example:
    metrics.global_revenue__gte=100000
  • name:
    string
    returns companies with the given name.
    Example:
    name=OFFICE TEAM
  • parent:
    string
    returns a list of companies having certain parent (identified by its `gid`).
    Example:
    parent=5d49be1602a24620c235e636
  • primary_naics:
    integer
    returns a list of companies with the given primary NAICS code.
    Example:
    primary_naics=541618
  • roles:
    string Available choices: [hq, standalone, subsidiary, branch]
    returns a list of companies filtered by the given role.
    Example:
    roles=hq
  • social.crunchbase.url:
    string
    returns companies with the given crunchbase URL (full URL should be provided).
    Example:
    social.crunchbase.url=https://www.crunchbase.com/organization/"name"
  • social.facebook.url:
    string
    returns companies with the given facebook url (full URL should be provided).
    Example:
    social.facebook.url=https://www.facebook.com/"name"
  • social.linkedin.url:
    string
    returns companies with the given LinkedIn url (full URL should be provided).
    Example:
    social.linkedin.url=https://www.linkedin.com/company/"name"
  • social.twitter.url:
    string
    returns companies with the given Twitter url (full URL should be provided).
    Example:
    social.twitter.url=https://twitter.com/"name"
  • updated_at:
    datetime(string) in format: %Y-%m-%d
    returns the companies that had their data last updated at the given date, before or after it.
    Example:
    updated_at=2020-06-21
    updated_at__lt=2020-06-21
  • website:
    string
    returns companies with the given website (specified without 'http(s)://').
    Example:
    website=www.familydollar.com
HTTP
Base request example 
                    GET https
                    :
                    //gz-api.gazelle.vision/public/companies

Query with one filter 
                    GET https
                    :
                    //gz-api.gazelle.vision/public/companies?address.country.code=UA

Query with few filters 
                    GET https
                    :
                    //gz-api.gazelle.vision/public/companies?address.country.code=UA&founded=2008

Query with inline operations 
                    GET https
                    :
                    //gz-api.gazelle.vision/public/companies?created_at__lte=2020-03-25
                

                    GET https
                    :
                    //gz-api.gazelle.vision/public/companies?address.city__in=Kyiv, London
                

                    GET https
                    :
                    //gz-api.gazelle.vision/public/companies?founded__exists=1

People API

The person API lets you look up a person data based on his name and the company, he works for. For example, you can get the person’s email and phone number, as well as his or her social network. You have to send body in json format to make request, below you can see instructions

Filters:

  • company.gid:
    string
    returns a list of people from the given company (specified by `gid`).
    Example:
    company.gid=5b342ed233c59c0682c5e8db
  • created_at:
    string
    returns a list of people created at the given date, before or after it.
    Example:
    created_at=2019-02-16T20:37:57.628290
    created_at__gte=2019-03-25
  • email:
    string(in email format)
    returns people with the given email.
    Example:
    email=username@email.com
  • first_name:
    string
    returns a list of people with the given first name.
    Example:
    first_name=Username
  • full_name:
    string
    returns a list of people with the given full name.
    Example:
    full_name=Username UserLastname
  • job_title:
    string
    returns a list of people with the given job title.
    Example:
    job_title=President
  • last_name:
    string
    returns a list of people with the given last name.
    Example:
    last_name=UserLastname
  • pid:
    string
    returns a person with the given pid (unique).
    Example:
    pid=57ac32c66890a345833a0667:Sharon Flom
  • updated_at:
    datetime(string) in format: %Y-%m-%d
    returns a list of people with their data updated at the given date, before or after it.
    Example:
    updated_at=2019-03-26
    updated_at__gte=2019-03-25
HTTP
Base request example 
                    GET https
                    :
                    //gz-api.gazelle.vision/public/people

Query with one filter 
                    GET https
                    :
                    //gz-api.gazelle.vision/public/people?updated_at=2019-03-26

Query with few filters 
                    GET https
                    :
                    //gz-api.gazelle.vision/public/people?updated_at=2019-03-26&job_title_keywords=executive

Query with inline operations 
                    GET https
                    :
                    //gz-api.gazelle.vision/public/people?updated_at__gte=2019-03-25
                

                    GET https
                    :
                    //gz-api.gazelle.vision/public/people?job_title__in=Pres, Mgr
                

                    GET https
                    :
                    //gz-api.gazelle.vision/public/people?full_name__exists=1

Download API

The download API lets you receive data about companies and people in csv format. You have to use authentication token for this curl examples (instruction in Authentication). Also you have to send body in json format to make request, below you can see instructions.

  • /download/companies POST request:

    There is list of fields that can be included in your body(data-row): Company GID, GScore, Name, Website, Main Email, Alt Email, Main Phone, Alt Phone, Street, City, State,Postal Code, Country, Revenue, Employees, Latitude, Longitude, Company Description, Year Founded, LinkedIn, Facebook, Twitter, Crunchbase, Primary Industry, Other Industry, International Presence. Also you can use any filter parameter from Companies API.


  • /people POST request

    There is list of fields that can be included in your body(data-row): Person Name, Title, Email, LinkedIn, Facebook, Twitter, Crunchbase. You need to specify "_limit" parameter here, and you can use any filter parameter from Person API.
HTTP
List of all possible fields for companies request 
                                        {"_fields":"gid__as__Company GID,gscore__as__GScore,
n.name__as__Name,n.url__as__Website,emails.0.email__as__Main Email,
emails.1.email__as__Alt Email,phones.0.phone__as__Main Phone,
phones.1.phone__as__Alt Phone,address.street__as__Street,address.city__as__City,
address.admin1.name__as__State,address.postal_code__as__Postal Code,
address.country.name__as__Country,revenue__as__Revenue,employees__as__Employees,
address.geo.lat__as__Latitude,address.geo.lon__as__Longitude,description__as__Company Description,
founded__as__Year Founded,social.linkedin.url__as__LinkedIn,social.facebook.url__as__Facebook,
social.twitter.url__as__Twitter,social.crunchbase.url__as__Crunchbase,primary_naics__as__Primary Naics,
industries.0.naics__as__NAICS 1,industries.1.naics__as__NAICS 2,industries.2.naics__as__NAICS 3,
industries.3.naics__as__NAICS 4,industries.4.naics__as__NAICS 5,
locations.countries.codes__as__International Presence"}
Curl request with all possible fields for companies request 
                                        curl -X POST 'https://gz-api.gazelle.vision/public/download/companies' \
-H 'Content-Type: application/json' \
-H $'Cookie: auth_tkt=your_auth_tkn' \
--data-raw '{"_fields":"all"}'

List of all possible fields for people request 
                                        {"_fields":"company.gid,first_name,last_name,job_title_keywords,job_title__as__Title,
full_name__as__Person Name,job_title__as__Title,email__as__Email,
social.linkedin.url__as__LinkedIn,social.facebook.url__as__Facebook,
social.twitter.url__as__Twitter,social.crunchbase.url__as__Crunchbase", "_limit":"10"}
Curl request with all possible fields for people request 
                                        curl -X POST 'https://gz-api.gazelle.vision/public/people' \
-H 'Content-Type: application/json' \
-H $'Cookie: auth_tkt=your_auth_tkn' \
--data-raw '{"_fields":"all", "_limit":"20"}'

Response Examples

In this section you can see basic examples of response for Companies API and for People API.

Responses
Companies API example 
                                
{
   "address":{
      "admin0":{
         "region":"South",
         "division":"South Atlantic"
      },
      "admin1":{
         "fips":"51",
         "name":"Virginia",
         "code":"VA",
         "admin_type":"state"
      },
      "admin2":{
         "fips":"51199",
         "name":"York",
         "code":"51199",
         "admin_type":"county"
      },
      "city":"Yorktown",
      "country":{
         "code":"US",
         "name":"United States"
      },
      "geo":{
         "lat":37.1744658,
         "lon":-76.4755822
      },
      "postal_code":"23692",
      "region":{
         "code":"019",
         "name":"Americas"
      },
      "street":"6642 George Washington Mem Hwy",
      "subregion":{
         "code":"021",
         "name":"Northern America"
      }
   },
   "created_at":"2020-02-24T00:46:00.177357",
   "description":"Beauty Salons",
   "gid":"57ac33f46890a345833a3f2c",
   "industries":[
      {
         "industry_type":"local",
         "naics":"812112",
         "name":"Beauty Salons",
         "primary":true
      }
   ],
   "locations":{
      "countries":{
         "count":1,
         "codes":[
            "US"
         ]
      },
      "hq":[
         "US:VA:51199:Yorktown:23692"
      ]
   },
   "metrics":{
      "global_employees":10,
      "global_revenue":343789
   },
   "name":"Hairphenalia 17",
   "parent":"NA",
   "phones":[
      {
         "phone":"+1 757-898-0997",
         "source":"dbusa"
      }
   ],
   "primary_naics":"812112",
   "revenue_range":[
      0,
      10000000
   ],
   "roles":[
      "hq",
      "standalone"
   ],
   "root_parent":"NA",
   "updated_at":"2020-02-24T00:46:00.177357",
   "website":"www.hairphenalia17llc.com"
}

People API example 
                                
{
   "company":{
      "gid":"5b342d0233c59c02cc55615e"
   },
   "first_name":"Rose",
   "full_name":"Rose De Fremery",
   "job_title":"Group Owner",
   "last_name":"De Fremery",
   "pid":"5b342d0233c59c02cc55615e:Rose De Fremery",
   "social":{
      "crunchbase":{
         "url":"https://www.crunchbase.com/person/rose-de-fremery",
         "handle":"person/rose-de-fremery"
      },
      "facebook":{
         "url":"http://www.facebook.com/rdefremery",
         "handle":"rdefremery"
      },
      "linkedin":{
         "url":"http://www.linkedin.com/in/rosedefremery",
         "handle":"in/rosedefremery"
      },
      "twitter":{
         "url":"http://twitter.com/rosedefremery",
         "handle":"rosedefremery"
      }
   },
   "updated_at":"2019-03-26T21:02:41.559000"
}