Finch Connect API

openapi: 3.2.0
info:
  title: Reference Connect API
  version: '2020-09-17'
  contact: {}
  description: 'The Finch HRIS API provides a unified way to connect to a multitide of HRIS systems. The API requires an access token issued by Finch.


    By default, Organization and Payroll requests use Finch''s Data Syncs. If a request is made before the initial sync has completed, Finch will request data live from the provider. The latency on live requests may range from seconds to minutes depending on the provider and batch size.

    For automated integrations, Deductions requests (both read and write) are always made live to the provider. Latencies may range from seconds to minutes depending on the provider and batch size.


    Employer products are specified by the product parameter, a space-separated list of products that your application requests from an employer authenticating through Finch Connect. Valid product names are—

    - `company`: Read basic company data


    - `directory`: Read company directory and organization structure


    - `individual`: Read individual data, excluding income and employment data


    - `employment`: Read individual employment and income data


    - `payment`: Read payroll and contractor related payments by the company


    - `pay_statement`: Read detailed pay statements for each individual


    - `benefits`: Create and manage deductions and contributions and enrollment for an employer


    ![Open in Postman](https://god.gw.postman.com/run-collection/21027137-08db0929-883d-4094-a9ce-dbf5a9bee4a4?action=collection%2Ffork&collection-url=entityId%3D21027137-08db0929-883d-4094-a9ce-dbf5a9bee4a4%26entityType%3Dcollection%26workspaceId%3D1edf19bc-e0a8-41e9-ac55-481a4b50790b)'
servers:
- url: https://api.tryfinch.com
  description: ''
tags:
- name: Connect
paths:
  /connect/sessions:
    post:
      summary: Create a new connect session
      description: Create a new connect session for an employer
      operationId: post-connect-sessions
      tags:
      - Connect
      parameters:
      - $ref: '#/components/parameters/API-Version'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConnectSessionRequest'
      security:
      - basicAuth: []
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateConnectSessionResponse'
              examples:
                Success:
                  value:
                    session_id: 550e8400-e29b-41d4-a716-446655440000
                    connect_url: https://connect.tryfinch.com/authorize?session=550e8400-e29b-41d4-a716-446655440000
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  finch_code:
                    type: string
                    enum:
                    - connection_already_exists
                    - invalid_request
                    example: connection_already_exists
                  message:
                    type: string
                    example: 'There''s an existing connection for the customer_id: {customer_id}. Please use the /connect/sessions/reauthenticate endpoint instead.'
                  name:
                    type: string
                    example: bad_request
                  context:
                    type: object
                    properties:
                      customer_id:
                        type: string
                      connection_id:
                        type: string
                required:
                - code
                - finch_code
                - message
                - name
                - context
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  finch_code:
                    type: string
                    example: invalid_client
                  message:
                    type: string
                    example: 'Invalid client: Unable to validate credentials'
                required:
                - code
                - finch_code
                - message
      x-codeSamples:
      - lang: JavaScript
        source: "import Finch from '@tryfinch/finch-api';\n\nconst client = new Finch({\n  clientID: process.env['FINCH_CLIENT_ID'], // This is the default and can be omitted\n  clientSecret: process.env['FINCH_CLIENT_SECRET'], // This is the default and can be omitted\n});\n\nconst response = await client.connect.sessions.new({\n  customer_id: 'x',\n  customer_name: 'x',\n  products: ['benefits'],\n});\n\nconsole.log(response.session_id);"
      - lang: Python
        source: "import os\nfrom finch import Finch\n\nclient = Finch(\n    client_id=os.environ.get(\"FINCH_CLIENT_ID\"),  # This is the default and can be omitted\n    client_secret=os.environ.get(\"FINCH_CLIENT_SECRET\"),  # This is the default and can be omitted\n)\nresponse = client.connect.sessions.new(\n    customer_id=\"x\",\n    customer_name=\"x\",\n    products=[\"benefits\"],\n)\nprint(response.session_id)"
      - lang: Go
        source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/Finch-API/finch-api-go/v2\"\n\t\"github.com/Finch-API/finch-api-go/v2/option\"\n)\n\nfunc main() {\n\tclient := finchgo.NewClient(\n\t\toption.WithClientID(\"4ab15e51-11ad-49f4-acae-f343b7794375\"),\n\t\toption.WithClientSecret(\"My Client Secret\"),\n\t)\n\tresponse, err := client.Connect.Sessions.New(context.TODO(), finchgo.ConnectSessionNewParams{\n\t\tCustomerID:   finchgo.F(\"x\"),\n\t\tCustomerName: finchgo.F(\"x\"),\n\t\tProducts:     finchgo.F([]finchgo.ConnectSessionNewParamsProduct{finchgo.ConnectSessionNewParamsProductBenefits}),\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.SessionID)\n}\n"
      - lang: Java
        source: "package com.tryfinch.api.example;\n\nimport com.tryfinch.api.client.FinchClient;\nimport com.tryfinch.api.client.okhttp.FinchOkHttpClient;\nimport com.tryfinch.api.models.ConnectSessionNewParams;\nimport com.tryfinch.api.models.SessionNewResponse;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        FinchClient client = FinchOkHttpClient.fromEnv();\n\n        ConnectSessionNewParams params = ConnectSessionNewParams.builder()\n            .customerId(\"x\")\n            .customerName(\"x\")\n            .addProduct(ConnectSessionNewParams.ConnectProducts.BENEFITS)\n            .build();\n        SessionNewResponse response = client.connect().sessions().new_(params);\n    }\n}"
      - lang: Kotlin
        source: "package com.tryfinch.api.example\n\nimport com.tryfinch.api.client.FinchClient\nimport com.tryfinch.api.client.okhttp.FinchOkHttpClient\nimport com.tryfinch.api.models.ConnectSessionNewParams\nimport com.tryfinch.api.models.SessionNewResponse\n\nfun main() {\n    val client: FinchClient = FinchOkHttpClient.fromEnv()\n\n    val params: ConnectSessionNewParams = ConnectSessionNewParams.builder()\n        .customerId(\"x\")\n        .customerName(\"x\")\n        .addProduct(ConnectSessionNewParams.ConnectProducts.BENEFITS)\n        .build()\n    val response: SessionNewResponse = client.connect().sessions().new(params)\n}"
      - lang: Ruby
        source: 'require "finch_api"


          finch = FinchAPI::Client.new(client_id: "4ab15e51-11ad-49f4-acae-f343b7794375", client_secret: "My Client Secret")


          response = finch.connect.sessions.new(customer_id: "x", customer_name: "x", products: [:benefits])


          puts(response)'
  /connect/sessions/reauthenticate:
    post:
      summary: Create a new Connect session for reauthentication
      description: Create a new Connect session for reauthenticating an existing connection
      operationId: post-connect-sessions-reauthenticate
      tags:
      - Connect
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReauthenticateRequest'
      security:
      - basicAuth: []
      responses:
        '201':
          description: Created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReauthenticateResponse'
              examples:
                Success:
                  value:
                    session_id: 550e8400-e29b-41d4-a716-446655440000
                    connect_url: https://connect.tryfinch.com/authorize?session=550e8400-e29b-41d4-a716-446655440000
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  finch_code:
                    type: string
                    enum:
                    - connection_not_found
                    - invalid_request
                required:
                - code
                - finch_code
              examples:
                ConnectionNotFound:
                  value:
                    code: 400
                    finch_code: invalid_request
                    message: Connection not found
                    name: bad_request
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 401
                  finch_code:
                    type: string
                    example: invalid_client
                  message:
                    type: string
                    example: 'Invalid client: Unable to validate credentials'
                required:
                - code
                - finch_code
                - message
      x-codeSamples:
      - lang: JavaScript
        source: "import Finch from '@tryfinch/finch-api';\n\nconst client = new Finch({\n  clientID: process.env['FINCH_CLIENT_ID'], // This is the default and can be omitted\n  clientSecret: process.env['FINCH_CLIENT_SECRET'], // This is the default and can be omitted\n});\n\nconst response = await client.connect.sessions.reauthenticate({ connection_id: 'connection_id' });\n\nconsole.log(response.session_id);"
      - lang: Python
        source: "import os\nfrom finch import Finch\n\nclient = Finch(\n    client_id=os.environ.get(\"FINCH_CLIENT_ID\"),  # This is the default and can be omitted\n    client_secret=os.environ.get(\"FINCH_CLIENT_SECRET\"),  # This is the default and can be omitted\n)\nresponse = client.connect.sessions.reauthenticate(\n    connection_id=\"connection_id\",\n)\nprint(response.session_id)"
      - lang: Go
        source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/Finch-API/finch-api-go/v2\"\n\t\"github.com/Finch-API/finch-api-go/v2/option\"\n)\n\nfunc main() {\n\tclient := finchgo.NewClient(\n\t\toption.WithClientID(\"4ab15e51-11ad-49f4-acae-f343b7794375\"),\n\t\toption.WithClientSecret(\"My Client Secret\"),\n\t)\n\tresponse, err := client.Connect.Sessions.Reauthenticate(context.TODO(), finchgo.ConnectSessionReauthenticateParams{\n\t\tConnectionID: finchgo.F(\"connection_id\"),\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", response.SessionID)\n}\n"
      - lang: Java
        source: "package com.tryfinch.api.example;\n\nimport com.tryfinch.api.client.FinchClient;\nimport com.tryfinch.api.client.okhttp.FinchOkHttpClient;\nimport com.tryfinch.api.models.ConnectSessionReauthenticateParams;\nimport com.tryfinch.api.models.SessionReauthenticateResponse;\n\npublic final class Main {\n    private Main() {}\n\n    public static void main(String[] args) {\n        FinchClient client = FinchOkHttpClient.fromEnv();\n\n        ConnectSessionReauthenticateParams params = ConnectSessionReauthenticateParams.builder()\n            .connectionId(\"connection_id\")\n            .build();\n        SessionReauthenticateResponse response = client.connect().sessions().reauthenticate(params);\n    }\n}"
      - lang: Kotlin
        source: "package com.tryfinch.api.example\n\nimport com.tryfinch.api.client.FinchClient\nimport com.tryfinch.api.client.okhttp.FinchOkHttpClient\nimport com.tryfinch.api.models.ConnectSessionReauthenticateParams\nimport com.tryfinch.api.models.SessionReauthenticateResponse\n\nfun main() {\n    val client: FinchClient = FinchOkHttpClient.fromEnv()\n\n    val params: ConnectSessionReauthenticateParams = ConnectSessionReauthenticateParams.builder()\n        .connectionId(\"connection_id\")\n        .build()\n    val response: SessionReauthenticateResponse = client.connect().sessions().reauthenticate(params)\n}"
      - lang: Ruby
        source: 'require "finch_api"


          finch = FinchAPI::Client.new(client_id: "4ab15e51-11ad-49f4-acae-f343b7794375", client_secret: "My Client Secret")


          response = finch.connect.sessions.reauthenticate(connection_id: "connection_id")


          puts(response)'
components:
  schemas:
    ReauthenticateResponse:
      type: object
      properties:
        session_id:
          type: string
          description: The unique identifier for the created connect session
        connect_url:
          type: string
          format: uri
          description: The Connect URL to redirect the user to for reauthentication
      required:
      - session_id
      - connect_url
    CreateConnectSessionResponse:
      type: object
      properties:
        session_id:
          type: string
          description: The unique identifier for the created connect session
        connect_url:
          type: string
          format: uri
          description: The Connect URL to redirect the user to for authentication
      required:
      - session_id
      - connect_url
    CreateConnectSessionRequest:
      type: object
      properties:
        customer_id:
          type: string
          minLength: 1
          maxLength: 255
          description: Unique identifier for the customer
        customer_name:
          type: string
          minLength: 1
          maxLength: 255
          description: Name of the customer
        customer_email:
          type: string
          nullable: true
          format: email
          description: Email address of the customer
        products:
          type: array
          items:
            $ref: '#/components/schemas/ConnectProducts'
          description: The Finch products to request access to. Use `benefits` to access deductions endpoints — `deduction` is a deprecated alias that is still accepted but should not be combined with `benefits`.
        redirect_uri:
          type: string
          nullable: true
          description: The URI to redirect to after the Connect flow is completed
        minutes_to_expire:
          type: number
          nullable: true
          minimum: 1
          maximum: 129600
          description: The number of minutes until the session expires (defaults to 129,600, which is 90 days)
        sandbox:
          type: string
          nullable: true
          enum:
          - finch
          - provider
          - null
          description: Sandbox mode for testing
        manual:
          type: boolean
          nullable: true
          description: Enable manual authentication mode
        integration:
          type: object
          nullable: true
          properties:
            provider:
              type: string
              description: The provider to integrate with
            auth_method:
              type: string
              nullable: true
              enum:
              - assisted
              - credential
              - oauth
              - api_token
              - null
              description: The authentication method to use
          required:
          - provider
          description: Integration configuration for the connect session
        recordkeeping:
          $ref: '#/components/schemas/Recordkeeping'
      required:
      - customer_id
      - customer_name
      - products
    Recordkeeping:
      type: object
      nullable: true
      properties:
        plan_id:
          type: string
          nullable: true
          minLength: 1
          description: The plan identifier used by the recordkeeper
        recordkeeper:
          type: string
          enum:
          - voya
          - empower
          - fidelity
          - transamerica
          description: The recordkeeper to configure for this connection
      required:
      - recordkeeper
      description: Optional recordkeeping configuration. Can only be provided when the `recordkeeping` product is requested. Currently supports `recordkeeper` set to `voya`, `empower`, `fidelity`, or `transamerica`.
    ConnectProducts:
      type: string
      enum:
      - benefits
      - company
      - deduction
      - directory
      - documents
      - employment
      - individual
      - payment
      - pay_statement
      - plans
      - plans_dependents
      - plans_enrollments
      - recordkeeping
      - ssn
    ReauthenticateRequest:
      type: object
      properties:
        redirect_uri:
          type: string
          nullable: true
          format: uri
          description: The URI to redirect to after the Connect flow is completed
        minutes_to_expire:
          type: integer
          description: The number of minutes until the session expires (defaults to 43,200, which is 30 days)
        products:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/ConnectProducts'
          description: The products to request access to (optional for reauthentication). Use `benefits` to access deductions endpoints — `deduction` is a deprecated alias that is still accepted but should not be combined with `benefits`.
        connection_id:
          type: string
          description: The ID of the existing connection to reauthenticate
      required:
      - connection_id
  parameters:
    API-Version:
      name: Finch-API-Version
      in: header
      required: true
      schema:
        type: string
        default: '2020-09-17'
        format: date
      description: Header used to specify the version for a given API request. Current version is 2020-09-17.
      x-stainless-param: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Please use your Access Token
    basicAuth:
      type: http
      scheme: basic
      description: Please use base64 encoded client_id:client_secret
x-provenance:
  method: harvested
  publisher: Finch
  source: https://developer.tryfinch.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)