Employee Create

Onboard workers with the Employee Create method

This guide walks you through the steps for onboarding a worker using the Branch Employee Create functionality.

For an outline of the roadmap and timing, see Get Started and the diagram below on this page.


Simulate Webhooks

You can use the Branch sandbox environment to manually trigger and test webhooks as you integrate them with your system. For details see Webhook Sandbox Testing.

Employee Create API

When a worker selects Branch as their Payment Method, your organization calls the Create Employee endpoint to create a roster record in Branch. After the roster record is created, your org surfaces a Branch deep link for workers to KYC and complete setup via the Branch app. Your org will listen for the Account Verified as Worker and Wallet Activated webhooks to determine when Branch setup is complete. Sequence of events outlined below:

employee create flow

All screens are subject to Branch review. View or download a PDF of onboarding screen examples with Branch-approved copy here.


Create Disbursement

When a job is confirmed and ready for payment, your organization calls the Create Disbursement endpoint to post earnings to the worker’s Branch Wallet. See the Disbursement Create section for more information.

API Endpoints

For complete details about each endpoint see the Branch API reference section.

Note the following when making API calls:

  • All API calls expect values to be trimmed with no prepended or trailing whitespace, unless noted otherwise.
  • All creation requests for wallets and disbursements are idempotent and support handling duplicate request attempts.

Note the proper handling of HTTP response codes:

  • 200/2XX OK The request was received and was processed by Branch.
  • 500/5XX 5xx The system experience an issue and did not complete the processing of the request.
  • If a call receives an error response code or encounters a timeout, the caller should retry the request until a 200 OK response is received.

Disbursement FAILED Reason Codes

Reason Code Description
worker_not_found A worker with the provided id does not exist in our system
worker_not_matched A user is not associated with the provided id, though the ID is on the roster. (User hasn’t signed up basically)
wallet_not_found The user associated with the provided ID does not have a wallet.
wallet_suspended The user associated with the provided ID’s wallet is suspended and not payable
amount_too_large The amount you are attempting to pay exceeds the single payout limits (by default $10k)
card_expired The card associated with this disbursement and employeeId is expired
card_invalid The card associated with this disbursement and employeeId is no longer valid
retry_period_elapsed The disbursement failed too long ago for it to be retried
unexpected_error The exact reason for failure cannot be determined automatically