➕ Add Employee (POST /employees)

Add a new employee to your organization using the FlexPay API. This endpoint requires authentication and the appropriate scopes.

---

Endpoint

bashCopyEditPOST https://api.flexpay.dev/v1/employees

---

Authentication

• Requires Bearer token with scope: write:employees

• Use HTTPS for all requests

---

Request Headers

Header	Value	Description
Authorization	Bearer {your_api_token}	Token for authentication
Content-Type	application/json	Payload format

---

Request Body

jsonCopyEdit{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[e-mail]",
  "employment_type": "full_time",
  "pay_group": "engineering",
  "pay_schedule": "biweekly",
  "start_date": "2025-06-01",
  "bank_account": {
    "account_number": "123456789",
    "routing_number": "987654321",
    "account_type": "checking"
  }
}

Field	Type	Required	Description
first_name	string	Yes	Employee’s first name
last_name	string	Yes	Employee’s last name
email	string	Yes	Employee’s contact email
employment_type	string	Yes	Employment classification (see glossary)
pay_group	string	Yes	Employee’s pay group (must match configured groups)
pay_schedule	string	Yes	Pay schedule for employee (e.g., biweekly)
start_date	string	Yes	ISO 8601 start date (YYYY-MM-DD)
bank_account	object	Optional	Direct deposit info; includes account number, routing number, account type

Table: Corresponding to the request body, this is a deeper dive into each parameter FlexPay needs.

---

Successful Response

HTTP 201 Created

jsonCopyEdit{
  "employee_id": "emp_abc123",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[e-mail]",
  "employment_type": "full_time",
  "pay_group": "engineering",
  "pay_schedule": "biweekly",
  "start_date": "2025-06-01",
  "status": "active"
}

---

Error Responses

HTTP Code	Error Message	Description
400	"Invalid request body"	Missing or malformed fields
401	"Unauthorized"	Missing or invalid token
403	"Forbidden: Insufficient scope"	Token lacks required scope
409	"Employee already exists"	Employee with email already onboarded

---

Rate Limits

This endpoint counts against your write:employees scoped rate limits. Refer to the Authentication & Rate Limits section for details on burst and sustained limits.

---

Example Curl Request

bashCopyEditcurl -X POST https://api.flexpay.dev/v1/employees \
-H "Authorization: Bearer sk_live_abc123..." \
-H "Content-Type: application/json" \
-d '{
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "[e-mail]",
  "employment_type": "full_time",
  "pay_group": "engineering",
  "pay_schedule": "biweekly",
  "start_date": "2025-06-01",
  "bank_account": {
    "account_number": "123456789",
    "routing_number": "987654321",
    "account_type": "checking"
  }
}'

---

Notes & Tips

• Ensure your pay_group and employment_type values exactly match the green terms configured in the system to avoid 400 errors.

• The start_date The field uses the ISO 8601 format (YYYY-MM-DD).

• Including bank account details enables direct deposit setup immediately; otherwise, this can be added later through a separate payroll update.

• When onboarding many employees, monitor your rate limits closely to avoid 429 Too Many Requests responses.

• Use scoped tokens with least privilege for security best practices.

---

Related Endpoints

Endpoint	Description
GET /employees	List all employees
PATCH /employees/{id}	Update employee details
DELETE /employees/{id}	Remove an employee

Summary

Adding employees through the FlexPay API is straightforward once you have a valid, properly scoped Bearer token. The key is to match all data fields — especially employment types and pay groups — to the exact values configured in your FlexPay Admin Dashboard. Proper use of start_date and optional bank account details streamlines onboarding and payroll readiness. This endpoint empowers you to automate onboarding flows, reduce manual data entry, and integrate FlexPay deeply into your HR systems or third-party tools. Always remember to monitor your API usage against rate limits and handle errors gracefully. With the ability to programmatically add employees, you’re building the foundation for scalable, automated payroll operations.

---

What’s Next?

After successfully onboarding employees, the natural next step is submitting Payroll runs via the API. The next section — 💰 Submit Payroll (POST /payroll) — covers how to create, review, and submit payroll with confidence using authenticated calls. We’ll explore how to tie employee pay groups and schedules into payroll runs and handle success and error responses.

This flow completes your basic payroll automation lifecycle: authentication, onboarding, and pay submission. If you’re ready, head over to Submit Payroll to keep building with FlexPay.

---