finch-api 0.1.0.pre.alpha.1

data/lib/finch-api/resources/jobs/automated.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Jobs
+      class Automated
+        # Enqueue an automated job.
+        #
+        #   `data_sync_all`: Enqueue a job to re-sync all data for a connection.
+        #   `data_sync_all` has a concurrency limit of 1 job at a time per connection. This
+        #   means that if this endpoint is called while a job is already in progress for
+        #   this connection, Finch will return the `job_id` of the job that is currently in
+        #   progress. Finch allows a fixed window rate limit of 1 forced refresh per hour
+        #   per connection.
+        #
+        #   `w4_form_employee_sync`: Enqueues a job for sync W-4 data for a particular
+        #   individual, identified by `individual_id`. This feature is currently in beta.
+        #
+        #   This endpoint is available for _Scale_ tier customers as an add-on. To request
+        #   access to this endpoint, please contact your Finch account manager.
+        #
+        # @param params [FinchAPI::Models::Jobs::AutomatedCreateParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [Symbol, FinchAPI::Models::Jobs::AutomatedCreateParams::Type] :type The type of job to start.
+        #
+        #   @option params [FinchAPI::Models::Jobs::AutomatedCreateParams::Params] :params
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::Jobs::AutomatedCreateResponse]
+        #
+        def create(params)
+          parsed, options = FinchAPI::Models::Jobs::AutomatedCreateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "jobs/automated",
+            body: parsed,
+            model: FinchAPI::Models::Jobs::AutomatedCreateResponse,
+            options: options
+          )
+        end
+
+        # Get an automated job by `job_id`.
+        #
+        # @param job_id [String]
+        #
+        # @param params [FinchAPI::Models::Jobs::AutomatedRetrieveParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::Jobs::AutomatedAsyncJob]
+        #
+        def retrieve(job_id, params = {})
+          @client.request(
+            method: :get,
+            path: ["jobs/automated/%0s", job_id],
+            model: FinchAPI::Models::Jobs::AutomatedAsyncJob,
+            options: params[:request_options]
+          )
+        end
+
+        # Get all automated jobs. Automated jobs are completed by a machine. By default,
+        #   jobs are sorted in descending order by submission time. For scheduled jobs such
+        #   as data syncs, only the next scheduled job is shown.
+        #
+        # @param params [FinchAPI::Models::Jobs::AutomatedListParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [Integer] :limit Number of items to return
+        #
+        #   @option params [Integer] :offset Index to start from (defaults to 0)
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Page<FinchAPI::Models::Jobs::AutomatedAsyncJob>]
+        #
+        def list(params = {})
+          parsed, options = FinchAPI::Models::Jobs::AutomatedListParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: "jobs/automated",
+            query: parsed,
+            page: FinchAPI::Page,
+            model: FinchAPI::Models::Jobs::AutomatedAsyncJob,
+            options: options
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/jobs/manual.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Jobs
+      class Manual
+        # Get a manual job by `job_id`. Manual jobs are completed by a human and include
+        #   Assisted Benefits jobs.
+        #
+        # @param job_id [String]
+        #
+        # @param params [FinchAPI::Models::Jobs::ManualRetrieveParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::Jobs::ManualAsyncJob]
+        #
+        def retrieve(job_id, params = {})
+          @client.request(
+            method: :get,
+            path: ["jobs/manual/%0s", job_id],
+            model: FinchAPI::Models::Jobs::ManualAsyncJob,
+            options: params[:request_options]
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/jobs.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Jobs
+      # @return [FinchAPI::Resources::Jobs::Automated]
+      attr_reader :automated
+
+      # @return [FinchAPI::Resources::Jobs::Manual]
+      attr_reader :manual
+
+      # @param client [FinchAPI::Client]
+      #
+      def initialize(client:)
+        @client = client
+        @automated = FinchAPI::Resources::Jobs::Automated.new(client: client)
+        @manual = FinchAPI::Resources::Jobs::Manual.new(client: client)
+      end
+    end
+  end
+end

data/lib/finch-api/resources/payroll/pay_groups.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Payroll
+      class PayGroups
+        # Read information from a single pay group
+        #
+        # @param pay_group_id [String]
+        #
+        # @param params [FinchAPI::Models::Payroll::PayGroupRetrieveParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::Payroll::PayGroupRetrieveResponse]
+        #
+        def retrieve(pay_group_id, params = {})
+          @client.request(
+            method: :get,
+            path: ["employer/pay-groups/%0s", pay_group_id],
+            model: FinchAPI::Models::Payroll::PayGroupRetrieveResponse,
+            options: params[:request_options]
+          )
+        end
+
+        # Read company pay groups and frequencies
+        #
+        # @param params [FinchAPI::Models::Payroll::PayGroupListParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [String] :individual_id
+        #
+        #   @option params [Array<String>] :pay_frequencies
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::SinglePage<FinchAPI::Models::Payroll::PayGroupListResponse>]
+        #
+        def list(params = {})
+          parsed, options = FinchAPI::Models::Payroll::PayGroupListParams.dump_request(params)
+          @client.request(
+            method: :get,
+            path: "employer/pay-groups",
+            query: parsed,
+            page: FinchAPI::SinglePage,
+            model: FinchAPI::Models::Payroll::PayGroupListResponse,
+            options: options
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/payroll.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Payroll
+      # @return [FinchAPI::Resources::Payroll::PayGroups]
+      attr_reader :pay_groups
+
+      # @param client [FinchAPI::Client]
+      #
+      def initialize(client:)
+        @client = client
+        @pay_groups = FinchAPI::Resources::Payroll::PayGroups.new(client: client)
+      end
+    end
+  end
+end

data/lib/finch-api/resources/providers.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Providers
+      # Return details on all available payroll and HR systems.
+      #
+      # @param params [FinchAPI::Models::ProviderListParams, Hash{Symbol=>Object}] .
+      #
+      #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      #
+      # @return [FinchAPI::SinglePage<FinchAPI::Models::Provider>]
+      #
+      def list(params = {})
+        @client.request(
+          method: :get,
+          path: "providers",
+          page: FinchAPI::SinglePage,
+          model: FinchAPI::Models::Provider,
+          options: params[:request_options]
+        )
+      end
+
+      # @param client [FinchAPI::Client]
+      #
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/finch-api/resources/request_forwarding.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class RequestForwarding
+      # The Forward API allows you to make direct requests to an employment system. If
+      #   Finch’s unified API doesn’t have a data model that cleanly fits your needs, then
+      #   Forward allows you to push or pull data models directly against an integration’s
+      #   API.
+      #
+      # @param params [FinchAPI::Models::RequestForwardingForwardParams, Hash{Symbol=>Object}] .
+      #
+      #   @option params [String] :method_ The HTTP method for the forwarded request. Valid values include: `GET` , `POST`
+      #     , `PUT` , `DELETE` , and `PATCH`.
+      #
+      #   @option params [String] :route The URL route path for the forwarded request. This value must begin with a
+      #     forward-slash ( / ) and may only contain alphanumeric characters, hyphens, and
+      #     underscores.
+      #
+      #   @option params [String, nil] :data The body for the forwarded request. This value must be specified as either a
+      #     string or a valid JSON object.
+      #
+      #   @option params [Object, nil] :headers The HTTP headers to include on the forwarded request. This value must be
+      #     specified as an object of key-value pairs. Example:
+      #     `{"Content-Type": "application/xml", "X-API-Version": "v1" }`
+      #
+      #   @option params [Object, nil] :params The query parameters for the forwarded request. This value must be specified as
+      #     a valid JSON object rather than a query string.
+      #
+      #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+      #
+      # @return [FinchAPI::Models::RequestForwardingForwardResponse]
+      #
+      def forward(params)
+        parsed, options = FinchAPI::Models::RequestForwardingForwardParams.dump_request(params)
+        @client.request(
+          method: :post,
+          path: "forward",
+          body: parsed,
+          model: FinchAPI::Models::RequestForwardingForwardResponse,
+          options: options
+        )
+      end
+
+      # @param client [FinchAPI::Client]
+      #
+      def initialize(client:)
+        @client = client
+      end
+    end
+  end
+end

data/lib/finch-api/resources/sandbox/company.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Sandbox
+      class Company
+        # Update a sandbox company's data
+        #
+        # @param params [FinchAPI::Models::Sandbox::CompanyUpdateParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [Array<FinchAPI::Models::Sandbox::CompanyUpdateParams::Account>, nil] :accounts An array of bank account objects associated with the payroll/HRIS system.
+        #
+        #   @option params [Array<FinchAPI::Models::Sandbox::CompanyUpdateParams::Department, nil>, nil] :departments The array of company departments.
+        #
+        #   @option params [String, nil] :ein The employer identification number.
+        #
+        #   @option params [FinchAPI::Models::Sandbox::CompanyUpdateParams::Entity, nil] :entity The entity type object.
+        #
+        #   @option params [String, nil] :legal_name The legal name of the company.
+        #
+        #   @option params [Array<FinchAPI::Models::Location, nil>, nil] :locations
+        #
+        #   @option params [String, nil] :primary_email The email of the main administrator on the account.
+        #
+        #   @option params [String, nil] :primary_phone_number The phone number of the main administrator on the account. Format: `XXXXXXXXXX`
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::Sandbox::CompanyUpdateResponse]
+        #
+        def update(params)
+          parsed, options = FinchAPI::Models::Sandbox::CompanyUpdateParams.dump_request(params)
+          @client.request(
+            method: :put,
+            path: "sandbox/company",
+            body: parsed,
+            model: FinchAPI::Models::Sandbox::CompanyUpdateResponse,
+            options: options
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/sandbox/connections/accounts.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Sandbox
+      class Connections
+        class Accounts
+          # Create a new account for an existing connection (company/provider pair)
+          #
+          # @param params [FinchAPI::Models::Sandbox::Connections::AccountCreateParams, Hash{Symbol=>Object}] .
+          #
+          #   @option params [String] :company_id
+          #
+          #   @option params [String] :provider_id The provider associated with the `access_token`
+          #
+          #   @option params [Symbol, FinchAPI::Models::Sandbox::Connections::AccountCreateParams::AuthenticationType] :authentication_type
+          #
+          #   @option params [Array<String>] :products Optional, defaults to Organization products (`company`, `directory`,
+          #     `employment`, `individual`)
+          #
+          #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+          #
+          # @return [FinchAPI::Models::Sandbox::Connections::AccountCreateResponse]
+          #
+          def create(params)
+            parsed, options = FinchAPI::Models::Sandbox::Connections::AccountCreateParams.dump_request(params)
+            @client.request(
+              method: :post,
+              path: "sandbox/connections/accounts",
+              body: parsed,
+              model: FinchAPI::Models::Sandbox::Connections::AccountCreateResponse,
+              options: options
+            )
+          end
+
+          # Update an existing sandbox account. Change the connection status to understand
+          #   how the Finch API responds.
+          #
+          # @param params [FinchAPI::Models::Sandbox::Connections::AccountUpdateParams, Hash{Symbol=>Object}] .
+          #
+          #   @option params [Symbol, FinchAPI::Models::ConnectionStatusType] :connection_status
+          #
+          #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+          #
+          # @return [FinchAPI::Models::Sandbox::Connections::AccountUpdateResponse]
+          #
+          def update(params = {})
+            parsed, options = FinchAPI::Models::Sandbox::Connections::AccountUpdateParams.dump_request(params)
+            @client.request(
+              method: :put,
+              path: "sandbox/connections/accounts",
+              body: parsed,
+              model: FinchAPI::Models::Sandbox::Connections::AccountUpdateResponse,
+              options: options
+            )
+          end
+
+          # @param client [FinchAPI::Client]
+          #
+          def initialize(client:)
+            @client = client
+          end
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/sandbox/connections.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Sandbox
+      class Connections
+        # @return [FinchAPI::Resources::Sandbox::Connections::Accounts]
+        attr_reader :accounts
+
+        # Create a new connection (new company/provider pair) with a new account
+        #
+        # @param params [FinchAPI::Models::Sandbox::ConnectionCreateParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [String] :provider_id The provider associated with the connection
+        #
+        #   @option params [Symbol, FinchAPI::Models::Sandbox::ConnectionCreateParams::AuthenticationType] :authentication_type
+        #
+        #   @option params [Integer] :employee_size Optional: the size of the employer to be created with this connection. Defaults
+        #     to 20. Note that if this is higher than 100, historical payroll data will not be
+        #     generated, and instead only one pay period will be created.
+        #
+        #   @option params [Array<String>] :products
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::Sandbox::ConnectionCreateResponse]
+        #
+        def create(params)
+          parsed, options = FinchAPI::Models::Sandbox::ConnectionCreateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "sandbox/connections",
+            body: parsed,
+            model: FinchAPI::Models::Sandbox::ConnectionCreateResponse,
+            options: options
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+          @accounts = FinchAPI::Resources::Sandbox::Connections::Accounts.new(client: client)
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/sandbox/directory.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Sandbox
+      class Directory
+        # Add new individuals to a sandbox company
+        #
+        # @param params [FinchAPI::Models::Sandbox::DirectoryCreateParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [Array<FinchAPI::Models::Sandbox::DirectoryCreateParams::Body>] :body Array of individuals to create. Takes all combined fields from `/individual` and
+        #     `/employment` endpoints. All fields are optional.
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [Array<Object>]
+        #
+        def create(params = {})
+          parsed, options = FinchAPI::Models::Sandbox::DirectoryCreateParams.dump_request(params)
+          @client.request(
+            method: :post,
+            path: "sandbox/directory",
+            body: parsed[:body],
+            model: FinchAPI::ArrayOf[FinchAPI::Unknown],
+            options: options
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/sandbox/employment.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Sandbox
+      class Employment
+        # Update sandbox employment
+        #
+        # @param individual_id [String]
+        #
+        # @param params [FinchAPI::Models::Sandbox::EmploymentUpdateParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [String, nil] :class_code Worker's compensation classification code for this employee
+        #
+        #   @option params [Array<FinchAPI::Models::Sandbox::EmploymentUpdateParams::CustomField>] :custom_fields Custom fields for the individual. These are fields which are defined by the
+        #     employer in the system. Custom fields are not currently supported for assisted
+        #     connections.
+        #
+        #   @option params [FinchAPI::Models::Sandbox::EmploymentUpdateParams::Department, nil] :department The department object.
+        #
+        #   @option params [FinchAPI::Models::Sandbox::EmploymentUpdateParams::Employment, nil] :employment The employment object.
+        #
+        #   @option params [Symbol, FinchAPI::Models::Sandbox::EmploymentUpdateParams::EmploymentStatus, nil] :employment_status The detailed employment status of the individual.
+        #
+        #   @option params [String, nil] :end_date
+        #
+        #   @option params [String, nil] :first_name The legal first name of the individual.
+        #
+        #   @option params [FinchAPI::Models::Income, nil] :income The employee's income as reported by the provider. This may not always be
+        #     annualized income, but may be in units of bi-weekly, semi-monthly, daily, etc,
+        #     depending on what information the provider returns.
+        #
+        #   @option params [Array<FinchAPI::Models::Income, nil>, nil] :income_history The array of income history.
+        #
+        #   @option params [Boolean, nil] :is_active `true` if the individual an an active employee or contractor at the company.
+        #
+        #   @option params [String, nil] :last_name The legal last name of the individual.
+        #
+        #   @option params [String, nil] :latest_rehire_date
+        #
+        #   @option params [FinchAPI::Models::Location, nil] :location
+        #
+        #   @option params [FinchAPI::Models::Sandbox::EmploymentUpdateParams::Manager, nil] :manager The manager object representing the manager of the individual within the org.
+        #
+        #   @option params [String, nil] :middle_name The legal middle name of the individual.
+        #
+        #   @option params [String] :source_id The source system's unique employment identifier for this individual
+        #
+        #   @option params [String, nil] :start_date
+        #
+        #   @option params [String, nil] :title The current title of the individual.
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::Sandbox::EmploymentUpdateResponse]
+        #
+        def update(individual_id, params = {})
+          parsed, options = FinchAPI::Models::Sandbox::EmploymentUpdateParams.dump_request(params)
+          @client.request(
+            method: :put,
+            path: ["sandbox/employment/%0s", individual_id],
+            body: parsed,
+            model: FinchAPI::Models::Sandbox::EmploymentUpdateResponse,
+            options: options
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end

data/lib/finch-api/resources/sandbox/individual.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module FinchAPI
+  module Resources
+    class Sandbox
+      class Individual
+        # Update sandbox individual
+        #
+        # @param individual_id [String]
+        #
+        # @param params [FinchAPI::Models::Sandbox::IndividualUpdateParams, Hash{Symbol=>Object}] .
+        #
+        #   @option params [String, nil] :dob
+        #
+        #   @option params [Array<FinchAPI::Models::Sandbox::IndividualUpdateParams::Email>, nil] :emails
+        #
+        #   @option params [String, nil] :encrypted_ssn Social Security Number of the individual in **encrypted** format. This field is
+        #     only available with the `ssn` scope enabled and the
+        #     `options: { include: ['ssn'] }` param set in the body.
+        #
+        #   @option params [Symbol, FinchAPI::Models::Sandbox::IndividualUpdateParams::Ethnicity, nil] :ethnicity The EEOC-defined ethnicity of the individual.
+        #
+        #   @option params [String, nil] :first_name The legal first name of the individual.
+        #
+        #   @option params [Symbol, FinchAPI::Models::Sandbox::IndividualUpdateParams::Gender, nil] :gender The gender of the individual.
+        #
+        #   @option params [String, nil] :last_name The legal last name of the individual.
+        #
+        #   @option params [String, nil] :middle_name The legal middle name of the individual.
+        #
+        #   @option params [Array<FinchAPI::Models::Sandbox::IndividualUpdateParams::PhoneNumber, nil>, nil] :phone_numbers
+        #
+        #   @option params [String, nil] :preferred_name The preferred name of the individual.
+        #
+        #   @option params [FinchAPI::Models::Location, nil] :residence
+        #
+        #   @option params [String, nil] :ssn Social Security Number of the individual. This field is only available with the
+        #     `ssn` scope enabled and the `options: { include: ['ssn'] }` param set in the
+        #     body.
+        #     [Click here to learn more about enabling the SSN field](/developer-resources/Enable-SSN-Field).
+        #
+        #   @option params [FinchAPI::RequestOptions, Hash{Symbol=>Object}, nil] :request_options
+        #
+        # @return [FinchAPI::Models::Sandbox::IndividualUpdateResponse]
+        #
+        def update(individual_id, params = {})
+          parsed, options = FinchAPI::Models::Sandbox::IndividualUpdateParams.dump_request(params)
+          @client.request(
+            method: :put,
+            path: ["sandbox/individual/%0s", individual_id],
+            body: parsed,
+            model: FinchAPI::Models::Sandbox::IndividualUpdateResponse,
+            options: options
+          )
+        end
+
+        # @param client [FinchAPI::Client]
+        #
+        def initialize(client:)
+          @client = client
+        end
+      end
+    end
+  end
+end