# Quickstart

> From API key to first accepted record in five steps.

## 1. Get your credentials

Email [developer@paycaptain.com](mailto:developer@paycaptain.com) for two things:

- an **API key**, sent as the `X-API-Key` header on every request
- your **company code**, sent as `company` on every record and query

Store the key in a secrets manager and call the API from your server only. [Trust and security](https://developer.paycaptain.com/trust#api-keys) has the full list of requirements.

## 2. Make a first call

All requests go to `https://api.paycaptain.com` over HTTPS with JSON bodies.

```bash
curl "https://api.paycaptain.com/employees?company=ABC" \
  -H "X-API-Key: $PAYCAPTAIN_API_KEY"
```

A `200` returns a page of up to 50 employees. A `204` means there are no more pages.

## 3. Create an employee

`POST /employee` creates the employee, or updates them if the `hrEmployeeId` already exists. This is the smallest valid record for a salaried employee:

```json
{
  "company": "ABC",
  "hrEmployeeId": "9876543210",
  "payrollCode": "123",
  "firstName": "Jason",
  "lastName": "Smith",
  "dateOfBirth": "2000-01-01",
  "gender": "Male",
  "email": "jason@example.com",
  "mailingStreet": "1 Main Street",
  "mailingCity": "Green City",
  "mailingStateProvince": "Happy County",
  "mailingPostalCode": "SW1A 1AA",
  "mailingCountry": "United Kingdom",
  "startDate": "2023-12-01",
  "payBasis": "Salaried",
  "salary": 12000,
  "payEffectiveDate": "2023-12-01",
  "payGroup": "Monthly"
}
```

```bash
curl -X POST "https://api.paycaptain.com/employee" \
  -H "X-API-Key: $PAYCAPTAIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d @employee.json
```

Check every value against the [Employee fields](https://developer.paycaptain.com/fields/employee) before sending. Only send [PAYE employees](https://developer.paycaptain.com/rules#who-to-send).

## 4. Send a shift

Shifts must be [approved](https://developer.paycaptain.com/rules#approval) in your system first.

```json
{
  "shiftId": "SH-000481",
  "company": "ABC",
  "hrEmployeeId": "9876543210",
  "payrollCode": "123",
  "date": "2026-11-02",
  "type": "Working",
  "payBasis": "Hourly",
  "units": 7.5,
  "rate": 15.25
}
```

Pay elements work the same way through `POST /payment`. See [Shift fields](https://developer.paycaptain.com/fields/shift) and [Payment fields](https://developer.paycaptain.com/fields/payment).

## 5. Read payslips

```bash
curl "https://api.paycaptain.com/payslips?company=ABC&payPeriod=2026-11&page=1" \
  -H "X-API-Key: $PAYCAPTAIN_API_KEY"
```

`payPeriod` is the Pay Period reference shown in the PayCaptain app. Keep requesting the next page until you receive a `204`.

## Before you go live

- Enforce every [field rule](https://developer.paycaptain.com/fields/employee) and [business rule](https://developer.paycaptain.com/rules) in your own validation layer.
- Stay inside the [rate limits](https://developer.paycaptain.com/reliability#rate-limits) and retry safely.
- Pass the [compliance tests](https://developer.paycaptain.com/testing) in your deployment pipeline.