Field	Type		Notes
name	string	required	1–200 characters
emailDomain	string	required	Company domain, e.g. acmecorp.com
isEmailDomainEnforced	boolean	required	When true, employees must use a work email on this domain. When false, other domains are allowed but those links need company-admin approval.
admin.firstName	string	required	1–100 characters
admin.lastName	string	required	1–100 characters
admin.email	string	required	Must be unique across the platform
admin.phoneNumber	string	optional	International format — e.g. +233201234567. Must be unique if provided.
admin.position	string	optional	Admin's job title. Defaults to HR.

Common errors

Status	Message	Fix
409	An account with this email already exists	Use a different admin email
409	An account with this phone number already exists	Use a different phone number or omit it

All fields are optional — send only what you want to set or update. Top-level name, emailDomain, and isEmailDomainEnforced can also be updated alongside profile.

Profile fields

Field	Type	Notes
industrySector	string	AGRICULTURE CONSTRUCTION EDUCATION ENERGY FINANCE HEALTHCARE HOSPITALITY MANUFACTURING MEDIA MINING RETAIL TECHNOLOGY TELECOMMUNICATIONS TRANSPORTATION OTHER
employeeCountRange	string	ONE_TO_FIVE SIX_TO_TWENTY TWENTY_ONE_TO_FIFTY FIFTY_ONE_TO_TWO_HUNDRED TWO_HUNDRED_PLUS
hasPhysicalOffice	boolean	Whether the company operates from a physical office
payrollSystem	string	Name of the payroll software in use, e.g. Sage
incorporationCountry	string	Country of incorporation
website / linkedIn / facebook	string (URL)	Online presence links, max 500 characters each
logoUrl / incorporationCertUrl	string (URL)	Links to the company logo and certificate of incorporation
workingDayStartDay / workingDayEndDay	integer 1–31	Start and end day of the pay cycle. Used to calculate earned wages for EWA.
cutoffDay	integer 1–31	Last day of the month employees can request EWA
repaymentDay	integer 1–31	Day of the month advances are repaid from salary
maxSalaryExposurePercentage	integer 0–100	Maximum share of salary that rent and other benefit repayments plus EWA can take together in a pay period
contactAdminId	integer	Must be the id of an admin of this company, otherwise 400

Status	What it means	What to do
PENDING	Awaiting review by Work Benefit	Make sure the profile is complete (Step 3). You can continue with Steps 5 and 6 while you wait.
ACCEPTED	Company is live and approved	Employees can now request EWA.
REJECTED	Application was declined	Contact Work Benefit support for the reason and next steps.

1 · List available benefits

2 · Enroll a benefit

Status	Message	Fix
404	Benefit not found	Use an id from GET /benefits
404	Company not found	Use a company created with your developer account
409	Resource already exists	The benefit is already enrolled. Update it instead.

3 · Update or deactivate a benefit

:id is the company benefit id. Send at least one of status (ACTIVE or INACTIVE) and paymentOption (PAYROLL_DEDUCTION or EMPLOYEE_SELF_PAYMENT). Some benefits have a fixed payment option and return 400 if you try to change it. Setting a WAITLISTED benefit to INACTIVE removes the enrollment. Suspended benefits can only be managed by Work Benefit (403). To see current enrollments, call GET /api/public/v1/companies/:companyId/benefits (BENEFIT_READ).

All fields are optional — send only what you want to change. By default, all rules are disabled and every EWA request requires manual approval.

Example A — Auto-approve all requests

Example B — Auto-approve up to 50% of accrued earnings

Example C — Auto-approve weekdays 8 am – 5 pm only

Example D — Limit the number of requests per month

The monthly request limit itself is set per employee (see Per-employee settings below).

All settings fields

Field	Type	Description
enabledAutoApprovalForAllEmployees	boolean	Master switch. When true, requests are auto-approved subject to the rules below. When false, only employees whose own approvalMode is AUTOMATIC can be auto-approved; everyone else needs manual approval.
hasPercentageOfAccruedWage	boolean	Enable a cap on the percentage of accrued earnings that can be withdrawn
percentageOfAccruedWage	number 0–100	Used when hasPercentageOfAccruedWage is true. A request must be at or below this percentage of earned wages.
hasPermanentOrConfirmedEmployeeStatus	boolean	Only auto-approve employees whose company link is approved
hasRequestedLessThanMaxAmountPerCycle	boolean	Enable a maximum total withdrawal amount per pay cycle
maxAmountPerCycle	number	Used when hasRequestedLessThanMaxAmountPerCycle is true
hasMadeLessThanMaxRequestsPerMonth	boolean	Only auto-approve while the employee is under their maxRequestsPerMonth limit
hasPendingPaymentFromPriorCycles	boolean	Accepted and stored, but not applied to auto-approval at the moment
enabledBetweenTimePeriods	boolean	Restrict auto-approval to a specific time window
smartAutoApprovalStartTime	string HH:MM	Start of the auto-approval window, 24-hour format. Set it when enabledBetweenTimePeriods is true.
smartAutoApprovalEndTime	string HH:MM	End of the auto-approval window
smartAutoApprovalDays	string	WEEKDAYS, WEEKENDS, or EVERYDAY

Per-employee settings

Get each employee's linkId from GET /api/public/v1/companies/:companyId/ewa/employees (EWA_READ). Send at least one of: enrolled (boolean), maxWithdrawalPercentage (0–50), approvalMode (MANUAL or AUTOMATIC), maxRequestsPerMonth (1–50).

What's next

The company is now live and fully configured. The next step is onboarding employees — continue to the Employee Onboarding Guide for the full flow covering registration, phone verification, selfie upload, company linking, and work email verification.

Field	Type		Notes
firstName	string	required	1–100 characters
lastName	string	required	1–100 characters
phoneNumber	string	required	International format, e.g. +233201234567. Receives the SMS code and must be unique.
companyId	integer	optional	A company created with your developer account. If present, workEmail is also required.
workEmail	string	optional	If present, companyId is also required. Must match the company domain when the domain is enforced.

Status	Message	Fix
400	Work email must use the company domain: acmecorp.com	Use a work email on the company domain
404	Company not found	Use a company created with your developer account
409	An account with this phone number already exists	The phone number is already registered

Status	Message	Fix
409	Invalid OTP code	Ask the employee to check the code and try again
409	OTP code has expired	Resend the code
409	Phone number is already verified	Continue to the next step

Send the image as multipart/form-data in a field named selfie.

Status	Message	Fix
400	Selfie image is required	Send the file in the selfie field
400	Verify the employee's phone number before uploading a selfie	Complete Step 2 first
400	Face check failed (no face, several faces or poor quality)	Ask the employee for a clear photo of their face only

Status	Message	Fix
400	A work email with the domain @acmecorp.com is required to link to this company	Use the company's domain when email-domain enforcement is enabled
404	Company not found	Use a valid company linked to your developer account
409	Your current company link must be revoked before linking to a new company	Only one active company relationship is allowed at a time
409	Your link to this company was rejected and cannot be re-attempted	Rejected links are terminal for that employee-company pair
409	This work email is already in use at this company	Use the employee's own work email

Status	Message	Fix
409	Invalid OTP code	Ask the employee to check the code and try again
409	OTP has expired. Please re-initiate the link.	Link the company again (Step 4)
409	Work email is already verified	Continue to Step 6
404	Company link not found	Check companyId, or link the company first

Status	What it means	What to do
PENDING	Awaiting company-admin review	Wait for the company admin to approve or reject in the Work Benefit platform
APPROVED	The employee is successfully linked to the company	Continue with income verification and benefit usage flows
REJECTED	The company declined the employee link	This employee cannot re-attempt linking to the same company

1 · Check current salary

2 · Set or update salary

Status	Message	Fix
409	Cannot update a verified salary	Once verification is approved, treat salary as read-only

Case A — first-time or still pending

Case B — approved, no new review pending

Case C — approved, but a salary review is pending

Field	Type		Notes
monthlyIncome	number	required	Must be 0 or greater
bank	array	optional	Bank statement documents
momo	array	optional	Mobile money statement documents
otherFiles[].type	string		PAY_SLIP, OFFER_LETTER, BUSINESS_REGISTRATION, or OTHER
otherFiles[].file	string		Base64-encoded file content. No name field for other files.

Status	Message	Fix
409	A pending income verification already exists	Load the existing pending request and update it with PATCH instead

All fields are optional. Send only the parts that need to change.

Field	Description
earnedWage	Wages accrued so far this pay cycle based on days worked
availableToUse	Amount still available to request this cycle. The request amount must not be higher than this.
maxAmountAllowed	Upper limit for this cycle, based on the employee's maximumWithdrawalPercentage and the company's salary exposure cap
availableToWithdraw	Approved funds not yet transferred out — ready to withdraw now
serviceChargePercentage	Service charge rate applied to each request (0.049 = 4.9%)
cutoffDate	Deadline for submitting EWA requests this pay cycle
repaymentDate	Date the advance is deducted from the employee's salary

Status	Message	Fix
400	You have a pending request	Wait for the existing pending request to be approved or rejected before submitting a new one
400	Amount requested exceeds available amount. Available: {n}	Use a value ≤ availableToUse from Step 1
400	EWA requests are no longer accepted for this pay cycle. The cut-off date has passed.	Wait for the next pay cycle
404	You are not associated with an active company. Please contact your administrator.	The employee needs an approved link to an ACCEPTED company
403	Earned Wage Access is not currently available at your company.	Enroll the EWA benefit for the company and make sure it is ACTIVE
403	You are not enrolled for Earned Wage Access. Please contact your administrator for assistance.	Enroll the employee with PATCH /companies/:companyId/ewa/employees/:linkId and { "enrolled": true }
403	Your salary details have not been verified yet. Please contact your administrator.	Complete the income verification flow first
403	Sandbox API keys cannot be used in a production environment.	Use a wb_live_ key for production

Filter by status to narrow results. Supports pagination via page and pageSize (max 100).

Status	What it means	What to do
PENDING	Awaiting manual review	Poll again later
APPROVED	Funds are ready to withdraw	Continue to Step 4
REJECTED	Request was declined	Inform the employee and let them submit a new request in the next cycle

1 · Check whether the employee has a PIN

If hasPin is true, skip to Step 5.

2 · Create a PIN setup session

redirectUrl is optional. It is where the employee is sent after setting the PIN.

3 · Employee sets the PIN on the hosted page

Pass accountType (BANK or MOBILE_MONEY) and amount as query parameters.

Field	Type		Notes
amount	number	required	Amount to withdraw, at least 1, up to 2 decimal places. It must also be at least GHS 10 and no more than availableToWithdraw when the employee submits.
accountType	string	required	BANK or MOBILE_MONEY
redirectUrl	string (URL)	optional	Where to send the employee after a successful withdrawal

Status	Message	Fix
403	Your account has been deactivated. Please contact your administrator for assistance.	The employee account is inactive
403	Sandbox API keys cannot be used in a production environment.	Use a wb_live_ key for production
404	Employee not found	Use an employee registered with your developer account

Check withdrawal outcome

Supports page, pageSize (max 100) and type query parameters. type is one of requests, withdrawals, rent or shop. Use type=withdrawals to see only withdrawals. The result is grouped into separate lists, not the standard list envelope.

1 · Get the employee's rent limit

2 · Preview costs for a specific amount & duration

Pass amount (the rent cost to finance) and paybackDuration (months to repay) as query parameters. premiumRate is optional; the default is 2.5% per month.

3 · Check physical inspection fees

4 · Check qualification (optional)

Pass amount and paybackDuration as query parameters. The check uses the employee's income and employment details.

results is "P" when the employee qualifies, or "F" with a message when they do not.

Field	Type		Notes
monthlyRentBudget	number	required	The employee's monthly rent cost in GHS
durationOfRent	integer	required	How many months the tenancy lasts (minimum 1)
rentPaybackPeriod	integer	required	How many months to repay the advance (minimum 1). Keep it within maxPaybackPeriod from the limit.
fullNameOfLandlord	string	optional	Landlord's full name
phoneNumberOfLandlord	string	optional	Landlord's contact number
propertyGpsAddress	string	optional	Ghana Post GPS address of the property

Status	Message	Fix
404	No emergency contact found	Add an emergency contact via POST /employees/:id/emergency-contact first
404	No salary information found	Set salary via PUT /employees/:id/income first
400	You are not eligible for this benefit. A minimum monthly salary of GHS 1,500 is required.	The employee's salary is below the minimum

Field	Type		Notes
expressServiceForPhysicalInspection	boolean	optional	When true, charges GHS 250 (express). When false or omitted, charges GHS 130 (standard).
dateAndTimeForVerification	string	optional	Preferred inspection date, format YYYY-MM-DD

Redirect the employee to authorization_url. Once they complete the payment, the application stage advances to PAID_PHYSICAL_INSPECTION.

Once the payment plan is in place, the tenancy agreement is ready to review and sign. Continue to Step 5.

1 · Generate the tenancy agreement link

2 · Optionally email the agreement

3 · Record the employee's signature

No request body required. Calling this endpoint records the employee's acceptance of the tenancy agreement terms.

No request body required. The amount is taken from the application's initial deposit. Returns 400 if the deposit is not available yet.

Redirect the employee to authorization_url. After payment, the stage advances to PAID_INITIAL_DEPOSIT and the employee can move in.

1 · Get the payment plan

2 · Initialize a monthly payment

3 · View payment history