Team API

Your team directory and staff files — hiring, onboarding and leaving.

Module code employees · 4 actions · 1 data models · 4 events. A key or token never does more here than the person behind it can; row-level security applies exactly as in the app. Scopes: employees (everything), employees:read (read only) or employees:<capability>.

Resources

Lists take limit (up to 200), cursor, order (e.g. -created_at), fields and q; every other query parameter is a column filter: ?status=paid, ?total[gte]=100, ?id[in]=a,b, ?x=null.

Actions

employees.activate

Finish onboarding — Moves an onboarding employee to active.

Needs employees:manage · changes data

• Canonical address: POST /api/v1/actions/employees.activate

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: employees.activated

What it writes: employment (update) — Sets the status to active

curl -X POST https://app.getera.io/api/v1/employments/actions/activate \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"userId":"APP_USER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "employees.activated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.employments.activate({
  userId: "APP_USER_ID"
})

era employments activate \
  --user-id "APP_USER_ID"

{
  "name": "era__employees__activate",
  "arguments": {
    "userId": "APP_USER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold employees:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_employed, not_onboarding · 429 slow down

employees.end_employment

End employment — Records the last day and the reason, and names everything they still own so it can be handed over.

Needs employees:manage · reaches outside (sends, publishes or charges) · asks a person to confirm when Era runs it

• Canonical address: POST /api/v1/actions/employees.end_employment

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: employees.employment_ended

What it writes: employment (update) — Closes the personnel file

curl -X POST https://app.getera.io/api/v1/employments/actions/end_employment \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"userId":"APP_USER_ID","endDate":"2026-11-02","reason":"resigned"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "employees.employment_ended"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.employments.endEmployment({
  userId: "APP_USER_ID",
  endDate: "2026-11-02",
  reason: "resigned"
})

era employments end_employment \
  --user-id "APP_USER_ID" \
  --end-date "2026-11-02" \
  --reason "resigned"

{
  "name": "era__employees__end_employment",
  "arguments": {
    "userId": "APP_USER_ID",
    "endDate": "2026-11-02",
    "reason": "resigned"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold employees:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 cannot_end_self, not_employed, already_ended, end_before_hire · 429 slow down

employees.hire

Hire — Opens a personnel file for a workspace member — onboarding first, or straight to active.

Needs employees:manage · changes data

• Canonical address: POST /api/v1/actions/employees.hire

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: employees.hired

What it writes: employment (upsert) — Opens (or re-opens) the personnel file

curl -X POST https://app.getera.io/api/v1/employments/actions/hire \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"userId":"APP_USER_ID","hireDate":"2026-11-02"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "employees.hired"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.employments.hire({
  userId: "APP_USER_ID",
  hireDate: "2026-11-02"
})

era employments hire \
  --user-id "APP_USER_ID" \
  --hire-date "2026-11-02"

{
  "name": "era__employees__hire",
  "arguments": {
    "userId": "APP_USER_ID",
    "hireDate": "2026-11-02"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold employees:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_a_member, already_employed · 429 slow down

employees.update

Edit employment details — Hire date, employment type and work contact.

Needs employees:manage · changes data

• Canonical address: POST /api/v1/actions/employees.update

Input

Preconditions

The action is refused with 409 and one of these codes:

Events it publishes: employees.updated

What it writes: employment (update) — Rewrites the given fields

curl -X POST https://app.getera.io/api/v1/employments/actions/update \
  -H "Authorization: Bearer $ERA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"userId":"APP_USER_ID"}'

{
  "ok": true,
  "result": "…",
  "events": [
    "employees.updated"
  ]
}

import { createEra } from "@getera/sdk"

const era = createEra({ apiKey: process.env.ERA_API_KEY })
const res = await era.employments.update({
  userId: "APP_USER_ID"
})

era employments update \
  --user-id "APP_USER_ID"

{
  "name": "era__employees__update",
  "arguments": {
    "userId": "APP_USER_ID"
  }
}

Errors: 401 no or expired credential · 403 the credential does not hold employees:manage · 404 the record or module is outside what it may reach · 422 invalid input (problems[]) · 409 not_employed · 429 slow down

Data models

Employment

Table employment · Resource employments

• GET /api/v1/employments
• GET /api/v1/employments/{id}

Primary key: workspace_id, user_id

Checks:

• CHECK (((end_date IS NULL) OR (end_date >= hire_date)))
• CHECK (((status = 'terminated'::text) = ((end_date IS NOT NULL) AND (end_reason IS NOT NULL))))
• CHECK (((end_reason IS NULL) OR (end_reason = ANY (ARRAY['resigned'::text, 'terminated'::text, 'retired'::text, 'contract_ended'::text, 'other'::text]))))

Events

Workflows and webhooks react to these events.