Skip to main content
API docs by Redocly

Branch API (1.0.3)

Download OpenAPI specification:Download

Branch API

Wallet

Create Wallet

Creates a digital wallet for an employee. Optionally allows a Branch card to be automatically ordered for the employee.

path Parameters
orgId
required
integer <int32>

The Organization ID

employeeId
required
string

The Employee ID

header Parameters
apikey
required
string
testmode
boolean
Request Body schema: application/json
first_name
required
string

Numbers not allowed

middle_name
string

Numbers not allowed

last_name
required
string

Numbers not allowed

required
object (Address)
date_of_birth
required
string[0-9]{4}-[0-9]{2}-[0-9]{2}
ssn
required
string[0-9]{9}
phone_number
required
string
email_address
required
string
type
string
Enum: "HOURLY" "SALARY"
pay_rate
integer <int32> >= 0

Rate of pay, in cents, used in conjunction with type. The following should be defined as follows: If type = salary, then should be the annual salary of the employee If type = hourly, then should be the hourly rate the employee earns

group_name
string
create_employee
boolean
Default: false

If true and the employee does not already exist, will create the employee with the given information.

order_card
boolean
Default: false

If true, a physical card will be shipped to the user when the account is created.

card_program
string

Specifies which card should be ordered and delivered to the user. Available options for an organization can be found by querying the card-controller -> getCardPrograms endpoint.Default is organization's default card program - generally BRANCH_W2

ein
string

9 digit employer identification number

Responses

Request samples

Content type
application/json
{
  • "first_name": "John",
  • "middle_name": "William",
  • "last_name": "Larson",
  • "address": {
    },
  • "date_of_birth": "2000-01-01",
  • "ssn": "123456789",
  • "phone_number": "+11235550123",
  • "email_address": "worker@branchapp.com",
  • "type": "HOURLY",
  • "pay_rate": 1500,
  • "group_name": "GOLD",
  • "create_employee": false,
  • "order_card": false,
  • "card_program": "BRANCH_W2",
  • "ein": "XXXXXXXXX"
}

getWallets

path Parameters
orgId
required
integer <int32>
query Parameters
required
object (PageRequest)
header Parameters
apikey
required
string

Responses

getWalletStatuses

path Parameters
orgId
required
integer <int32>
query Parameters
required
object (PageRequest)
header Parameters
apikey
required
string

Responses

getWallet

path Parameters
orgId
required
integer <int32>
employeeId
required
string
header Parameters
apikey
required
string

Responses

Disbursements

getDisbursementsForEmployee

path Parameters
orgId
required
integer <int32>
employeeId
required
string
query Parameters
required
object (DisbursementSearchCriteria)
required
object (PageRequest)
sort
required
string

Format: field_name,direction

header Parameters
apikey
required
string

Responses

Create Disbursement

Creates a disbursement for an employee. A disbursement is an initiation of payment to a worker.

path Parameters
orgId
required
integer <int32>
employeeId
required
string
header Parameters
apikey
required
string
Request Body schema: application/json
amount
required
integer <int32>

Amount, in cents, to be disbursed to the employee.

external_id
required
string [ 0 .. 64 ] characters

Allows the custom specification of a unique ID that correlates back to your own records.

type
required
string
Enum: "TIPS" "TRIP" "MILEAGE" "PAYCHECK" "MISCELLANEOUS" "DEVICE" "DELIVERY" "DEPOSIT" "BONUS" "REWARD" "UNKNOWN"

TIPS: Disbursement for tips earned by worker
TRIP: Disbursement for trip made by worker
MILEAGE: Disbursement for miles driven by worker
PAYCHECK: Disbursement for income earned by worker
MISCELLANEOUS: Disbursement to worker for miscellaneous reasons
DEVICE: Disbursement for a worker’s device
DELIVERY: Disbursement for delivery made by worker
DEPOSIT: Disbursement for generic purposes
REWARD: Disbursement for a rewared earned
BONUS: Disbursement representing a non-usual payment

employee_group
string [ 0 .. 150 ] characters

A grouping for the employee. This could be anything that is used by your organization in order to group employees: store id, employee tier, region code, etc.

display_sub_label
string [ 0 .. 150 ] characters

A description of the disbursement. This will be displayed to the worker in the application

description
required
string [ 0 .. 256 ] characters
retry
boolean

Default false. If status goes into FAILED, allows disbursement to be reattempted.

object
time_scheduled
string <date-time>

Date and time at which the specified amount will be disbursed to the employee.

Responses

Request samples

Content type
application/json
{
  • "amount": 500,
  • "external_id": "123456",
  • "type": "MILEAGE",
  • "employee_group": "Store #1",
  • "display_sub_label": "Tip for delivery",
  • "description": "Disbursement for miles driven.",
  • "retry": true,
  • "metadata": {
    },
  • "time_scheduled": "2019-08-24T14:15:22Z"
}

getDisbursementsForInvoice

path Parameters
orgId
required
integer <int32>
invoiceId
required
integer <int32>
query Parameters
required
object (DisbursementSearchCriteria)
required
object (PageRequest)
sort
required
string

Format: field_name,direction

header Parameters
apikey
required
string

Responses

Search Disbursements

Searches disbursements while returning HATEOAS links (e.g. prev_page, next_page) for retrieving additional data.

path Parameters
orgId
required
integer <int32>
query Parameters
required
object (DisbursementSearchCriteria)
required
object (PageRequest)
sort
required
string

Format: field_name,direction

header Parameters
apikey
required
string

Responses

Employees

getEmployee

path Parameters
orgId
required
integer <int32>
employeeId
required
string
header Parameters
apikey
required
string

Responses

updateEmployee

path Parameters
orgId
required
integer <int32>
employeeId
required
string
header Parameters
apikey
required
string
Request Body schema: application/json
first_name
required
string

Numbers not allowed

last_name
required
string

Numbers not allowed

phone_number
string
email_address
string
type
string
Enum: "HOURLY" "SALARY"
pay_rate
integer <int32> >= 0

Rate of pay, in cents, used in conjunction with type. The following should be defined as follows: If type = salary, then should be the annual salary of the employee If type = hourly, then should be the hourly rate the employee earns

business_name
string
group_name
string
ein
string
password
string

Responses

Request samples

Content type
application/json
{
  • "first_name": "John",
  • "last_name": "Larson",
  • "phone_number": "+11235550123",
  • "email_address": "worker@branchapp.com",
  • "type": "HOURLY",
  • "pay_rate": 0,
  • "business_name": "Dunder Mifflin Paper Company",
  • "group_name": "GOLD",
  • "ein": "XXXXXXXXX",
  • "password": "string"
}

createEmployee

path Parameters
orgId
required
integer <int32>
employeeId
required
string
header Parameters
apikey
required
string
Request Body schema: application/json
first_name
required
string

Numbers not allowed

last_name
required
string

Numbers not allowed

phone_number
string
email_address
string
type
string
Enum: "HOURLY" "SALARY"
pay_rate
integer <int32> >= 0

Rate of pay, in cents, used in conjunction with type. The following should be defined as follows: If type = salary, then should be the annual salary of the employee If type = hourly, then should be the hourly rate the employee earns

business_name
string
group_name
string
ein
string
password
string

Responses

Request samples

Content type
application/json
{
  • "first_name": "John",
  • "last_name": "Larson",
  • "phone_number": "+11235550123",
  • "email_address": "worker@branchapp.com",
  • "type": "HOURLY",
  • "pay_rate": 0,
  • "business_name": "Dunder Mifflin Paper Company",
  • "group_name": "GOLD",
  • "ein": "XXXXXXXXX",
  • "password": "string"
}

deleteEmployee

path Parameters
orgId
required
integer <int32>
employeeId
required
string
header Parameters
apikey
required
string

Responses

searchEmployees

path Parameters
orgId
required
integer <int32>
query Parameters
required
object (EmployeeSearchCriteria)
required
object (PageRequest)
header Parameters
apikey
required
string

Responses

Payroll Periods

Get an existing payroll period

Get an existing payroll period.

path Parameters
orgId
required
integer <int32>
payrollPeriodId
required
integer <int32>
header Parameters
apikey
required
string

Responses

Update an existing payroll period

Update an existing payroll period. A payroll period records a pay date and payroll period deadline

path Parameters
orgId
required
integer <int32>
payrollPeriodId
required
integer <int32>
header Parameters
apikey
required
string
Request Body schema: application/json
payroll_deadline
string <date>

The date by which workers' pay must be determined.

pay_date
string <date>

The date individuals will receive payment.

Responses

Request samples

Content type
application/json
{
  • "payroll_deadline": "2000-01-01",
  • "pay_date": "2000-01-01"
}

Payroll Calendar

Get the payroll calendar

Get the payroll calendar for an organization

path Parameters
orgId
required
integer <int32>
header Parameters
apikey
required
string

Responses

Create a new payroll calendar

Create a new payroll calendar. A payroll calendar is a list of payroll periods

path Parameters
orgId
required
integer <int32>
header Parameters
apikey
required
string
Request Body schema: application/json
Array of objects (PayrollPeriodCreationRequest)

The list of payroll periods creation requests for the calendar.

Array
payroll_deadline
string <date>

The date by which workers' pay must be determined.

pay_date
string <date>

The date individuals will receive payment.

Responses

Request samples

Content type
application/json
{
  • "payroll_periods": [
    ]
}

Shifts

Get worker's shift.

Get a person's completed shift. Requires shift_id to identify which shift to retrieve.If an existing shift cannot be found with the provided shift_id, call will return 404 - Not Found.Successful call will return the completed shift.

path Parameters
orgId
required
integer <int32>
employeeId
required
string
shiftId
required
string
header Parameters
apikey
required
string

Responses

Updates worker's shift.

Updates a person's completed shift. Requires shift_id to identify which shift to update.If an existing shift cannot be found with the provided shift_id, call will return 404 - Not Found.Requests made with missing required fields or invalid dates/times will return 400 - Bad Request.Successful call will return newly updated shift.

path Parameters
orgId
required
integer <int32>
employeeId
required
string
shiftId
required
string
header Parameters
apikey
required
string
Request Body schema: application/json
punch_in
string <date-time>

Time the shift started

punch_out
string <date-time>

Time the shift ended. This does not need to be provided if 'hours' is provided

hours
number <double>

Number of hours worked in the shift. This does not need to be provided if 'punch_out' is provided

rate
integer <int32>

Amount of money, in cents, the employee made per hour/day depending on 'shift_type'

shift_type
string
Enum: "Daily" "Hourly"

Shift type, 'HOURLY' or 'DAILY'

Responses

Request samples

Content type
application/json
{
  • "punch_in": "2019-08-24T14:15:22Z",
  • "punch_out": "2019-08-24T14:15:22Z",
  • "hours": 0,
  • "rate": 0,
  • "shift_type": "Daily"
}

Delete shift.

Delete an existing shift. Requires shift_id to identify which shift to delete.If an existing shift cannot be found with the provided shift_id, call will return 404 - Not Found.Successful call will return status 204 - No Content.

path Parameters
orgId
required
integer <int32>
employeeId
required
string
shiftId
required
string
header Parameters
apikey
required
string

Responses

Submit worker's shift.

Submits a person's completed shift. Shifts are used to track hours worked by an individual employee and calculate EWA.Shifts may be created with a shift_id unique within the organization. Failure to provide a shift_id will cause a UUID to be generated instead.If a duplicate shift_id is provided, call will return 409 - Conflict.Successful call will return the created shift and status 201.

path Parameters
orgId
required
integer <int32>
employeeId
required
string
header Parameters
apikey
required
string
Request Body schema: application/json
id
string

If blank, defaults to UUID

punch_in
string <date-time>

Time the shift started

punch_out
string <date-time>

Time the shift ended. This does not need to be provided if 'hours' is provided

hours
number <double> >= 0

Number of hours worked in the shift. This value cannot be negative. This does not need to be provided if 'punch_out' is provided

rate
integer <int32>

Amount of money, in cents, the employee made per hour/day depending on 'shift_type'

shift_type
required
string
Enum: "Daily" "Hourly"

Shift type, 'HOURLY' or 'DAILY'

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "punch_in": "2019-08-24T14:15:22Z",
  • "punch_out": "2019-08-24T14:15:22Z",
  • "hours": 0,
  • "rate": 0,
  • "shift_type": "Daily"
}

Employee Earnings

updateEmployeePeriodEarning

path Parameters
orgId
required
integer <int32>
employeeId
required
string
header Parameters
apikey
required
string
Request Body schema: application/json
amount
integer <int32> >= 1

earnings in cents. must be greater than 0

date
string <date> yyyy-MM-dd

Responses

Request samples

Content type
application/json
{
  • "amount": 1,
  • "date": "2021-06-24"
}

Remittance

reportOrganizationRemittanceDeduction

path Parameters
orgId
required
integer <int32>
remittanceId
required
integer <int32>
header Parameters
apikey
required
string
Request Body schema: application/json
employee_id
required
string
amount
integer <int32> >= 0

Amount, in cents, that was successfully deducted for the employee

Responses

Request samples

Content type
application/json
{
  • "employee_id": "string",
  • "amount": 0
}

updateOrganizationRemittance

path Parameters
orgId
required
integer <int32>
remittanceId
required
integer <int32>
header Parameters
apikey
required
string
Request Body schema: application/json
status
required
stringCOMPLETED

Responses

Request samples

Content type
application/json
{
  • "status": "string"
}

getOrganizationRemittances

path Parameters
orgId
required
integer <int32>
query Parameters
required
object (PageRequest)
header Parameters
apikey
required
string

Responses

getOrganizationRemittanceRequestedDeductions

path Parameters
orgId
required
integer <int32>
remittanceId
required
integer <int32>
query Parameters
required
object (PageRequest)
header Parameters
apikey
required
string

Responses

Advances

searchOrganizationAdvances

path Parameters
orgId
required
integer <int32>
query Parameters
required
object (EmployeeAdvanceSearchCriteria)
required
object (PageRequest)
header Parameters
apikey
required
string

Responses