Add an employee

Add somebody to the directory with the net amount they are paid.

Authorization

OAuth2PasswordBearer

AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Someone on the payroll. IN-302.

Where the money goes is given one of two ways: beneficiary_id for a saved recipient, or account_identifier with enough context to reach it. Prefer the beneficiary — it has been name-checked and screened once, whereas a raw account is re-typed every time somebody edits the record.

employee_number*Employee Number

Your identifier for them. Unique per business, and what a payroll run reports against, so keep it stable across runs.

Length1 <= length <= 64

Example"EMP-0042"

full_name*Full Name

As it appears on the account being paid. A mismatch is the most common reason a payroll line is rejected by the receiving bank.

Length1 <= length <= 200

Example"Aline Uwase"

net_pay_minor*Net Pay Minor

Minor units. What the employee receives — this is not a gross figure and nothing is deducted from it. 45000000 is 450,000.00 RWF.

Range0 < value

Example45000000

currency*Currency

ISO 4217. Must match the currency of the run that pays them — a run pays one currency.

Length3 <= length <= 3

Example"RWF"

payout_method*PayoutMethodKind

Decides the rail: a wallet and a bank account differ. It also decides what account_identifier must look like — a phone number for mobile_money, an account number for bank.

Example"mobile_money"

Value in

"mobile_money"
"bank"

employment_type?EmploymentType

Reporting only. It does not change how or when they are paid.

Default"full_time"

Example"full_time"

Value in

"full_time"
"part_time"
"contractor"

beneficiary_id?|

A saved, screened recipient. Preferred over a raw account: send this and the account fields below are unnecessary.

Example"b7e3f1a2-5c4d-4e6f-8a9b-0c1d2e3f4a5b"

account_identifier?|

Where the pay lands when there is no beneficiary_id — the wallet number for mobile_money, the account number for bank. Mobile money takes the international form.

Example"+250788123456"

bank_name?|

For bank payouts, as written on the account.

Example"Banque de Kigali"

country_code?|

ISO 3166-1 alpha-2. Picks the corridor, so a payroll spanning two countries routes each line correctly.

Example"RW"

department?|

Reporting and filtering only.

Example"Engineering"

email?|

Where a payslip is sent, where you send them.

Example"aline@example.com"

started_on?|

YYYY-MM-DD. Reporting only; it does not prorate pay.

Example"2024-02-01"

Response Body

`application/json`

curl -X POST "https://example.com/api/b/v1/payroll/employees" \  -H "Content-Type: application/json" \  -d '{    "employee_number": "EMP-0042",    "full_name": "Aline Uwase",    "net_pay_minor": 45000000,    "currency": "RWF",    "payout_method": "mobile_money"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "employee_number": "string",  "full_name": "string",  "department": "string",  "employment_type": "full_time",  "net_pay_minor": 0,  "currency": "string",  "payout_method": "mobile_money",  "beneficiary_id": "0a8df251-de2a-4394-bffc-6b9d9795700d",  "account_identifier": "string",  "country_code": "string",  "status": "active",  "created_at": "2019-08-24T14:15:22Z"}

Authorization

Cookie Parameters

Request Body

Response Body

201application/json

422application/json

`application/json`

`application/json`