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 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.
taxId	US tax ID (EIN)
name	Complete organization name or starting letters of an organization name
mode	Provide "exact" to return organization with name exactly matching provided value."

Output

If the "mode" parameter is anything other than "exact", the API returns an array of metadata objects with names beginning with the provided "name" parameter. Useful for constructing autocomplete UI to allow the user to search for an organization.

If the mode parameter is set to "exact", the API returns a single 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

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

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)

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)

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 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.

Firmographic Fields

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

Technographic Fields

Name	Description
cert	Subdomains and other domains referenced in the SSL certificate for the Website. Useful in detecting other domains owned by the same organization and the internal attack surface.
dns	Summarizes hosting/email infrastructure: MX providers + SPF hints point to outbound mail services, NS/SOA reveal authoritative DNS hosting .
xhr	Lists first-party subdomains hit via XHR vs. third-party domains, showing internal API surface area and external SaaS dependencies.
techs	Normalized Website technology tags.
vd	Vendor domains derived by analyzing technographic data.