docs: add params class javadocs (#316)

Finch-API · Jan 7, 2025 · 2b4bc9e · 2b4bc9e
1 parent e804c4c
commit 2b4bc9e
Show file tree

Hide file tree

Showing 41 changed files with 79 additions and 0 deletions.
diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/AccessTokenCreateParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/AccessTokenCreateParams.kt
@@ -15,6 +15,7 @@ import com.tryfinch.api.core.immutableEmptyMap
 import com.tryfinch.api.core.toImmutable
 import java.util.Objects
 
+/** Exchange the authorization code for an access token */
 class AccessTokenCreateParams
 constructor(
     private val body: AccessTokenCreateBody,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/AccountDisconnectParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/AccountDisconnectParams.kt
@@ -9,6 +9,7 @@ import com.tryfinch.api.core.http.QueryParams
 import com.tryfinch.api.core.toImmutable
 import java.util.Objects
 
+/** Disconnect one or more `access_token`s from your application. */
 class AccountDisconnectParams
 constructor(
     private val additionalHeaders: Headers,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/AccountIntrospectParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/AccountIntrospectParams.kt
@@ -7,6 +7,7 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/** Read account information associated with an `access_token` */
 class AccountIntrospectParams
 constructor(
     private val additionalHeaders: Headers,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/ConnectSessionNewParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/ConnectSessionNewParams.kt
@@ -18,6 +18,7 @@ import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Objects
 
+/** Create a new connect session for an employer */
 class ConnectSessionNewParams
 constructor(
     private val body: ConnectSessionNewBody,

diff --git a/...kotlin-core/src/main/kotlin/com/tryfinch/api/models/ConnectSessionReauthenticateParams.kt b/...kotlin-core/src/main/kotlin/com/tryfinch/api/models/ConnectSessionReauthenticateParams.kt
@@ -18,6 +18,7 @@ import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Objects
 
+/** Create a new Connect session for reauthenticating an existing connection */
 class ConnectSessionReauthenticateParams
 constructor(
     private val body: ConnectSessionReauthenticateBody,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitCreateParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitCreateParams.kt
@@ -15,6 +15,10 @@ import com.tryfinch.api.core.immutableEmptyMap
 import com.tryfinch.api.core.toImmutable
 import java.util.Objects
 
+/**
+ * Creates a new company-wide deduction or contribution. Please use the `/providers` endpoint to
+ * view available types for each provider.
+ */
 class HrisBenefitCreateParams
 constructor(
     private val body: HrisBenefitCreateBody,

diff --git a/...in-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitIndividualEnrolledIdsParams.kt b/...in-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitIndividualEnrolledIdsParams.kt
@@ -7,6 +7,7 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/** Lists individuals currently enrolled in a given deduction. */
 class HrisBenefitIndividualEnrolledIdsParams
 constructor(
     private val benefitId: String,

diff --git a/...rc/main/kotlin/com/tryfinch/api/models/HrisBenefitIndividualRetrieveManyBenefitsParams.kt b/...rc/main/kotlin/com/tryfinch/api/models/HrisBenefitIndividualRetrieveManyBenefitsParams.kt
@@ -7,6 +7,7 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/** Get enrollment information for the given individuals. */
 class HrisBenefitIndividualRetrieveManyBenefitsParams
 constructor(
     private val benefitId: String,

diff --git a/...n-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitIndividualUnenrollManyParams.kt b/...n-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitIndividualUnenrollManyParams.kt
@@ -15,6 +15,7 @@ import com.tryfinch.api.core.immutableEmptyMap
 import com.tryfinch.api.core.toImmutable
 import java.util.Objects
 
+/** Unenroll individuals from a deduction or contribution */
 class HrisBenefitIndividualUnenrollManyParams
 constructor(
     private val benefitId: String,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitListParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitListParams.kt
@@ -7,6 +7,7 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/** List all company-wide deductions and contributions. */
 class HrisBenefitListParams
 constructor(
     private val additionalHeaders: Headers,

diff --git a/...in-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitListSupportedBenefitsParams.kt b/...in-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitListSupportedBenefitsParams.kt
@@ -7,6 +7,7 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/** Get deductions metadata */
 class HrisBenefitListSupportedBenefitsParams
 constructor(
     private val additionalHeaders: Headers,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitRetrieveParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitRetrieveParams.kt
@@ -7,6 +7,7 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/** Lists deductions and contributions information for a given item */
 class HrisBenefitRetrieveParams
 constructor(
     private val benefitId: String,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitUpdateParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisBenefitUpdateParams.kt
@@ -15,6 +15,7 @@ import com.tryfinch.api.core.immutableEmptyMap
 import com.tryfinch.api.core.toImmutable
 import java.util.Objects
 
+/** Updates an existing company-wide deduction or contribution */
 class HrisBenefitUpdateParams
 constructor(
     private val benefitId: String,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisCompanyRetrieveParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisCompanyRetrieveParams.kt
@@ -7,6 +7,7 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/** Read basic company data */
 class HrisCompanyRetrieveParams
 constructor(
     private val additionalHeaders: Headers,

diff --git a/...kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisDirectoryListIndividualsParams.kt b/...kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisDirectoryListIndividualsParams.kt
@@ -7,6 +7,7 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/** Read company directory and organization structure */
 class HrisDirectoryListIndividualsParams
 constructor(
     private val limit: Long?,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisDirectoryListParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisDirectoryListParams.kt
@@ -7,6 +7,7 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/** Read company directory and organization structure */
 class HrisDirectoryListParams
 constructor(
     private val limit: Long?,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisDocumentListParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisDocumentListParams.kt
@@ -12,6 +12,7 @@ import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Objects
 
+/** **Beta:** This endpoint is in beta and may change. Retrieve a list of company-wide documents. */
 class HrisDocumentListParams
 constructor(
     private val individualIds: List<String>?,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisDocumentRetreiveParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisDocumentRetreiveParams.kt
@@ -7,6 +7,10 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/**
+ * **Beta:** This endpoint is in beta and may change. Retrieve details of a specific document by its
+ * ID.
+ */
 class HrisDocumentRetreiveParams
 constructor(
     private val documentId: String,

diff --git a/...h-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisEmploymentRetrieveManyParams.kt b/...h-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisEmploymentRetrieveManyParams.kt
@@ -15,6 +15,7 @@ import com.tryfinch.api.core.immutableEmptyMap
 import com.tryfinch.api.core.toImmutable
 import java.util.Objects
 
+/** Read individual employment and income data */
 class HrisEmploymentRetrieveManyParams
 constructor(
     private val body: HrisEmploymentRetrieveManyBody,

diff --git a/...h-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisIndividualRetrieveManyParams.kt b/...h-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisIndividualRetrieveManyParams.kt
@@ -15,6 +15,7 @@ import com.tryfinch.api.core.immutableEmptyMap
 import com.tryfinch.api.core.toImmutable
 import java.util.Objects
 
+/** Read individual data, excluding income and employment data */
 class HrisIndividualRetrieveManyParams
 constructor(
     private val body: HrisIndividualRetrieveManyBody,

diff --git a/...kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisPayStatementRetrieveManyParams.kt b/...kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisPayStatementRetrieveManyParams.kt
@@ -15,6 +15,11 @@ import com.tryfinch.api.core.immutableEmptyMap
 import com.tryfinch.api.core.toImmutable
 import java.util.Objects
 
+/**
+ * Read detailed pay statements for each individual.
+ *
+ * Deduction and contribution types are supported by the payroll systems that supports Benefits.
+ */
 class HrisPayStatementRetrieveManyParams
 constructor(
     private val body: HrisPayStatementRetrieveManyBody,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisPaymentListParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/HrisPaymentListParams.kt
@@ -8,6 +8,7 @@ import com.tryfinch.api.core.http.QueryParams
 import java.time.LocalDate
 import java.util.Objects
 
+/** Read payroll and contractor related payments by the company. */
 class HrisPaymentListParams
 constructor(
     private val endDate: LocalDate,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/JobAutomatedCreateParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/JobAutomatedCreateParams.kt
@@ -28,6 +28,21 @@ import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Objects
 
+/**
+ * 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.
+ */
 class JobAutomatedCreateParams
 constructor(
     private val body: JobAutomatedCreateBody,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/JobAutomatedListParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/JobAutomatedListParams.kt
@@ -7,6 +7,11 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/**
+ * 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.
+ */
 class JobAutomatedListParams
 constructor(
     private val limit: Long?,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/JobAutomatedRetrieveParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/JobAutomatedRetrieveParams.kt
@@ -7,6 +7,7 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/** Get an automated job by `job_id`. */
 class JobAutomatedRetrieveParams
 constructor(
     private val jobId: String,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/JobManualRetrieveParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/JobManualRetrieveParams.kt
@@ -7,6 +7,10 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/**
+ * Get a manual job by `job_id`. Manual jobs are completed by a human and include Assisted Benefits
+ * jobs.
+ */
 class JobManualRetrieveParams
 constructor(
     private val jobId: String,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/PayrollPayGroupListParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/PayrollPayGroupListParams.kt
@@ -8,6 +8,7 @@ import com.tryfinch.api.core.http.QueryParams
 import com.tryfinch.api.core.toImmutable
 import java.util.Objects
 
+/** Read company pay groups and frequencies */
 class PayrollPayGroupListParams
 constructor(
     private val individualId: String?,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/PayrollPayGroupRetrieveParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/PayrollPayGroupRetrieveParams.kt
@@ -7,6 +7,7 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/** Read information from a single pay group */
 class PayrollPayGroupRetrieveParams
 constructor(
     private val payGroupId: String,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/ProviderListParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/ProviderListParams.kt
@@ -7,6 +7,7 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/** Return details on all available payroll and HR systems. */
 class ProviderListParams
 constructor(
     private val additionalHeaders: Headers,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/RequestForwardingForwardParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/RequestForwardingForwardParams.kt
@@ -15,6 +15,11 @@ import com.tryfinch.api.core.immutableEmptyMap
 import com.tryfinch.api.core.toImmutable
 import java.util.Objects
 
+/**
+ * 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.
+ */
 class RequestForwardingForwardParams
 constructor(
     private val body: RequestForwardingForwardBody,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxCompanyUpdateParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxCompanyUpdateParams.kt
@@ -18,6 +18,7 @@ import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Objects
 
+/** Update a sandbox company's data */
 class SandboxCompanyUpdateParams
 constructor(
     private val body: SandboxCompanyUpdateBody,

diff --git a/...tlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxConnectionAccountCreateParams.kt b/...tlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxConnectionAccountCreateParams.kt
@@ -18,6 +18,7 @@ import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Objects
 
+/** Create a new account for an existing connection (company/provider pair) */
 class SandboxConnectionAccountCreateParams
 constructor(
     private val body: SandboxConnectionAccountCreateBody,

diff --git a/...tlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxConnectionAccountUpdateParams.kt b/...tlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxConnectionAccountUpdateParams.kt
@@ -15,6 +15,10 @@ import com.tryfinch.api.core.immutableEmptyMap
 import com.tryfinch.api.core.toImmutable
 import java.util.Objects
 
+/**
+ * Update an existing sandbox account. Change the connection status to understand how the Finch API
+ * responds.
+ */
 class SandboxConnectionAccountUpdateParams
 constructor(
     private val body: SandboxConnectionAccountUpdateBody,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxConnectionCreateParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxConnectionCreateParams.kt
@@ -18,6 +18,7 @@ import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Objects
 
+/** Create a new connection (new company/provider pair) with a new account */
 class SandboxConnectionCreateParams
 constructor(
     private val body: SandboxConnectionCreateBody,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxDirectoryCreateParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxDirectoryCreateParams.kt
@@ -18,6 +18,7 @@ import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Objects
 
+/** Add new individuals to a sandbox company */
 class SandboxDirectoryCreateParams
 constructor(
     private val body: List<IndividualOrEmployment>,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxEmploymentUpdateParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxEmploymentUpdateParams.kt
@@ -18,6 +18,7 @@ import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Objects
 
+/** Update sandbox employment */
 class SandboxEmploymentUpdateParams
 constructor(
     private val individualId: String,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxIndividualUpdateParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxIndividualUpdateParams.kt
@@ -18,6 +18,7 @@ import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Objects
 
+/** Update sandbox individual */
 class SandboxIndividualUpdateParams
 constructor(
     private val individualId: String,

diff --git a/...lin-core/src/main/kotlin/com/tryfinch/api/models/SandboxJobConfigurationRetrieveParams.kt b/...lin-core/src/main/kotlin/com/tryfinch/api/models/SandboxJobConfigurationRetrieveParams.kt
@@ -7,6 +7,7 @@ import com.tryfinch.api.core.http.Headers
 import com.tryfinch.api.core.http.QueryParams
 import java.util.Objects
 
+/** Get configurations for sandbox jobs */
 class SandboxJobConfigurationRetrieveParams
 constructor(
     private val additionalHeaders: Headers,

diff --git a/...otlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxJobConfigurationUpdateParams.kt b/...otlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxJobConfigurationUpdateParams.kt
@@ -18,6 +18,7 @@ import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Objects
 
+/** Update configurations for sandbox jobs */
 class SandboxJobConfigurationUpdateParams
 constructor(
     private val body: SandboxJobConfigurationUpdateBody,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxJobCreateParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxJobCreateParams.kt
@@ -18,6 +18,7 @@ import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Objects
 
+/** Enqueue a new sandbox job */
 class SandboxJobCreateParams
 constructor(
     private val body: SandboxJobCreateBody,

diff --git a/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxPaymentCreateParams.kt b/finch-kotlin-core/src/main/kotlin/com/tryfinch/api/models/SandboxPaymentCreateParams.kt
@@ -18,6 +18,7 @@ import com.tryfinch.api.core.toImmutable
 import com.tryfinch.api.errors.FinchInvalidDataException
 import java.util.Objects
 
+/** Add a new sandbox payment */
 class SandboxPaymentCreateParams
 constructor(
     private val body: SandboxPaymentCreateBody,