Firmographics API

Introduction

The Firmographics.org APIs enable programmatic access to our firmographic knowledge-base. We have built our technology stack natively in the form of APIs; in fact, all the data presented on this Website directly invokes the underlying APIs.

Invocation

All APIs are invoked via simple HTTPS GET or POST requests. You will need an API key in order to make a successful API call. The key is provided in the HTTP header field FG-API-KEY. The API endpoint URL is constructed by appending the API path to the base URL https://api.firmographics.org/v1. For example, you can request information about an organization using Unix curl command as shown below.

curl -X GET -H "FG-API-KEY: 123456xyzdfdfd" "https://api.firmographics.org/v1/getorg?id=id-12345"

Response Format

All APIs return a JSON object with two fields:
  • status - Status code indicating the response status
  • result - Result of the API call when the it is successful
  • error - Error object with a "message" field indicating the type of error when the call fails.

The following table lists possible status codes.

Code Description
0 Successful invocation
-1 User/Application errors due to invalid input
-2 Internal server error

Throttling Error

All client requests have an upper limit on the request rates. If a client exceeds the allowable rate limit, it will receive an HTTP response with HTTP status code 429.

Available APIs

Get Organization Record

Get available information about an organization given its ID.

Path
/getorg

Input Parameters

Name Description
id Object ID. Typically the client would use an ID returned within previous organization search results.

Output
JSON object representing the organization data. The object fields returned vary based on the source and type of the organization. Some common fields are listed below.

Name Description
id Object ID
name Organization name
tagline One line phrase that describes organization type
about Overview of organization's business activities.
keywords Keywords representing organization's business activities
main An object providing details about the main location of the organization. May contain some or all of the following fields: addr1, addr2, city, state, zipcode, zipext, phone, email, fax
employees Employee count
revenue Revenue in US dollars
employees Employee count
revenueEst Estimated revenue in US dollars
codes An array of objects representing NAICS 2022 codes for the organization. Each object contains the following fields:
  • c - NAICS code
  • p - Confidence score
people An array of objects corresponding to people working for the organization with fields: name, title, phone, email
locs An array of objects representing physical locations. Fields: name, addr1, addr2, city, state, zipcode, zipext, phone, email, fax
phones An array of objects containing organization phones. Fields: ty, num
emails An array objects containing organization emails. Fields: ty, eml
social An object containing a collection of social media links belonging to the organization. The following object fields may be present:
  • fb - Facebook URL
  • tw - X (Twitter) URL
  • in - Instagram URL
  • li - Linked In URL
  • go - Google location URL

Name Lookup

Search for organizations based on keywords.

Path:
/searchorgs

Input Parameters

Name Description
searchtype Must be name
name One or more words in organization name

Output
An array of organizations that contain the input words in their names. Each element of the array will have the following fields:

  • id - Organization ID
  • name - Organization name
  • city - City in which the headquarter is located
  • state - State in which the headquarter is located

Text Search

Performs a text search on organization business overview.

Path:
/searchorgs

Input Parameters

Name Description
searchtype Must be fulltext
name Search terms.

Output
An array of organizations associated with the keywords. Each element of the array will have the following fields:

  • id - Organization ID
  • name - Organization name
  • overview - Organization overview
  • city - City in which the headquarter is located
  • state - State in which the headquarter is located
  • revenue - Revenue or estimated revenue (if available)
  • employees - Employee count (if available)

Keyword Search

Search for organizations based on keywords.

Path:
/searchorgs

Input Parameters

Name Description
searchtype Must be keywords
name Keyword to search for.

Output
An array of organizations associated with the keywords. Each element of the array will have the following fields:

  • id - Organization ID
  • name - Organization name
  • overview - Organization overview
  • city - City in which the headquarter is located
  • state - State in which the headquarter is located
  • revenue - Revenue or estimated revenue (if available)
  • employees - Employee count (if available)

NAICS Classification

Get NAICS 2022 classes applicable to an organization provided its name and business overview.

Path
/classifynaics2022

Input Parameters

Name Description
name Organization name
overview Overview of organization's business activities.

Output
An array of objects representing applicable NAICS 2022 codes. Each object contains the following fields:

  • c - NAICS code
  • d - Code description or index entry
  • r - Reason why this code is applicable

Get Domain Insights

Get technographic and firmographic information associated with a domain/Website.

Path
/getdomain

Input Parameters

Name Description
id Domain (e.g. firmographics.org)

Output
JSON object representing the organization data. The object fields returned vary based on the source and type of the organization. Some common fields are listed below.

Name Description
id Domain name
name Name of the entity associated with the Website
tagline One line phrase that describes the Website or the entity associated with it
about Summary of the entity associated with the Website
keywords Keywords describing Website contents
main An object providing details about the main location of the entity associated with the Website. May contain some or all of the following fields: addr1, addr2, city, state, zipcode, zipext, phone, email, fax
techs An array of technologies (e.g. React, JQuery, etc.) used on the Website
founded The year the associated company was founded (if mentioned)
revenueEst Estimated revenue in US dollars
codes An array of objects representing NAICS 2022 codes for the Website or the entity associated with the Website. Each object contains the following fields:
  • c - NAICS code
  • d - Code description or index entry
  • r - Reason why this code is applicable
people An array of objects corresponding to people mentioned on the Website. Available fields: name, title, phone, email
locs An array of objects representing physical locations mentioned on the Website. Avaiable fields: name, addr1, addr2, city, state, zipcode, zipext, phone, email, fax
phones An array of objects containing phones mentioned on the Website. Fields: ty, num
emails An array objects containing emails displayed on the Website. Fields: ty, eml
social An object containing a collection of social media links discovered on the Website. The following object fields may be present:
  • fb - Facebook URL
  • tw - X (Twitter) URL
  • in - Instagram URL
  • li - Linked In URL
  • go - Google location URL