Create Deduction

JavaScript

import Finch from '@tryfinch/finch-api';

const client = new Finch({
  accessToken: 'My Access Token',
});

const createCompanyBenefitsResponse = await client.hris.benefits.create();

console.log(createCompanyBenefitsResponse.benefit_id);

package main

import (
	"context"
	"fmt"

	"github.com/Finch-API/finch-api-go/v2"
	"github.com/Finch-API/finch-api-go/v2/option"
)

func main() {
	client := finchgo.NewClient(
		option.WithAccessToken("My Access Token"),
	)
	createCompanyBenefitsResponse, err := client.HRIS.Benefits.New(context.TODO(), finchgo.HRISBenefitNewParams{})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", createCompanyBenefitsResponse.BenefitID)
}

package com.tryfinch.api.example;

import com.tryfinch.api.client.FinchClient;
import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
import com.tryfinch.api.models.CreateCompanyBenefitsResponse;
import com.tryfinch.api.models.HrisBenefitCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        FinchClient client = FinchOkHttpClient.builder()
            .fromEnv()
            .accessToken("My Access Token")
            .build();

        CreateCompanyBenefitsResponse createCompanyBenefitsResponse = client.hris().benefits().create();
    }
}

package com.tryfinch.api.example

import com.tryfinch.api.client.FinchClient
import com.tryfinch.api.client.okhttp.FinchOkHttpClient
import com.tryfinch.api.models.CreateCompanyBenefitsResponse
import com.tryfinch.api.models.HrisBenefitCreateParams

fun main() {
    val client: FinchClient = FinchOkHttpClient.builder()
        .fromEnv()
        .accessToken("My Access Token")
        .build()

    val createCompanyBenefitsResponse: CreateCompanyBenefitsResponse = client.hris().benefits().create()
}

curl --request POST \
  --url https://api.tryfinch.com/employer/benefits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: <content-type>' \
  --header 'Finch-API-Version: <finch-api-version>' \
  --data '
{
  "description": "<string>",
  "company_contribution": {
    "type": "match",
    "tiers": [
      {
        "match": 5000,
        "threshold": 5000
      }
    ]
  }
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tryfinch.com/employer/benefits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'description' => '<string>',
    'company_contribution' => [
        'type' => 'match',
        'tiers' => [
                [
                                'match' => 5000,
                                'threshold' => 5000
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: <content-type>",
    "Finch-API-Version: <finch-api-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "benefit_id": "e8b90071-0c11-471c-86e8-e303ef2f6782",
  "job_id": "be1b3351-a88e-46c2-96e4-c2cf38e529a7"
}

POST

employer

benefits

JavaScript

import Finch from '@tryfinch/finch-api';

const client = new Finch({
  accessToken: 'My Access Token',
});

const createCompanyBenefitsResponse = await client.hris.benefits.create();

console.log(createCompanyBenefitsResponse.benefit_id);

package main

import (
	"context"
	"fmt"

	"github.com/Finch-API/finch-api-go/v2"
	"github.com/Finch-API/finch-api-go/v2/option"
)

func main() {
	client := finchgo.NewClient(
		option.WithAccessToken("My Access Token"),
	)
	createCompanyBenefitsResponse, err := client.HRIS.Benefits.New(context.TODO(), finchgo.HRISBenefitNewParams{})
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", createCompanyBenefitsResponse.BenefitID)
}

package com.tryfinch.api.example;

import com.tryfinch.api.client.FinchClient;
import com.tryfinch.api.client.okhttp.FinchOkHttpClient;
import com.tryfinch.api.models.CreateCompanyBenefitsResponse;
import com.tryfinch.api.models.HrisBenefitCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        FinchClient client = FinchOkHttpClient.builder()
            .fromEnv()
            .accessToken("My Access Token")
            .build();

        CreateCompanyBenefitsResponse createCompanyBenefitsResponse = client.hris().benefits().create();
    }
}

package com.tryfinch.api.example

import com.tryfinch.api.client.FinchClient
import com.tryfinch.api.client.okhttp.FinchOkHttpClient
import com.tryfinch.api.models.CreateCompanyBenefitsResponse
import com.tryfinch.api.models.HrisBenefitCreateParams

fun main() {
    val client: FinchClient = FinchOkHttpClient.builder()
        .fromEnv()
        .accessToken("My Access Token")
        .build()

    val createCompanyBenefitsResponse: CreateCompanyBenefitsResponse = client.hris().benefits().create()
}

curl --request POST \
  --url https://api.tryfinch.com/employer/benefits \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: <content-type>' \
  --header 'Finch-API-Version: <finch-api-version>' \
  --data '
{
  "description": "<string>",
  "company_contribution": {
    "type": "match",
    "tiers": [
      {
        "match": 5000,
        "threshold": 5000
      }
    ]
  }
}
'

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.tryfinch.com/employer/benefits",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'description' => '<string>',
    'company_contribution' => [
        'type' => 'match',
        'tiers' => [
                [
                                'match' => 5000,
                                'threshold' => 5000
                ]
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: <content-type>",
    "Finch-API-Version: <finch-api-version>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

{
  "benefit_id": "e8b90071-0c11-471c-86e8-e303ef2f6782",
  "job_id": "be1b3351-a88e-46c2-96e4-c2cf38e529a7"
}

Availability: Automated and Assisted providers Employer Match capabilities are currently in Beta. Please reach out if you are interested in gaining early access. If the same request is made more than once with the same type, frequency and description, a new item will not be created. Finch will instead return the benefit_id of the existing item. Latencies may vary depending on whether the provider is Automated or Assisted - new items will be created within minutes for Automated providers and within the 2 business day SLA for Assisted providers.

Authorizations

Authorization

string

header

required

Please use your Access Token

Headers

Finch-API-Version

string<date>

default:2020-09-17

required

Header used to specify the version for a given API request. Current version is 2020-09-17.

Content-Type

string

default:application/json

required

Used to indicate the original media type of the resource

Query Parameters

entity_ids

string<uuid>[]

The entity IDs to specify which entities' data to access. Provide exactly one entity ID per request; a maximum of one is accepted. Required when the connection has more than one entity — omitting it returns a 400 invalid_request_error. Optional for single-entity connections.

Required array length: 1 element

Example:

["550e8400-e29b-41d4-a716-446655440000"]

Body

application/json

type

enum<string> | null

Type of benefit.

Available options:

457,

401k,

401k_roth,

401k_loan,

403b,

403b_roth,

457_roth,

commuter,

custom_post_tax,

custom_pre_tax,

fsa_dependent_care,

fsa_medical,

hsa_post,

hsa_pre,

s125_dental,

s125_medical,

s125_vision,

simple,

simple_ira,

null

description

string

Name of the benefit as it appears in the provider and pay statements. Recommend limiting this to <30 characters due to limitations in specific providers (e.g. Justworks).

frequency

enum<string> | null

The frequency of the benefit deduction/contribution.

Available options:

every_paycheck,

monthly,

one_time,

null

company_contribution

BenefitCompanyMatchContribution · object | null

The company match for this benefit.

Show child attributes

Response

Successfully Created

benefit_id

string<uuid>

required

The id of the benefit.

job_id

string<uuid>

required

Organization

Payroll

Deductions

Benefits

Documents

Connect

Management

Sandbox

Development Guides

Create Deduction

Authorizations

Headers

Query Parameters

Body

Response