Payroll Integration Guide

Partners will send lightweight event notifications to a Basic Capital webhook when key events occur in their systems. We will provision a specific webhook url for you.

Testing
https://api.basiccapital.dev/v1/{your_payroll_system}

Production
https://api.basiccapital.com/v1/{your_payroll_system}

These are events you will send to the webhook endpoint we will provision for you.

POST /employment/event

Send this event when an employee is hired, terminated, or updated (e.g., compensation changes).

Request Body:

{
  "event_id": "evt_1a2b3c4d5e6f",
  "employer_id": "emp_9z8y7x6w5v4u",
  "employee_id": "ee_7k6j5h4g3f2d",
  "event_type": "EMPLOYEE_HIRED"
}

Event Types:

• EMPLOYEE_HIRED - New employee started
• EMPLOYEE_UPDATED - Employee information changed (compensation, role, etc.)
• EMPLOYEE_TERMINATED - Employee left the company

Response: 202 Accepted

POST /employer/event

Send this event when an employer is updated or company-wide deductions are changed.

Request Body:

{
  "event_id": "evt_4d5e6f7g8h9i",
  "employer_id": "emp_9z8y7x6w5v4u",
  "event_type": "EMPLOYER_UPDATED"
}

Event Types:

• EMPLOYER_UPDATED - Employer information or company-wide deductions changed

Response: 202 Accepted

POST /payroll/event

Send this event when payroll is processed and paid.

Request Body:

{
  "event_id": "evt_5e6f7g8h9i0j",
  "employer_id": "emp_9z8y7x6w5v4u",
  "payroll_event_id": "prl_3m2n1b0v9c8x",
  "event_type": "PAYROLL_PAID",
  "pay_date":"YYYY-MM-DD"
}

Event Types:

• PAYROLL_PAID - Payroll has been processed and paid

Response: 202 Accepted