Finch API

naftiko: 1.0.0-alpha2
info:
  label: Finch API
  description: Finch is a unified employment API that lets developers integrate with HRIS, payroll, and benefits systems through
    a single interface. The API exposes Company, Directory, Individual, Employment, Payment, Pay Statement, and Benefits resources,
    plus Sandbox endpoints for testing.
  tags:
  - Finch
  - API
  created: '2026-05-06'
  modified: '2026-05-06'
capability:
  consumes:
  - type: http
    namespace: finch
    baseUri: https://api.tryfinch.com
    description: Finch API HTTP API.
    authentication:
      type: bearer
      token: '{{FINCH_TOKEN}}'
    resources:
    - name: connect-sessions
      path: /connect/sessions
      operations:
      - name: createconnectsession
        method: POST
        description: Create a Finch Connect session
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: auth-token
      path: /auth/token
      operations:
      - name: exchangeauthcode
        method: POST
        description: Exchange authorization code for access token
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: employer-company
      path: /employer/company
      operations:
      - name: getcompany
        method: GET
        description: Get connected company information
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: employer-directory
      path: /employer/directory
      operations:
      - name: listdirectory
        method: GET
        description: List employees in the company directory
        inputParameters:
        - name: limit
          in: query
          type: integer
        - name: offset
          in: query
          type: integer
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: employer-individual
      path: /employer/individual
      operations:
      - name: getindividuals
        method: POST
        description: Get individual records (PII)
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: employer-employment
      path: /employer/employment
      operations:
      - name: getemployment
        method: POST
        description: Get employment records
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: employer-payment
      path: /employer/payment
      operations:
      - name: listpayments
        method: GET
        description: List company payments (pay runs)
        inputParameters:
        - name: start_date
          in: query
          type: string
        - name: end_date
          in: query
          type: string
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: employer-pay-statement
      path: /employer/pay-statement
      operations:
      - name: getpaystatements
        method: POST
        description: Get pay statements for one or more payments
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
    - name: employer-benefits
      path: /employer/benefits
      operations:
      - name: listbenefits
        method: GET
        description: List company benefits
        outputRawFormat: json
        outputParameters:
        - name: result
          type: object
          value: $.
  exposes:
  - type: rest
    port: 8080
    namespace: finch-rest
    description: REST adapter for Finch API.
    resources:
    - path: /connect/sessions
      name: createconnectsession
      operations:
      - method: POST
        name: createconnectsession
        description: Create a Finch Connect session
        call: finch.createconnectsession
        outputParameters:
        - type: object
          mapping: $.
    - path: /auth/token
      name: exchangeauthcode
      operations:
      - method: POST
        name: exchangeauthcode
        description: Exchange authorization code for access token
        call: finch.exchangeauthcode
        outputParameters:
        - type: object
          mapping: $.
    - path: /employer/company
      name: getcompany
      operations:
      - method: GET
        name: getcompany
        description: Get connected company information
        call: finch.getcompany
        outputParameters:
        - type: object
          mapping: $.
    - path: /employer/directory
      name: listdirectory
      operations:
      - method: GET
        name: listdirectory
        description: List employees in the company directory
        call: finch.listdirectory
        outputParameters:
        - type: object
          mapping: $.
    - path: /employer/individual
      name: getindividuals
      operations:
      - method: POST
        name: getindividuals
        description: Get individual records (PII)
        call: finch.getindividuals
        outputParameters:
        - type: object
          mapping: $.
    - path: /employer/employment
      name: getemployment
      operations:
      - method: POST
        name: getemployment
        description: Get employment records
        call: finch.getemployment
        outputParameters:
        - type: object
          mapping: $.
    - path: /employer/payment
      name: listpayments
      operations:
      - method: GET
        name: listpayments
        description: List company payments (pay runs)
        call: finch.listpayments
        outputParameters:
        - type: object
          mapping: $.
    - path: /employer/pay-statement
      name: getpaystatements
      operations:
      - method: POST
        name: getpaystatements
        description: Get pay statements for one or more payments
        call: finch.getpaystatements
        outputParameters:
        - type: object
          mapping: $.
    - path: /employer/benefits
      name: listbenefits
      operations:
      - method: GET
        name: listbenefits
        description: List company benefits
        call: finch.listbenefits
        outputParameters:
        - type: object
          mapping: $.
  - type: mcp
    port: 9090
    namespace: finch-mcp
    transport: http
    description: MCP adapter for Finch API for AI agent use.
    tools:
    - name: createconnectsession
      description: Create a Finch Connect session
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: finch.createconnectsession
      outputParameters:
      - type: object
        mapping: $.
    - name: exchangeauthcode
      description: Exchange authorization code for access token
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: finch.exchangeauthcode
      outputParameters:
      - type: object
        mapping: $.
    - name: getcompany
      description: Get connected company information
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: finch.getcompany
      outputParameters:
      - type: object
        mapping: $.
    - name: listdirectory
      description: List employees in the company directory
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: finch.listdirectory
      with:
        limit: tools.limit
        offset: tools.offset
      inputParameters:
      - name: limit
        type: integer
        description: limit
      - name: offset
        type: integer
        description: offset
      outputParameters:
      - type: object
        mapping: $.
    - name: getindividuals
      description: Get individual records (PII)
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: finch.getindividuals
      outputParameters:
      - type: object
        mapping: $.
    - name: getemployment
      description: Get employment records
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: finch.getemployment
      outputParameters:
      - type: object
        mapping: $.
    - name: listpayments
      description: List company payments (pay runs)
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: finch.listpayments
      with:
        start_date: tools.start_date
        end_date: tools.end_date
      inputParameters:
      - name: start_date
        type: string
        description: start_date
      - name: end_date
        type: string
        description: end_date
      outputParameters:
      - type: object
        mapping: $.
    - name: getpaystatements
      description: Get pay statements for one or more payments
      hints:
        readOnly: false
        destructive: false
        idempotent: false
      call: finch.getpaystatements
      outputParameters:
      - type: object
        mapping: $.
    - name: listbenefits
      description: List company benefits
      hints:
        readOnly: true
        destructive: false
        idempotent: true
      call: finch.listbenefits
      outputParameters:
      - type: object
        mapping: $.
binds:
- namespace: env
  keys:
    FINCH_TOKEN: FINCH_TOKEN