Ocrolus Business history API
The Business history API from Ocrolus — 4 operation(s) for business history.
OpenAPI Specification
openapi: 3.0.0
info:
title: Account Level Webhooks Book Commands Business history API
version: 1.0.0
servers:
- url: https://api.ocrolus.com
security:
- oauth: []
tags:
- name: Business history
paths:
/v2/book/{book_uuid}/business:
get:
summary: Business identifier
operationId: business-identifier
tags:
- Business history
description: "This API retrieves the business associated with a given `book_uuid`. It returns the business ID and display name, which can be used with business-level endpoints to access aggregated data across multiple <<glossary:Book>>s. \nA single business can have multiple Books. All books associated with the same business within your organization return the same business ID.\n"
parameters:
- name: book_uuid
in: path
description: A universally unique identifier (UUID) of the Book used to retrieve its associated business.
required: true
schema:
type: string
format: uuid
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
properties:
id:
type: string
description: Universally Unique Identifier (UUID) of the business entity. This is a stable identifier that is used with all business endpoints.
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name:
type: string
description: 'Display name of the business. The name is determined in the following order: user-defined display name, org-specific name, then global entity name.
'
example: Acme Corp
examples:
Success:
value:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: Acme Corp
'400':
description: Invalid Auth/Book UUID format
content:
application/json:
schema:
oneOf:
- title: Invalid authentication
$ref: '#/paths/~1v1~1businesses~1%7Bbusiness_id%7D/get/responses/400/content/application~1json/schema/oneOf/0'
- title: Invalid Book UUID Format
$ref: '#/paths/~1v1~1businesses~1%7Bbusiness_id%7D/get/responses/403/content/application~1json/schema'
examples:
Invalid Auth:
$ref: '#/components/examples/InvalidAuthError'
Invalid Book UUID Format:
$ref: '#/components/examples/InvalidBookUUIDFormatError'
'403':
description: Book not associated with requesting organization
content:
application/json:
schema:
$ref: '#/paths/~1v1~1businesses~1%7Bbusiness_id%7D/get/responses/403/content/application~1json/schema'
examples:
Book not associated with requesting organization:
$ref: '#/components/examples/BookNotBelongToOrganizationError'
'404':
description: Business Identity Not Associated With Book
content:
application/json:
schema:
$ref: '#/paths/~1v1~1businesses~1%7Bbusiness_id%7D/get/responses/403/content/application~1json/schema'
examples:
Business Identity Not Associated With Book:
$ref: '#/components/examples/BusinessIdentityNotAssociatedWithBookError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/paths/~1v1~1businesses~1%7Bbusiness_id%7D/get/responses/403/content/application~1json/schema'
examples:
Internal Server Error:
$ref: '#/components/examples/InternalServerError'
/v1/businesses/{business_id}:
get:
summary: Business overview
operationId: business-overview
tags:
- Business history
description: 'This API retrieves the full metadata profile for a business entity, including industry classification, loan inquiry history, and addresses derived from bank account holder information.
'
parameters:
- name: business_id
in: path
description: A universally unique identifier (UUID) of the business entity for which you want to retrieve overview information.
required: true
schema:
type: string
format: uuid
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
properties:
id:
type: string
description: UUID of the business entity for which overview information is retrieved.
example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name:
type: string
description: 'Display name of the business. The name is determined in the following order: user-defined display name, org-specific name, then global entity name.
'
example: Acme Corp
state:
type: string
description: Current operational state of the business entity.
enum:
- ACTIVE
- INACTIVE
- CLOSED
example: ACTIVE
industry:
type: object
description: Industry classification information for the business.
properties:
naics4_code:
type: integer
description: A 4-digit North American Industry Classification System (NAICS) code that represents the industry of the Book.
example: 7225
naics_description:
type: string
description: "\nThe description of the 4-digit NAICS code, indicating the industry classification of the Book category.\n\n > \U0001F4D8 In Books with multiple businesses or fragmented merchant activity, system may show the following statuses as applicable:\n > - **`Pending - Industry Data`** — Classification is in progress. \n > - **`Unable to find a unique SMB merchant`** — The system is not able to find a unique merchant mapped to the documents in the Book. \n > - **`Not Available`** — The system has found a unique merchant, but this merchant does not have industry classification data.\n"
example: Restaurants and Other Eating Places
naics6_code:
type: integer
description: A six-digit NAICS code that provides a more granular industry classification for the merchant. This code refines the broader NAICS category and is commonly used for detailed industry analysis, peer comparisons, and benchmarking.
example: 7225
naics6_description:
type: string
description: A human-readable description of the six-digit NAICS code that specifies the merchant’s exact industry segment within the broader NAICS classification.
example: Snack and Nonalcoholic Beverage Bars
naics_override:
type: boolean
description: Shows if the 4-digit NAICSA code was overriden by the lender.
example: true
mcc_code:
type: integer
description: A four-digit code assigned by payment networks that classifies a merchant based on the primary type of goods or services they provide. Merchant Category Code (MCC) are commonly derived from card transaction data and are used for transaction categorization, risk assessment, and analytics.
example: 7225
mcc_description_:
type: string
description: A human-readable description of the MCC that explains the merchant’s primary business activity as defined by the card network.
example: Snack and Nonalcoholic Beverage Bars
sic_code:
type: integer
description: A four-digit Standard Industrial Classification (SIC) code that identifies the merchant’s primary business activity using the legacy SIC system. SIC codes are derived from bank statement data and are used for industry classification, regulatory reporting, and analytics.
example: 172
sic_description_:
type: string
description: A human-readable description of the SIC code that explains the merchant’s primary industry classification under the SIC system.
example: GRAPES
active_override:
type: boolean
description: Shows if the industry classification has been manually overridden.
example: false
loan_inquiries:
type: object
description: Loan inquiry history and velocity metrics aggregated across all applications.
properties:
total_applications:
type: integer
description: Total number of loan applications across all organisations that have been made for this business entity.
example: 5
application_history:
type: array
description: "Timestamps (ISO 8601) for each application.\n > \U0001F4D8 Note\n > This is cross-org data. It includes application timestamps but does not identify which organization submitted each application.\n"
items:
type: string
format: date-time
example:
- '2025-01-15T12:00:00Z'
velocity:
type: object
description: Application velocity counts in rolling time windows.
properties:
day_count_30:
type: integer
description: Number of applications in the last 30 days.
example: 1
day_count_60:
type: integer
description: Number of applications in the last 60 days.
example: 1
day_count_90:
type: integer
description: Number of applications in the last 90 days.
example: 2
day_count_180:
type: integer
description: Number of applications in the last 180 days.
example: 3
day_count_270:
type: integer
description: Number of applications in the last 270 days.
example: 4
day_count_365:
type: integer
description: Number of applications in the last 365 days.
example: 5
addresses:
type: array
description: Deduplicated addresses derived from bank account holder information, sorted by frequency with the most common address first.
items:
type: object
properties:
holder_address_1:
type: string
description: The primary line of the address, typically including the street number and name.
example: 123 MAIN STREET
holder_address_2:
type: string
nullable: true
description: The secondary line of the address, which may include apartment, suite, unit, building, or floor.
example: SUITE 200
holder_city:
type: string
description: The city associated with the address.
example: NEW YORK
holder_state:
type: string
description: The state or province associated with the address.
example: NY
holder_zip:
type: string
description: The postal or ZIP code associated with the address.
example: '10001'
holder_country:
type: string
description: The country associated with the address.
example: US
frequency:
type: integer
example: 4
description: Number of bank accounts sharing this address. Higher frequency indicates higher confidence.
examples:
Success:
value:
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
name: Acme Corp
state: ACTIVE
industry:
naics4_code: '5411'
naics_description: Legal Services
active_override: false
naics6_code: '541110'
naics6_description: Offices of Lawyers
mcc_code: '8111'
mcc_description: Legal Services
sic_code: '8111'
sic_description: Legal Services
loan_inquiries:
total_applications: 5
application_history:
- '2025-01-15T12:00:00Z'
- '2025-04-20T09:30:00Z'
- '2025-07-10T14:15:00Z'
- '2025-10-05T11:00:00Z'
- '2026-01-22T16:45:00Z'
velocity:
day_count_30: 1
day_count_60: 1
day_count_90: 2
day_count_180: 3
day_count_270: 4
day_count_365: 5
addresses:
- holder_address_1: 123 MAIN STREET
holder_address_2: SUITE 200
holder_city: NEW YORK
holder_state: NY
holder_zip: '10001'
holder_country: US
frequency: 4
- holder_address_1: PO BOX 456
holder_address_2: null
holder_city: NEW YORK
holder_state: NY
holder_zip: '10002'
holder_country: US
frequency: 1
'400':
description: Invalid Auth/Business ID format
content:
application/json:
schema:
oneOf:
- title: Invalid authentication
properties:
status:
type: integer
description: A numerical code that indicates the status of the request.
example: 400
code:
type: integer
description: A numerical code that indicates the nature of an error.
example: 1401
response:
type: object
description: An object received from the server that potentially contains data.
message:
type: string
description: A textual description that indicates details about this response's status.
example: Book not found
meta:
type: object
description: An object received from the server that potentially contains data.
properties:
status:
type: integer
example: 400
description: A numerical code that indicates the status of the request.
message:
type: string
example: Book not found
description: A textual description that indicates details about this response's status.
code:
type: integer
example: 1401
description: A numerical code that indicates the nature of an error.
- title: Invalid Business ID Format
$ref: '#/paths/~1v1~1businesses~1%7Bbusiness_id%7D/get/responses/403/content/application~1json/schema'
examples:
Invalid Auth:
$ref: '#/components/examples/InvalidAuthError'
Invalid Business ID Format:
$ref: '#/components/examples/InvalidBusinessIDFormatError'
'403':
description: Business not associated with requesting organization
content:
application/json:
schema:
properties:
status:
type: integer
description: A numerical code that indicates the status of the request.
message:
type: string
description: A textual description that indicates details about this response's status.
examples:
Business not associated with requesting organization:
$ref: '#/components/examples/BusinessNotBelongToOrganizationError'
'404':
description: Business Identity Not Associated With Book
content:
application/json:
schema:
$ref: '#/paths/~1v1~1businesses~1%7Bbusiness_id%7D/get/responses/403/content/application~1json/schema'
examples:
Business Identity Not Associated With Book:
$ref: '#/components/examples/BusinessIdentityNotAssociatedWithBookError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/paths/~1v1~1businesses~1%7Bbusiness_id%7D/get/responses/403/content/application~1json/schema'
examples:
Internal Server Error:
$ref: '#/components/examples/InternalServerError'
/v1/businesses/{business_id}/transactions:
get:
summary: Business transactions
operationId: business-transactions
tags:
- Business history
description: "This API retrieves the paginated, deduplicated enriched transactions across all of the requesting org's <<glossary:Book>>s for a given business. Transactions are structurally compatible with the existing book-level enriched transactions API.\n\n > \U0001F44D Tips\n > `start_date` and `end_date` filter transactions based on when they occurred at the bank, while `updated_since` filters based on when transactions were ingested into the system. Use `updated_since` to retrieve newly added data, even if the transaction dates are earlier.\n"
parameters:
- name: business_id
in: path
description: A universally unique identifier (UUID) of the business entity for which you want to retrieve transction details.
required: true
schema:
type: string
format: uuid
example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
- name: offset
in: query
description: Number of transactions to skip for pagination.
required: false
schema:
type: integer
minimum: 0
- name: limit
in: query
description: Maximum number of records to return per page, starting from the specified **offset**.
required: false
schema:
type: integer
minimum: 1
- name: start_date
in: query
description: Start date in `YYYY-MM-DD` format from which you want to filter transactions. The system includes only transactions with a `txn_date` on or after the specified date.
required: false
schema:
type: string
format: date
example: '2023-01-01'
- name: end_date
in: query
description: End date in `YYYY-MM-DD` format from which you want to filter transactions. The system includes only transactions with a `txn_date` on or before the specified date.
required: false
schema:
type: string
format: date
example: '2023-12-31'
- name: updated_since
in: query
description: Timestamp (ISO 8601) for filtering transactions ingested into the system after this time. The system uses `txn_created_ts` to determine the ingestion time. Use this for incremental retrieval to fetch only newly ingested transactions since your last request.
required: false
schema:
type: string
format: date-time
example: '2023-01-01T00:00:00Z'
x-readme:
samples-languages:
- curl
- python
explorer-enabled: false
responses:
'200':
description: Success
content:
application/json:
schema:
properties:
id:
description: Unique identifier of the business entity for which transaction details are retrieved.
type: string
format: uuid
example: caaa57ba-8909-4a05-9dcc-e7cc057e3c48
total:
type: integer
description: The total number of deduplicated transactions for this business retrieved based on the specified query parameteres.
example: 50
filtered_total:
type: integer
description: The total number of transactions retrieved based on the provided `start_date`, `end_date`, and `updated_since` filters.
example: 50
offset:
type: integer
description: The starting index for paginated transactions result.
example: 1
limit:
type: integer
description: The maximum number of transactions returned per page starting from the specified `offset` value.
example: 50
transactions:
type: array
items:
type: object
properties:
txn_pk:
type: integer
example:
- 2640590368
description: Unique identifier of the transaction.
txn_date:
type: number
example: '2021-01-09'
description: Date of the transaction in ISO 8601-compliant YYYY-MM-DD format.
description:
type: string
example: CHECKCARD 0109 LIBERTY PAPER SUPPLIES
description: A brief description of the transaction.
bank_account_pk:
type: integer
example: 123246
description: The primary key of the bank account associated with the transaction.
uploaded_doc_uuid:
type: string
example: 123246
description: The UUID of the uploaded <<glossary:Document>> containing transaction details.
uploaded_doc_name:
type: string
example: december_bank_statement
description: The name of the uploaded <<glossary:Document>> containing transaction details.
amount:
type: number
format: float
example: -50
description: 'Transaction amount. Positive values represent credits, and negative values represent debits.
This amount includes dollars and cents; to avoid floating-point precision errors, consider parsing this field with a decimal data type, as opposed to a native `float` or `double`.
'
counterparty:
type: string
description: Standardized identifier of the transaction counterparty.
example: ACME Corp
comment:
type: string
description: User provided notes or remarks about the transaction.
example: Payment for office supplies
is_noteworthy:
type: boolean
description: Indicates whether the transaction is considered noteworthy based on internal business rules and risk factors. A value of `true` highlights transactions that may require additional attention or review.
page_idx:
type: number
description: The page number in the source document where this transaction was recorded.
book_uuid:
type: string
description: UUID of the book entity from which transaction details are retrieved.
example: book-uuid-456
format: uuid
deposits:
type: boolean
example: true
description: Creadited amount greater than zero.
withdrawals:
type: boolean
example: true
description: Debited amount less than zero.
revenue:
type: boolean
example: true
description: Deposits that have been included in revenue.
nsf:
type: boolean
example: true
description: Non-sufficient funds transactions and fees.
expense:
type: boolean
example: true
description: Withdrawals that have been included as expense.
overdraft:
type: boolean
example: true
description: Fees associated with overdraft events
atm:
type: boolean
example: true
description: Transaction at physical ATM locations.
bank:
type: boolean
nullable: true
description: Transaction associated with a traditional bank/depository institution.
bank_branch:
type: boolean
nullable: true
description: Transaction with a physical bank branch.
bank_cash_advance:
type: boolean
nullable: true
description: Cash advance transaction with a traditional bank.
bank_loan:
type: boolean
nullable: true
description: Loan transaction with a traditional bank.
benefits:
type: boolean
nullable: true
description: Transaction associated with government benefits.
card_rewards:
type: boolean
nullable: true
description: Transaction associated with credit card rewards.
checks:
type: boolean
example: true
description: Transaction associated with check payments, including check payments that have cleared, as well as check payments that have not cleared but are present in the bank statement data.
credit_builder:
type: boolean
example: false
description: Transaction associated with credit builder products offered by fintech companies to help businesses build credit history.
credit_card:
type: boolean
example: true
description: Transaction associated with credit cards, including purchases, payments, fees, and interest charges.
crypto:
type: boolean
example: true
description: Transaction associated with cryptocurrency and related companies.
debit_card:
type: boolean
example: true
description: Debit card transaction.
debt_consolidator:
type: boolean
example: true
description: Transaction associated with debt refinancing and consolidation companies that offer services to help businesses manage and consolidate existing debts.
equipment_lease:
type: boolean
example: true
description: Transaction associated with equipment leasing companies.
factoring:
type: boolean
example: true
description: Transaction associated with factoring companies.
federal_tax:
type: boolean
example: true
description: Transaction associated with federal tax payments or refunds.
fintech_loan:
type: boolean
example: true
description: Loan transaction with a fintech company that does not fit into `bank_loan` category.
fintech_loan_source:
type: string
example: true
description: The source of a loan transaction with a fintech company.
fintech_mca:
type: string
example: true
description: Merchant cash advance transaction with a fintech company.
fintech_mca_source:
type: boolean
example:
# --- truncated at 32 KB (283 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ocrolus/refs/heads/main/openapi/ocrolus-business-history-api-openapi.yml