openapi: 3.2.0
info:
description: "### Cellenus Corporate APIs\nThe Cellenus Corporate APIs consists of three main datasets, \"Corporate, Market & Industry\", \"ESG\", and \"Thematic Trending\" which provide news, events, press releases relevant to corporate entities, typically identifying signals that affect them. Bitvore currently surveils most public companies traded on US and international exchanges, US companies and international companies. Additionally, new companies required by a customer can be requested to be added to our surveillance.\n\nThe Corporate APIs also includes access to economic news for geographic locations in the United States.\n\nA typical record in the dataset is depicted below.\n\n\n\nAccess to the Corporate Datasets using the Corporate APIs requires its own license and API key. To register for an API Key please visit [here](http://developer.bitvore.com/v2/getting-started?section=obtain-api-key). \n\nThe Cellenus Corporate APIs, include [Corporate News API](http://developer.bitvore.com/v2/docs/overview/corp?tagname=News%20API), [Ecomomic News](http://developer.bitvore.com/v2/docs/overview/corp?tagname=News%20API), [Organizations](http://developer.bitvore.com/v2/docs/overview/corp?tagname=Organizations%20API), [Portfolio Integration](http://developer.bitvore.com/v2/docs/overview/corp?tagname=Portfolios%20API), [Sentiment Scores](http://developer.bitvore.com/v2/docs/overview/corp?tagname=Sentiment%20Scores%20API), [Financial Filings](http://developer.bitvore.com/v2/docs/overview/corp?tagname=Filings%20API) and [Datasets](http://developer.bitvore.com/v2/docs/overview/corp?tagname=Datasets%20API).\n\nThe [Corporate News API](http://developer.bitvore.com/v2/docs/overview/corp?tagname=News%20API) provides direct access to the curated news based on company ID (Bitvore ID), portfolio, customer ID, industry, location, and certain company characteristics such as number of employees and annual revenue.\n\nThe [Economic News API](http://developer.bitvore.com/v2/docs/overview/corp?tagname=News%20API) provides direct access to the curated news relevant to the economy of a location or region.\n\nThe [Organizations API](http://developer.bitvore.com/v2/docs/overview/corp?tagname=Organizations%20API) provides the ability to search for companies by a variety of company characteristics such as name, web domain, ticker, industry, location, number of employees, and annual revenue. Each company is uniquely identified by a Bitvore ID which can be used as input to query the [News API](http://developer.bitvore.com/v2/docs/overview).\n\nThe [Portfolios API](http://developer.bitvore.com/v2/docs/overview/corp?tagname=Portfolios%20API) provides the ability to either create and maintain portfolios of companies so that news can be queried in a single call from the [News API](http://developer.bitvore.com/v2/docs/overview/corp?tagname=News%20API) for a given portfolio or to map your own company ID scheme to Bitvore's so you can query the [News API](http://developer.bitvore.com/v2/docs/overview/corp?tagname=News%20API) with your own IDs.\n\nThe [Filings API](http://developer.bitvore.com/v2/docs/overview/corp?tagname=Filings%20API) provides direct access to the financial filings submitted to regulatory agencies such as the SEC on behalf of companies found in the [Organizations API](http://developer.bitvore.com/v2/docs/overview/corp?tagname=Organizations%20API).\n\nThe [Datasets API](http://developer.bitvore.com/v2/docs/overview/corp?tagname=Datasets%20API) provides dataset and changeset exporting. This API provides offline data consumption that can be used with external tools.\n\n"
version: '2.1'
title: Corporate Organizations API API
license:
name: Copyright Bitvore Corp. 2026
servers:
- url: https://api.bitvore.com/
tags:
- name: Organizations API
description: Organization Details and Search
paths:
/v2/corp/organizations/byid/{id}:
get:
tags:
- Organizations API
summary: Organization by Alt-Id
description: "Returns detailed information about the organization with the given Bitvore ID or Alternate ID. The following are the supported ID Scheme parameters: \n\n * BVID - Bitvore ID (default) \n * CUSIP - Requires license: 'CUSIP' \n * FIGI \n * ISIN - Requires license: 'ISIN' \n * SEDOL - Requires license: 'SEDOL' \n \n\n Example Request: \n\n \n\n ```js\n GET https://api.bitvore.com/v2/corp/organizations/byid/BBG001S5TD05?orgIdScheme=FIGI\n ```\n \n\n "
operationId: handleGetOrgUsingGET_1
parameters:
- name: id
in: path
description: Organization Id
required: true
schema:
type: string
- name: idScheme
in: query
description: Organization Id Scheme
required: false
allowEmptyValue: false
schema:
type: string
enum:
- BVID
- CUSIP
- ISIN
- SEDOL
- FIGI
default: BVID
responses:
'200':
description: Success
content:
'*/*':
schema:
$ref: '#/components/schemas/OrganizationDetails'
originalRef: OrganizationDetails
'400':
description: Invalid parameter
content:
'*/*':
schema:
$ref: '#/components/schemas/ReasonResponse'
originalRef: ReasonResponse
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/AccessDeniedResponse'
originalRef: AccessDeniedResponse
'500':
description: Internal error
content:
'*/*':
schema:
$ref: '#/components/schemas/InternalErrorResponse'
originalRef: InternalErrorResponse
security:
- API key:
- Global
- OAuth:
- Global
deprecated: false
/v2/corp/organizations/lookup:
get:
tags:
- Organizations API
summary: Organization Search
description: "A lookup takes a single string as input to matching entities. The following are the matching rules used. The search results are ordered according to the rules. \n\n 1. Exact match on name (case insensitive)\n 2. Exact match on ticker\n 3. Exact match on domain name\n 4. Exact match on alias (case insensitive)\n 5. Starts with on name (case insensitive)\n 6. Starts with on ticker\n 7. Starts with on domain name\n 8. Starts with on alias (case insensitive)\n \n\n Example Request: \n\n \n\n ```js\n GET https://api.bitvore.com/v2/corp/organizations/search?q=acme\n ```\n \n\n \n\n 0 or more companies may be returned that match the supplied query criteria. Only summary information for each matching organization is supplied which includes the following fields: \n\n * ID \n * Name \n * Domain Name \n * Ticker \n * State \n * Country \n * Parent \n "
operationId: handleOrgLookupUsingGET_1
parameters:
- name: q
in: query
description: Lookup option. Value is used to match multiple fields.
required: false
allowEmptyValue: false
schema:
type: string
- name: pageNo
in: query
description: Page number of the total result set to return, default is 1.
required: false
allowEmptyValue: false
schema:
type: integer
format: int32
default: 1
- name: pageSize
in: query
description: Number of results out of the total result set per page to return, default is 100, maximum is 1000.
required: false
allowEmptyValue: false
schema:
type: integer
format: int32
default: 100
responses:
'200':
description: Success
content:
'*/*':
schema:
$ref: '#/components/schemas/OrgResultsResponse'
originalRef: OrgResultsResponse
'400':
description: Invalid parameter
content:
'*/*':
schema:
$ref: '#/components/schemas/ReasonResponse'
originalRef: ReasonResponse
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/AccessDeniedResponse'
originalRef: AccessDeniedResponse
'500':
description: Internal error
content:
'*/*':
schema:
$ref: '#/components/schemas/InternalErrorResponse'
originalRef: InternalErrorResponse
security:
- API key:
- Global
- OAuth:
- Global
deprecated: false
/v2/corp/organizations/match:
post:
tags:
- Organizations API
summary: Organization Matching
description: "Attempts to find companies matching input specifications made up of a list of property values. Multiple companies can be matched in a single call. For each organization to match a list of properties and values known by the client (the input specification) are passed in. If possible the system will return a single matching organization for each input specification. If more than one organization matches an input specification and there is not one organization that is more qualified than the others all the candidates will be returned. The following are the organization properties that can be used in input specifications. More than one value can be supplied for each indicating a match of any of the values will be acceptable. \n * Name \n * DomainName \n * Ticker \n * CUSIP - Requires license: 'CUSIP' \n * FIGI \n * ISIN - Requires license: 'ISIN' \n * SEDOL - Requires license: 'SEDOL' \n * NAICSCode \n * SICCode \n * City \n * StateCode \n * Country \n \n\n Tickers formats: \n * Nonqualified - Basic ticker symbol (e.g. T, XOM) \n * Region Qualified - <region>:<ticker> (e.g. US:T, US:XOM) \n * Exchange Qualified - <exchange>:<ticker> (e.g. NYS:T, NAS:XOM) \n \n\n In the following example we'll try to match two companies. In this case they will actually be companies with the same name but by using different properties in the specifications we can see how the system matches differently. The first specification will include the organization name and the state it's in. The second specification will include the organization name and its domain name. \n\n \n\n ```js\n POST https://api.bitvore.com/v2/corp/organizations/match \n Content-Type: application/json \n Accept: application/json \n X-BV-APIKEY: xyz123... \n\n [ \n \t{ \n \t\t\"Name\": [\"Bank of Commerce\"], \n \t\t\"State\": [\"Oklahoma\"] \n \t}, \n \t{ \n \t\t\"Name\": [\"Bank of Commerce\"], \n \t\t\"DomainName\": [\"bocokonline.com\"] \n \t} \n ] \n ```\n \n\n \n\n The first set of candidates is returned for the name/state combination. There are three companies with the input name and state code. Since that is the only input the system could not narrow the candidates down any further. \n\n The second set of candidates is returned for the same name but with a domain name instead of a state code. This input specification matched only one organization in the system which is returned. \n\n The properties that were matched for each candidate are returned in the \"hits\" field. These will match the input specification properties. However, when matching names the system will attempt to match the input name against the organization's names in the Knowledge Graph as well as any known aliases for companies. If the input name matched an alias instead of a organization name the \"Alias\" property will be returned in \"hits\"."
operationId: handleOrgMatchingUsingPOST_1
responses:
'200':
description: Success
content:
'*/*':
schema:
$ref: '#/components/schemas/SingleOrganizationMatchingResult'
originalRef: SingleOrganizationMatchingResult
'400':
description: Invalid parameter
content:
'*/*':
schema:
$ref: '#/components/schemas/ReasonResponse'
originalRef: ReasonResponse
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/AccessDeniedResponse'
originalRef: AccessDeniedResponse
'500':
description: Internal error
content:
'*/*':
schema:
$ref: '#/components/schemas/InternalErrorResponse'
originalRef: InternalErrorResponse
security:
- API key:
- Global
- OAuth:
- Global
deprecated: false
requestBody:
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/OrgSpec'
originalRef: OrgSpec
description: specs
required: true
/v2/corp/organizations/search:
post:
tags:
- Organizations API
summary: Organization Search
description: "A search query takes one or more search parameters. A parameter has a name and one or more values. The search will match the organization properties and relationships with the parameters and return only those that have an EXACT match on all input parameters. The following are the supported search parameters: \n\n * name - One or more names to search for \n * ticker - One or more tickers to search for \n * domainName - One or more domain names to search for. \n * location - One or more locations companies must have their headquarters in. Locations are in the format of city/state code/country. If city or state is unspecified the appropriate / delimiters must still be included, i.e., /California/United States. Must not be used with fips or zip. \n * fips - One or more FIPS codes identifying counties or CBSAs (metropolitan/micropolitan statistical areas) companies must have their headquarters in. FIPS codes for counties can be found [here](https://www.census.gov/prod/techdoc/cbp/95-96cd/fips-st.pdf). FIPS codes for CBSAs can be found [here](https://www2.census.gov/programs-surveys/cps/methodology/2015%20Geography%20Cover.pdf). Maps of CBSAs can be found [here](https://www.census.gov/geographies/reference-maps/2020/geo/cbsa.html). Must not be used with location or zip. \n * zip - One or more zip codes identifying ZIP Code Tabulation Areas (ZCTAs) companies must have their headquarters in. Must not be used with location or fips. \n * naics - One or more [NAICS](https://www.naics.com/search/) codes identifying industries the companies must operate in. \n * sic - One or more [SIC](https://www.osha.gov/pls/imis/sicsearch.html) codes identifying industries the companies must operate in. \n * revRange - Revenue range (in millions) companies must fall in. The range is formated as lower-upper where lower and upper must be one of 0, 1, 10, 50, 100, 500, 1000, 10000. The upper bound can be omitted to report over 10B. \n * empRange - Employee range companies must fall in. The range is formated as lower-upper where lower and upper must be one of 1, 10, 50, 100, 250, 500, 1000, 5000, 10000. The upper bound can be omitted to report over 10000. \n \n\n Example Request: \n\n \n\n ```js\n POST https://api.bitvore.com/v2/corp/organizations?domainName=acme.com\n ```\n \n\n \n\n 0 or more companies may be returned that match the supplied query criteria. Only summary information for each matching organization is supplied which includes the following fields: \n\n * ID \n * Name \n * Domain Name \n * Ticker \n * State \n * Country \n * Parent \n \n\n "
operationId: handleOrgSearchUsingPOST
parameters:
- name: name
in: query
description: One or more names to search for.
required: false
allowEmptyValue: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: ticker
in: query
description: One or more tickers to search for.
required: false
allowEmptyValue: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: domainName
in: query
description: One or more domain names to search for.
required: false
allowEmptyValue: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: location
in: query
description: One or more locations organization must have their headquarters in.
required: false
allowEmptyValue: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: fips
in: query
description: One or more FIPS codes identifying locations the companies must have their headquarters in.
required: false
allowEmptyValue: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: zip
in: query
description: One or more zip codes identifying locations the companies must have their headquarters in.
required: false
allowEmptyValue: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: naicsCode
in: query
description: One or more NAICS codes identifying industries the companies must operate in.
required: false
allowEmptyValue: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: sicCode
in: query
description: One or more SIC codes identifying industries the companies must operate in.
required: false
allowEmptyValue: false
style: form
explode: true
schema:
type: array
items:
type: string
- name: revRange
in: query
description: Revenue range (in millions) companies must fall in. The range is formated as lower-upper where lower and upper must be one of 0, 1, 10, 50, 100, 200, 1000. The upper bound can be ommited to report over 1B.
required: false
allowEmptyValue: false
schema:
type: string
- name: empRange
in: query
description: Employee range companies must fall in. The range is formated as lower-upper where lower and upper must be one of 1, 10, 50, 200, 500, 1000, 5000, 10000. The upper bound can be ommited to report over 1B.
required: false
allowEmptyValue: false
schema:
type: string
- name: pageNo
in: query
description: Page number of the total result set to return, default is 1.
required: false
allowEmptyValue: false
schema:
type: integer
format: int32
default: 1
- name: pageSize
in: query
description: Number of results out of the total result set per page to return, default is 100, maximum is 1000.
required: false
allowEmptyValue: false
schema:
type: integer
format: int32
default: 100
responses:
'200':
description: Success
content:
'*/*':
schema:
$ref: '#/components/schemas/OrgResultsResponse'
originalRef: OrgResultsResponse
'400':
description: Invalid parameter
content:
'*/*':
schema:
$ref: '#/components/schemas/ReasonResponse'
originalRef: ReasonResponse
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/AccessDeniedResponse'
originalRef: AccessDeniedResponse
'500':
description: Internal error
content:
'*/*':
schema:
$ref: '#/components/schemas/InternalErrorResponse'
originalRef: InternalErrorResponse
security:
- API key:
- Global
- OAuth:
- Global
deprecated: false
/v2/corp/organizations/{bvId}:
get:
tags:
- Organizations API
summary: Organization Details
description: "Returns detailed information about the organization with the given Bitvore ID. The following are the supported ID Scheme parameters: \n\n * BVID - Bitvore ID\n \n\n Example Request: \n\n \n\n ```js\n GET https://api.bitvore.com/v2/corp/organizations/b00001axt\n ```\n \n\n "
operationId: handleGetOrgUsingGET_2
parameters:
- name: bvId
in: path
description: Organization BvId
required: true
schema:
type: string
responses:
'200':
description: Success
content:
'*/*':
schema:
$ref: '#/components/schemas/OrganizationDetails'
originalRef: OrganizationDetails
'400':
description: Invalid parameter
content:
'*/*':
schema:
$ref: '#/components/schemas/ReasonResponse'
originalRef: ReasonResponse
'401':
description: Unauthorized
content:
'*/*':
schema:
$ref: '#/components/schemas/AccessDeniedResponse'
originalRef: AccessDeniedResponse
'500':
description: Internal error
content:
'*/*':
schema:
$ref: '#/components/schemas/InternalErrorResponse'
originalRef: InternalErrorResponse
security:
- API key:
- Global
- OAuth:
- Global
deprecated: false
components:
schemas:
InternalErrorResponse:
type: object
properties:
reason:
type: string
example: internal_error
reasonSupport:
type: string
example: An internal error occured.
response:
type: string
example: INTERNAL_SERVER_ERROR
success:
type: boolean
example: false
title: InternalErrorResponse
OrganizationDetails:
type: object
properties:
bvId:
type: string
example: b00001ab7
description: Bitvore Id of the organization
channels:
type: array
description: Official social and communication channels of the organization
items:
$ref: '#/components/schemas/Channel'
originalRef: Channel
city:
type: string
example: Irvine
description: City the organization is headquartered in.
country:
type: string
example: United States
description: Country the organization is headquartered in.
domainName:
type: string
example: acme.com
description: Domain name of the organization.
factSetId:
type: string
isin:
type: string
example: US5949181045
description: 'ISIN of the organization. (Requires License: ''ISIN'')'
listings:
type: array
description: The exchange listings of the organization.
items:
$ref: '#/components/schemas/Listing'
originalRef: Listing
naicsIndustry:
description: NAICS Industry the organization operates in
$ref: '#/components/schemas/IndustrySummary'
originalRef: IndustrySummary
name:
type: string
example: ACME Corp
description: Name of the organization.
sicIndustry:
description: SIC Industry the organization operates in
$ref: '#/components/schemas/IndustrySummary'
originalRef: IndustrySummary
state:
type: string
example: CA
description: State (code) the organization is headquartered in.
ticker:
type: string
description: The primary ticker symbol the organization.
title: OrganizationDetails
OrgSpec:
type: object
properties:
city:
type: array
example:
- Mountain View
description: Cities of the organizations. Used to narrow down results when using other identifiers.
items:
type: string
country:
type: array
example:
- United States
description: Countries of the organizations. Used to narrow down results when using other identifiers.
items:
type: string
cusip:
type: array
example:
- ABCD12345
description: CUSIP Ids of the organizations
items:
type: string
domainName:
type: array
example:
- abc.xyz
description: Domain names of the organizations
items:
type: string
figi:
type: array
example:
- BBG009S39JY5
- b00001afc
description: FIGI Ids of the organizations
items:
type: string
isin:
type: array
example:
- US02079K3059
description: ISIN IDs of the organizations
items:
type: string
naicsCode:
type: array
example:
- '518210'
description: NAICS codes of the organizations
items:
type: string
name:
type: array
example:
- Alphabet
description: Names of the organizations
items:
type: string
sedol:
type: array
example:
- USABCD12345
description: SEDOL Ids of the organizations
items:
type: string
sicCode:
type: array
example:
- '7374'
description: SIC codes of the organizations
items:
type: string
state:
type: array
example:
- CA
description: States of the organizations. Used to narrow down results when using other identifiers.
items:
type: string
ticker:
type: array
example:
- GOOGL
- APPL
- F
description: Tickers of the organizations
items:
type: string
title: OrgSpec
PotentialOrganizationMatch:
type: object
properties:
hits:
type: array
example:
- Name
- DomainName
description: List of the properties in the input specification that this organization has matches for
items:
type: string
org:
description: Summary information for this potential match
$ref: '#/components/schemas/Organization'
originalRef: Organization
title: PotentialOrganizationMatch
description: A potential matched organization.
Organization:
type: object
properties:
bvId:
type: string
example: b00001ab7
description: Bitvore Id of the organization
city:
type: string
example: Irvine
description: City the organization is headquartered in.
country:
type: string
example: United States
description: Country the organization is headquartered in.
domainName:
type: string
example: acme.com
description: Domain name of the organization.
factSetId:
type: string
isin:
type: string
example: US5949181045
description: 'ISIN of the organization. (Requires License: ''ISIN'')'
listings:
type: array
description: The exchange listings of the organization.
items:
$ref: '#/components/schemas/Listing'
originalRef: Listing
name:
type: string
example: ACME Corp
description: Name of the organization.
state:
type: string
example: CA
description: State (code) the organization is headquartered in.
ticker:
type: string
description: The primary ticker symbol the organization.
title: Organization
ReasonResponse:
type: object
properties:
reason:
type: string
example: Could not locate subject.
description: Text reason for the failure (if not successful)
reasonSupport:
type: object
example: Longer description of the missing subject.
description: Additional information about the failure (if not successful)
response:
type: object
description: Response payload
success:
type: boolean
example: true
description: Indicates whether the call was successful or not
title: ReasonResponse
description: A response used to explain a failure or issue with the request.
Channel:
type: object
properties:
channel:
type: string
enum:
- FACEBOOK
- LINKEDIN
- TWITTER
location:
type: string
example: https://www.facebook.com/ACME
description: Direct source to the organizations channel
title: Channel
IndustrySummary:
type: object
properties:
code:
type: string
example: 55101050
description: Unique ID of the industry
name:
type: string
example: Corporate Financial Services
description: Name of the industry
title: IndustrySummary
description: Summary information about an industry.
OrgResultsResponse:
type: object
properties:
response:
type: array
description: Response payload
items:
$ref: '#/components/schemas/Organization'
originalRef: Organization
returned:
type: integer
format: int32
example: 10
description: Number of items return
success:
type: boolean
example: true
description: Indicates whether the call was successful or not
total:
type: integer
format: int32
example: 100
description: Total number of items available
title: OrgResultsResponse
description: Organization search response
Listing:
type: object
properties:
exchange:
type: string
example: NAS
description: The exchange the ticker belongs to.
mic:
type: string
example: XNAS
description: The MIC code of the exchange
region:
type: string
example: US
description: The geographic region of the exchange
ticker:
type: string
example: ACME
description: Primary ticker symbol the organization.
title: Listing
AccessDeniedResponse:
type: object
properties:
reason:
type: string
example: access_denied
reasonSupport:
type: string
example: You are not authorized for this resource.
response:
type: string
example: UNAUTHORIZED
success:
type: boolean
example: false
title: AccessDeniedResponse
SingleOrganizationMatchingResult:
type: object
properties:
candidates:
type: array
description: List of candidate matches
items:
$ref: '#/components/schemas/PotentialOrganizationMatch'
originalRef: PotentialOrganizationMatch
spec:
description: Input organization specification used to find candidates
$ref: '#/components/schemas/OrgSpec'
originalRef: OrgSpec
title: SingleOrganiz
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bitvore/refs/heads/main/openapi/bitvore-organizations-api-api-openapi.yml