Fintary

Fintary Open API

Customer-facing REST API over Fintary's commission and distribution data — list, create and update agents; assign and remove uplines; read an agent's commissions, payouts, policies and dashboard snapshot; query published analytics reports, datasets and dashboard widgets; pull commission report data; and upload or convert documents. Authenticated with an `x-api-key` header API key or an HTTP bearer token. Twenty-one operations under the `/openapi/` path prefix on api.fintary.com.

GitHub OpenAPI

Documentation

📖
APIReference
https://api.fintary.com/openapi-doc
📖
Documentation
https://api.fintary.com/documentation

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/fintary/refs/heads/main/openapi/fintary-open-api-openapi.yml

Other Resources

🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/fintary/refs/heads/main/overlays/fintary-open-api-overlay.yaml
🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/fintary/refs/heads/main/apis.yml

OpenAPI Specification

fintary-open-api-openapi.yml Raw ↑ 
openapi: 3.0.0
info:
  title: Fintary Open API documentation
  version: '1.0'
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: string
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication
  schemas:
    AgGridCompositeDateFilterSchema:
      type: object
      properties:
        filterType:
          type: string
          enum:
          - date
        operator:
          type: string
          enum:
          - AND
          - OR
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/AgGridDateFilterSchema'
      required:
      - filterType
      - operator
      - conditions
    AgGridCompositeTextFilterSchema:
      type: object
      properties:
        filterType:
          type: string
          enum:
          - text
        operator:
          type: string
          enum:
          - AND
          - OR
        conditions:
          type: array
          items:
            $ref: '#/components/schemas/AgGridTextFilterSchema'
      required:
      - filterType
      - operator
      - conditions
    AgGridDateFilterSchema:
      type: object
      properties:
        filterType:
          type: string
          enum:
          - date
        type:
          type: string
          enum:
          - equals
          - notEqual
          - lessThan
          - greaterThan
          - inRange
        dateFrom:
          type: string
          nullable: true
        dateTo:
          type: string
          nullable: true
      required:
      - filterType
      - type
    AgGridFilterModelSchema:
      type: object
      additionalProperties:
        anyOf:
        - $ref: '#/components/schemas/AgGridTextFilterSchema'
        - $ref: '#/components/schemas/AgGridCompositeTextFilterSchema'
        - $ref: '#/components/schemas/AgGridNumberFilterSchema'
        - $ref: '#/components/schemas/AgGridCompositeDateFilterSchema'
        - $ref: '#/components/schemas/AgGridDateFilterSchema'
    AgGridNumberFilterSchema:
      type: object
      properties:
        filterType:
          type: string
          enum:
          - number
        type:
          type: string
          enum:
          - equals
          - notEqual
          - lessThan
          - greaterThan
          - inRange
        filter:
          type: number
        filterTo:
          type: number
      required:
      - filterType
      - type
      - filter
    AgGridTextFilterSchema:
      type: object
      properties:
        filterType:
          type: string
          enum:
          - text
        type:
          type: string
          enum:
          - contains
          - equals
          - notEqual
          - startsWith
          - endsWith
        filter:
          type: string
      required:
      - filterType
      - type
      - filter
    AnalyticsDatasetDataResponse:
      type: object
      properties:
        data:
          type: array
          items:
            type: object
            additionalProperties: {}
          description: Dataset rows for the current page. Column set depends on the dataset.
        reportName:
          type: string
          description: Name of the queried dataset
          example: latest_commissions
        accountId:
          type: string
          description: Account the dataset rows belong to
          example: acct_7f3c2b1a
        pageRowCount:
          type: integer
          minimum: 0
          description: Number of rows returned on the current page
          example: 50
        rowCount:
          type: integer
          minimum: 0
          description: Total rows matching the query across all pages
          example: 412
        startDate:
          type: string
          nullable: true
          format: date-time
          description: Resolved start of the date filter window, when applied
        endDate:
          type: string
          nullable: true
          format: date-time
          description: Resolved end of the date filter window, when applied
        page:
          type: integer
          minimum: 0
          description: Zero-based page index returned
          example: 0
      required:
      - data
      - reportName
      - accountId
      - pageRowCount
      - rowCount
      description: Paginated dataset rows returned by the deprecated dataset-by-name query endpoint
    AnalyticsDatasetListResponse:
      type: array
      items:
        $ref: '#/components/schemas/AnalyticsDatasetTable'
      description: List of available analytics tables
    AnalyticsDatasetTable:
      type: object
      properties:
        id:
          type: string
          description: Full table identifier
          example: fintary-prod.analytics_reports.agency_receivables_by_policy
        friendlyName:
          type: string
          description: Human-readable name for the table
          example: Agency receivables by policy
        description:
          type: string
          description: Description of the table
        labels:
          type: object
          additionalProperties:
            anyOf:
            - type: string
            - type: array
              items:
                type: string
          description: Labels attached to the table
        columns:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the column
              type:
                type: string
                description: Data type of the column
              description:
                type: string
                description: Business description of the column sourced from the BigQuery schema. Omitted when the column
                  has no description.
                example: Unique policy number assigned by the carrier
            required:
            - name
            - type
          description: Column definitions for the dataset
      required:
      - id
    AnalyticsReportColumnMetadataSchema:
      type: object
      properties:
        name:
          type: string
          description: Column name in the underlying dataset
          example: policy_number
        type:
          type: string
          description: BigQuery column type
          example: STRING
        description:
          type: string
          description: Business description of the column sourced from the BigQuery schema. Omitted when the column has no
            description.
          example: Unique policy number assigned by the carrier
      required:
      - name
      - type
    AnalyticsReportFilterSchema:
      type: object
      properties:
        column_name:
          type: string
          description: Dataset column the filter applies to
          example: carrier_name
        operation:
          type: string
          nullable: true
          description: Filter operation identifier
          example: substring_contains
        filter_values:
          type: array
          items:
            type: string
          description: Values used by the filter operation
          example:
          - Acme
      required:
      - column_name
      - filter_values
    AnalyticsReportMeasureSchema:
      type: object
      properties:
        column:
          type: string
          description: Source column the measure aggregates
          example: premium_amount
        aggregation:
          type: string
          enum:
          - ANY
          - SUM
          - AVG
          - COUNT
          - MIN
          - MAX
          description: Aggregation applied to the column
          example: SUM
        outputName:
          type: string
          description: Column name exposed in report output
          example: total_premium
      required:
      - column
      - aggregation
      - outputName
    AnalyticsReportsListQuerySchema:
      type: object
      properties:
        account_id:
          type: string
          description: Account override for Fintary Admin or Account Admin callers. Must be supplied together with `contact_id`
            to impersonate a specific contact. Account admins may only use their own account.
          example: acct_7f3c2b1a
        contact_id:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          description: Contact override for Fintary Admin or Account Admin callers. Must be supplied together with `account_id`.
            Resolves the contact user role used for report access checks.
          example: 12345
      description: Query parameters for listing published analytics reports
    AnalyticsReportsListResponseSchema:
      type: array
      items:
        $ref: '#/components/schemas/FlattenedPublishedReportSchema'
      description: Published analytics reports visible to the authenticated principal
    AssignUplineRequestSchema:
      type: object
      properties:
        upline:
          type: string
          minLength: 1
          description: Agent identifier (str_id or agent_code) of the upline agent
        start_date:
          type: string
          nullable: true
          description: Start date of the hierarchy period
          format: date-time
        end_date:
          type: string
          nullable: true
          description: End date of the hierarchy period
          format: date-time
        split_percentage:
          type: number
          nullable: true
          minimum: 0
          maximum: 100
          description: Split percentage (0-100). Stored in percentage form (e.g. 80 for 80%)
      required:
      - upline
      description: Request body for assigning upline to an agent
    AssignUplineResponseSchema:
      type: object
      properties:
        assigned:
          type: boolean
          enum:
          - true
        str_id:
          type: string
          description: str_id of the created contact_hierarchy record; use this when removing upline
      required:
      - assigned
      - str_id
      description: Response when upline is successfully assigned
    ConvertHtmlToPdfRenderingOptions:
      type: object
      properties:
        page_size:
          type: string
          description: Paper size (e.g. A4, Letter)
          example: A4
        margin_top:
          type: number
          description: Top margin
        margin_bottom:
          type: number
          description: Bottom margin
        margin_left:
          type: number
          description: Left margin
        margin_right:
          type: number
          description: Right margin
        orientation:
          type: string
          enum:
          - portrait
          - landscape
          description: Page orientation
          example: portrait
        print_background:
          type: boolean
          description: Whether to render background graphics
        scale:
          type: number
          description: Render scale factor
          example: 1
        title:
          type: string
          description: PDF document title
        author:
          type: string
          description: PDF document author
        subject:
          type: string
          description: PDF document subject
      description: Optional PDF rendering options passed to the conversion service
    ConvertHtmlToPdfRequest:
      type: object
      properties:
        html_content:
          type: string
          format: binary
          description: HTML file to convert to PDF (required).
        assets:
          type: array
          items:
            type: string
            format: binary
          description: Optional asset files referenced by the HTML (images, fonts, CSS).
        rendering_options:
          description: Optional rendering options, sent as a JSON-encoded string form field.
          allOf:
          - $ref: '#/components/schemas/ConvertHtmlToPdfRenderingOptions'
      required:
      - html_content
      description: Multipart request to convert an HTML document (plus optional assets) to a PDF. Max 32 MB total.
    DocumentUploadCompanyValidationSchema:
      $ref: '#/components/schemas/DocumentUploadSchema'
    DocumentUploadResponseSchema:
      type: object
      properties:
        id:
          type: number
        str_id:
          type: string
        sync_id:
          type: string
          nullable: true
      required:
      - id
      - str_id
      - sync_id
    DocumentUploadSchema:
      type: object
      properties:
        type:
          type: string
          enum:
          - commission
          - policy
          - compgrid
        file:
          type: file
          description: File to upload
        company_id:
          type: string
          maxLength: 36
          description: "Identifier (stored as sync_id of company entity) for the company synced from third-party systems.\
            \ \n\n**Note:** At least one of `company_id` or `company_name` is required."
          example: '1234'
        company_name:
          type: string
          maxLength: 100
          description: "Name of the carrier / company. \n\n**Note:** At least one of `company_id` or `company_name` is required."
          example: Company name
        is_upline:
          type: boolean
          default: false
          description: Indicates the provided company_name refers to an upline company
          example: false
        bank_total_amount:
          type: number
          description: Bank deposit amount for commission statements
          example: 1000
        statement_amount:
          type: number
          description: Statement amount for commission statements
          example: 1000
        check_date:
          type: string
          description: Date of the check
          format: date
        deposit_date:
          type: string
          description: Date of the deposit
          format: date
        filename:
          type: string
          description: Filename of the file
          example: filename.pdf
        notes:
          type: string
          description: Notes for the document
          example: ''
        sync_id:
          type: string
          description: Unique id for document. Currently unused, but allows for referencing file in the future.
          example: ZBcA7v_iwNGGHR9r4xAiD
      description: A document uploaded to the server. At least one of company_id or company_name must be provided. If neither
        is supplied and the system cannot determine the company automatically, the request will be rejected.
      required:
      - file
      - type
    FlattenedPublishedReportSchema:
      type: object
      properties:
        id:
          type: integer
          description: Numeric identifier of the published report access record (legacy). Prefer `str_id` for follow-up calls.
          example: 42
        str_id:
          type: string
          nullable: true
          description: String identifier of the published report access record. Pass this value as `{id}` to `GET /openapi/analytics/reports/{id}`.
          example: rpt_abc123xyz
        name:
          type: string
          description: Display name of the published report
          example: Agency receivables by policy
        principal_type:
          type: string
          enum:
          - account
          - user
          - role
          description: Access principal type that scopes who can run the report
          example: account
        account_id:
          type: string
          nullable: true
          description: Account the report access record belongs to
          example: acct_7f3c2b1a
        selected_columns:
          type: array
          items:
            type: string
          description: Columns selected for the report, resolved against the dataset schema
          example:
          - policy_number
          - premium_amount
          - effective_date
        group_by_columns:
          type: array
          items:
            type: string
          description: Columns used for grouping when measures are configured
          example:
          - carrier_name
        column_order:
          type: array
          items:
            type: string
          description: Preferred column ordering for the report UI and exports
          example:
          - policy_number
          - premium_amount
        columns:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsReportColumnMetadataSchema'
          description: Dataset column metadata for the report backing table
        measures:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsReportMeasureSchema'
          description: Configured aggregations appended to report output
        column_header_names:
          nullable: true
          description: Optional custom header labels keyed by column name
        output_columns:
          type: array
          items:
            type: string
          description: Final column list returned by `GET /openapi/analytics/reports/{id}` (dimensions plus measure output
            names)
          example:
          - policy_number
          - premium_amount
          - total_premium
        date_key:
          type: string
          nullable: true
          description: Dataset column used as the default date filter when querying report data
          example: effective_date
        dataset_description:
          type: string
          nullable: true
          description: Human-readable description of the backing dataset
          example: Receivables aggregated at the policy level
        updated_at:
          type: string
          nullable: true
          format: date-time
          description: ISO-8601 timestamp when the report access record was last updated (falls back to `created_at` when
            absent)
          example: '2026-04-06T18:00:00.000Z'
        dataset_id:
          type: string
          description: Fully qualified BigQuery table identifier for the dataset
          example: fintary-prod.analytics_reports.agency_receivables_by_policy
        state:
          type: string
          nullable: true
          description: Lifecycle state of the report access record
          example: active
        published:
          type: boolean
          nullable: true
          description: Whether the report access record is published
          example: true
        description:
          type: string
          nullable: true
          description: Optional description of the published report
        filters:
          type: array
          items:
            $ref: '#/components/schemas/AnalyticsReportFilterSchema'
          description: Pre-configured filters applied when the report is run
        created_at:
          type: string
          nullable: true
          format: date-time
          description: ISO-8601 timestamp when the report access record was created
          example: '2026-01-15T12:30:00.000Z'
      required:
      - selected_columns
      - column_order
      - columns
      - measures
      - output_columns
      - date_key
      - dataset_description
      - dataset_id
      description: Published analytics report metadata flattened per access record, including resolved dataset columns
    OpenAgentCreateSchema:
      type: object
      properties:
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
          format: email
        phone:
          type: string
          nullable: true
        agent_code:
          type: string
          nullable: true
        company_name:
          type: string
          nullable: true
        type:
          nullable: true
          anyOf:
          - type: string
            enum:
            - Sales rep
            - Agent
            - IMO
            - Agency
          - type: array
            items:
              type: string
              enum:
              - Sales rep
              - Agent
              - IMO
              - Agency
          description: 'Type of the agent. Known values: Sales rep, Agent, IMO, Agency'
        start_date:
          type: string
          nullable: true
          description: ISO datetime string
          format: date-time
        status:
          type: string
          nullable: true
          enum:
          - Inactive
          - Terminated
          - active
          - archived
          - manager
          - current
          description: Status of the agent
        payout_level:
          type: string
          nullable: true
        payable_status:
          type: string
          nullable: true
          enum:
          - payable
          - non_payable
          - pay_to_upline
          description: Payable status of the agent
        bank_info:
          type: string
          nullable: true
        notes:
          type: string
          nullable: true
        sync_id:
          type: string
          minLength: 1
          description: Client system identifier for the agent. Used for syncing with external systems; Fintary generates its
            own str_id internally.
      description: Input for creating a new agent
    OpenAgentDatasetPage:
      type: object
      properties:
        rows:
          type: array
          items:
            type: object
            additionalProperties: {}
          description: Dataset rows for the current page. Columns are determined by the underlying analytics dataset and are
            not statically typed. Additional non-reserved query parameters are applied as column filters.
        pageRowCount:
          type: integer
          minimum: 0
          description: Number of rows returned on the current page
          example: 20
        rowCount:
          type: integer
          minimum: 0
          description: Total number of rows matching the query across all pages
          example: 137
        startDate:
          type: string
          nullable: true
          format: date-time
          description: Resolved start of the date filter window, when applied
          example: '2026-01-01T00:00:00.000Z'
        endDate:
          type: string
          nullable: true
          format: date-time
          description: Resolved end of the date filter window, when applied
          example: '2026-03-31T23:59:59.999Z'
        page:
          type: integer
          minimum: 0
          description: Zero-based page index returned
          example: 0
      required:
      - rows
      - pageRowCount
      - rowCount
      description: Paginated dataset rows returned by the agent commissions, payouts, policies, and dashboard endpoints. Wrapped
        in the standard Open API response envelope under `data`.
    OpenAgentDetailSchema:
      type: object
      properties:
        id:
          type: number
        str_id:
          type: string
          nullable: true
        sync_id:
          type: string
          nullable: true
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
          format: email
        phone:
          type: string
          nullable: true
        agent_code:
          type: string
          nullable: true
        company_name:
          type: string
          nullable: true
        type:
          nullable: true
          anyOf:
          - type: string
            enum:
            - Sales rep
            - Agent
            - IMO
            - Agency
          - type: array
            items:
              type: string
              enum:
              - Sales rep
              - Agent
              - IMO
              - Agency
          description: 'Type of the agent. Known values: Sales rep, Agent, IMO, Agency'
        start_date:
          type: string
          nullable: true
          description: ISO date string
          format: date
        status:
          type: string
          nullable: true
          enum:
          - Inactive
          - Terminated
          - active
          - archived
          - manager
          - current
          description: Status of the agent
        payout_level:
          type: string
          nullable: true
        payable_status:
          type: string
          nullable: true
          enum:
          - payable
          - non_payable
          - pay_to_upline
          description: Payable status of the agent
        bank_info:
          type: string
          nullable: true
        notes:
          type: string
          nullable: true
        created_at:
          type: string
          description: ISO datetime when created
          format: date-time
        created_by:
          type: string
          nullable: true
        updated_at:
          type: string
          description: ISO datetime when last updated
          format: date-time
        updated_by:
          type: string
          nullable: true
        parent_relationships:
          type: array
          items:
            type: object
            properties:
              str_id:
                type: string
                nullable: true
                description: Fintary-generated identifier for this hierarchy relationship (contact_hierarchy.str_id). Use
                  when removing upline.
              start_date:
                type: string
                nullable: true
                format: date-time
              end_date:
                type: string
                nullable: true
                format: date-time
              split_percentage:
                nullable: true
              sync_id:
                type: string
                nullable: true
                description: Client system identifier for this hierarchy relationship (contact_hierarchy.sync_id).
              created_at:
                type: string
                format: date-time
              parent:
                type: object
                nullable: true
                properties:
                  str_id:
                    type: string
                    nullable: true
                  sync_id:
                    type: string
                    nullable: true
                  first_name:
                    type: string
                    nullable: true
                  last_name:
                    type: string
                    nullable: true
                  email:
                    type: string
                    nullable: true
                    format: email
                  phone:
                    type: string
                    nullable: true
                  agent_code:
                    type: string
                    nullable: true
                  status:
                    type: string
                    nullable: true
                required:
                - str_id
                - sync_id
                - first_name
                - last_name
                - email
                - phone
                - agent_code
                - status
            required:
            - str_id
            - start_date
            - end_date
            - sync_id
            - created_at
            - parent
        child_relationships:
          type: array
          items:
            type: object
            properties:
              str_id:
                type: string
                nullable: true
                description: Fintary-generated identifier for this hierarchy relationship (contact_hierarchy.str_id). Use
                  when removing upline.
              start_date:
                type: string
                nullable: true
                format: date-time
              end_date:
                type: string
                nullable: true
                format: date-time
              split_percentage:
                nullable: true
              sync_id:
                type: string
                nullable: true
                description: Client system identifier for this hierarchy relationship (contact_hierarchy.sync_id).
              created_at:
                type: string
                format: date-time
              contact:
                type: object
                properties:
                  str_id:
                    type: string
                    nullable: true
                  sync_id:
                    type: string
                    nullable: true
                  first_name:
                    type: string
                    nullable: true
                  last_name:
                    type: string
                    nullable: true
                  email:
                    type: string
                    nullable: true
                    format: email
                  phone:
                    type: string
                    nullable: true
                  agent_code:
                    type: string
                    nullable: true
                  status:
                    type: string
                    nullable: true
                required:
                - str_id
                - sync_id
                - first_name
                - last_name
                - email
                - phone
                - agent_code
                - status
            required:
            - str_id
            - start_date
            - end_date
            - sync_id
            - created_at
            - contact
      required:
      - id
      - str_id
      - sync_id
      - first_name
      - last_name
      - email
      - phone
      - agent_code
      - company_name
      - type
      - start_date
      - status
      - payout_level
      - payable_status
      - bank_info
      - notes
      - created_at
      - created_by
      - updated_at
      - updated_by
      - parent_relationships
      - child_relationships
      description: Agent detail
    OpenAgentIdParamSchema:
      type: object
      properties:
        id:
          type: string
          minLength: 1
      required:
      - id
      description: Path param for agent identifier. Supports str_id, agent_code, or sync_id.
    OpenAgentListQuerySchema:
      type: object
      properties:
        status:
          type: string
          enum:
          - Inactive
          - Terminated
          - active
          - archived
          - manager
          - current
          description: Filter by agent status
        company_name:
          type: string
        type:
          type: string
          enum:
          - Sales rep
          - Agent
          - IMO
          - Agency
          description: Filter by agent type
        page:
          type: integer
          minimum: 0
        limit:
          type: integer
          minimum: 1
          maximum: 1000
      description: Query params for listing agents
    OpenAgentListResponseSchema:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/OpenAgentDetailSchema'
        count:
          type: integer
          minimum: 0
      required:
      - items
      - count
      description: Paginated list of agents with total count
    OpenAgentUpdateSchema:
      type: object
      properties:
        first_name:
          type: string
          nullable: true
        last_name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
          format: email
        phone:
          type: string
          nullable: true
        agent_code:
          type: string
          nullable: true
        company_name:
          type: string
          nullable: true
        type:
          nullable: true
          anyOf:
          - type: string
            enum:
            - Sales rep
            - Agent
            - IMO
            - Agency
          - type: array
            items:
              type: string
              enum:
              - Sales rep
              - Agent
              - IMO
              - Agency
          description: 'Type of the agent. Known values: Sales rep, Agent, IMO, Agency'
        start_date:
          type: string
          nullable: true
          description: ISO datetime string
          format: date-time
        status:
          type: string
          nullable: true
          enum:
          - Inactive
          - Terminated
          - active
          - archived
          - manager
          - current
          description: Status of t

# --- truncated at 32 KB (88 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/fintary/refs/heads/main/openapi/fintary-open-api-openapi.yml