Admin Endpoints: Pay Data, Configuration, and Roles

The admin surface is where pay data enters MeetCost, where disclosure policy is configured, and where role assignments are managed. Every route here is restricted to the admin role (or the finance role for read-only coverage and pay listing) unless noted. The most important invariant on this entire surface: every route that touches a pay figure writes its audit row in the same database transaction as the read. A read that was not logged is a read that did not commit. This is not a post-hoc side effect — it is a transactional guarantee.

Pay data

POST /api/v1/admin/pay/upload

Upload pay data for multiple employees from a CSV file. Requires admin role. Validation is all-or-nothing: if any single row contains an error, nothing is written. A partially-imported payroll would silently fall back the bad entries to the blended default rate, which is worse than no import. Fix every reported error and re-upload. Pass ?dry_run=true to validate the file and see what would be written without committing anything. The CSV upload accepts the following columns. Common header name aliases from popular payroll exports are recognised automatically, because payroll systems never agree on column names. Every bad row is reported at once so operators can fix them in one pass.

Column	Required	Description
`employee_email`	Yes	Employee’s work email address
`annual_pay`	Yes	Annual or hourly pay amount (positive number)
`currency`	Yes	ISO 4217 currency code (e.g. `USD`, `GBP`)
`effective_date`	Yes	Date this pay record takes effect (`YYYY-MM-DD`)
`pay_basis`	No	`annual` (default) or `hourly`

Query parameters

boolean

default:"false"

When true, validates the CSV and reports any errors but writes nothing to the database. The response shows how many rows would be created or updated.

Response

{
  "created": 142,
  "updated": 8,
  "skipped": 0,
  "errors": []
}

On validation failure, errors contains a list of human-readable error strings (one per bad row, up to 50), and created, updated are both 0.

Example

curl -X POST "https://meetcost.acme-corp.internal/api/v1/admin/pay/upload?dry_run=true" \
  -H "Authorization: Bearer <admin-token>" \
  -F "file=@payroll-q3-2026.csv"

POST /api/v1/admin/pay

Add or update a pay record for a single employee. Requires admin role.

string

required

Employee’s email address.

number

required

Pay amount. Must be greater than 0.

string

ISO 4217 currency code (3 characters). Defaults to the org’s base_currency.

string

Date this record takes effect (YYYY-MM-DD). Defaults to today.

string

default:"annual"

annual or hourly.

Example

{
  "employee_email": "ada@example.com",
  "annual_pay": 95000,
  "currency": "USD",
  "effective_date": "2026-01-01",
  "pay_basis": "annual"
}

GET /api/v1/admin/pay

List pay records. Requires at minimum the finance role. By default, actual pay amounts are masked (shown as a placeholder string like "USD ***"). Pass ?reveal=true to decrypt and return actual amounts. Revealing pay data:

Requires admin role, or finance role with finance_can_view_raw_pay policy enabled
Writes one audit event per person revealed, so the question “who has seen my salary data, and when?” is answerable via GET /api/v1/admin/audit

Query parameters

boolean

default:"false"

Decrypt and return actual pay amounts. Audited per person. Requires admin role (or finance role if finance_can_view_raw_pay is enabled).

string

Filter by email address (partial match).

integer

default:"100"

Maximum records to return. Capped at 500.

integer

default:"0"

Pagination offset.

Response example (masked)

[
  {
    "employee_email": "ada@example.com",
    "currency": "USD",
    "effective_date": "2026-01-01",
    "pay_basis": "annual",
    "source": "csv",
    "masked": "USD ***",
    "amount": null
  }
]

Response example (revealed)

[
  {
    "employee_email": "ada@example.com",
    "currency": "USD",
    "effective_date": "2026-01-01",
    "pay_basis": "annual",
    "source": "csv",
    "masked": "USD ***",
    "amount": "95000.0000"
  }
]

GET /api/v1/admin/pay/export.csv

Export all pay data as a CSV file. Admin only. Heavily audited — writes one audit event per row exported. Returns text/csv with the columns: employee_email, annual_pay, currency, effective_date, pay_basis.

curl "https://meetcost.acme-corp.internal/api/v1/admin/pay/export.csv" \
  -H "Authorization: Bearer <admin-token>" \
  -o pay-export.csv

DELETE /api/v1/admin/pay/

Delete all pay records for an employee. Used for offboarding leavers and processing GDPR/CCPA erasure requests. Requires admin role. Deletes every version of the record (all effective dates).

Path parameters

string

required

The employee’s email address. URL-encode the @ if necessary.

Response

{
  "employee_email": "ada@example.com",
  "records_removed": 3
}

GET /api/v1/admin/coverage

Shows how much of the people directory has valid pay data, and how fresh that data is. Requires finance role or above.

Response

{
  "directory_people": 320,
  "covered_people": 298,
  "uncovered_people": 22,
  "coverage_percent": 93.13,
  "total_records": 412,
  "newest_effective_date": "2026-07-01",
  "oldest_effective_date": "2023-01-01",
  "stale": true,
  "stale_message": "Newest pay record is 195 days old (threshold 180). Estimates may be understated."
}

stale_message is safe to show directly to finance users. When stale is true, estimates for some employees may be based on outdated rates. Upload a fresh payroll CSV or trigger an HRIS sync to resolve this.

Configuration

GET /api/v1/admin/config

Returns the current org configuration. Admin only.

PATCH /api/v1/admin/config

Updates one or more configuration values. Admin only. Every change is audited with a before/after snapshot of the changed fields. All fields are optional (this is a partial update):

number

Payroll loading multiplier applied to raw salary. Default 1.30 (i.e. 30% on-costs). Must be between 0 and 5.

integer

Hours per year used to convert annual pay to an hourly rate. Default 2080. Must be between 1 and 8760.

number

Org-wide blended annual pay used for employees with no individual record. 0 means uncosted (those people contribute nothing to totals). Must be 0 or greater.

string

Default currency for the org (ISO 4217, 3 characters). Used when a pay record has no explicit currency.

boolean

When true, authorised callers can see individual per-person costs in responses. Default false. Enabling this has privacy implications — it is audited and flagged in the admin UI.

integer

Minimum headcount below which per-person breakdowns are suppressed even when per_person_breakdown_enabled is true. Default 5. Range 2–100.

boolean

When false (the default), only organisers see cost totals. Participants see headcount and duration only.

boolean

When true, users with the finance role may call GET /api/v1/admin/pay?reveal=true. Default false.

boolean

When true, totals for small meetings are rounded to two significant figures (total_is_approximate: true). Default true.

number

Cost above which a cost_above_threshold nudge is emitted. Default 500.

integer

Headcount above which a headcount nudge is emitted. Default 8.

integer

Duration above which a duration nudge is emitted. Default 60.

integer

Age (in days) after which pay data is considered stale. Affects the stale flag in coverage reports. Default 180. Minimum 1.

Example

curl -X PATCH https://meetcost.acme-corp.internal/api/v1/admin/config \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"participants_see_cost": true, "nudge_cost_threshold": 750}'

Response

{
  "changed": {
    "participants_see_cost": {"before": false, "after": true},
    "nudge_cost_threshold": {"before": "500.0000", "after": "750.0000"}
  },
  "config": {
    "loading_factor": "1.3000",
    "working_hours_per_year": 2080,
    "participants_see_cost": true,
    "nudge_cost_threshold": "750.0000"
  }
}

Role management

GET /api/v1/admin/roles

Lists all role assignments. Admin only.

[
  {
    "email": "bola@example.com",
    "role": "finance",
    "team_id": null,
    "granted_by": "ada@example.com",
    "granted_at": "2026-06-01T10:30:00Z"
  }
]

PUT /api/v1/admin/roles

Assign or update a role. Admin only. Audited.

string

required

The user’s email address.

string

required

One of participant, organiser, team_lead, finance, admin.

string

Team identifier for team_lead assignments. Scopes the team_lead’s reporting access.

DELETE /api/v1/admin/roles/

Revokes the role assignment for the specified email. The user reverts to participant. Admin only. Audited. Returns 404 if no role row exists.

Audit log

GET /api/v1/admin/audit

Query the audit log. Admin only.

string

Filter by the target of the action. Pass an employee email to answer: “who has accessed this person’s pay data, and when?”

string

Filter by the actor (the person who performed the action).

string

Filter by action type, e.g. PAY_VIEW, PAY_EXPORT, CONFIG_UPDATE, ROLE_GRANT.

integer

default:"30"

Look back this many days. Range 1–3650.

integer

default:"200"

Maximum events to return. Capped at 1000.

Response example

[
  {
    "id": "e1f2a3b4...",
    "at": "2026-08-28T14:22:10Z",
    "actor": "bola@example.com",
    "actor_role": "finance",
    "action": "PAY_VIEW",
    "target": "ada@example.com",
    "detail": { "via": "admin_list", "search": null },
    "source_ip": "10.0.1.42"
  }
]

Adapters and sync

GET /api/v1/admin/adapters

Returns which provider adapters have credentials configured. An adapter with no credentials simply does nothing — it is not an error. Admin only.

{
  "google": { "configured": true },
  "microsoft": { "configured": true },
  "zoom": { "configured": false }
}

POST /api/v1/admin/sync/directory

Triggers a directory sync immediately rather than waiting for the scheduled run. Admin only.

string

Sync only this provider (google, microsoft). Omit to sync all configured providers.

Returns a list of sync results, one per provider run:

[
  {
    "adapter": "google",
    "created": 5,
    "updated": 12,
    "deactivated": 1,
    "errors": []
  }
]

Returns 412 Precondition Failed if no directory provider is configured.

POST /api/v1/admin/sync/hris

Pulls pay data from the configured HRIS integration. Admin only. Returns 412 Precondition Failed if MEETCOST_HRIS_ADAPTER is not set.

{
  "adapter": "workday",
  "created": 18,
  "updated": 6,
  "errors": []
}

GET /api/v1/admin/sync-state

Returns the last-run timestamps and record counts for every adapter. Use this to check whether the directory or HRIS sync is current and to diagnose staleness. Admin only.

[
  {
    "adapter": "google",
    "last_run_at": "2026-08-28T08:00:00Z",
    "last_success_at": "2026-08-28T08:00:05Z",
    "record_count": 298,
    "last_error": null
  }
]

​Pay data

​POST /api/v1/admin/pay/upload

​Query parameters

​Response

​Example

​POST /api/v1/admin/pay

​Example

​GET /api/v1/admin/pay

​Query parameters

​Response example (masked)

​Response example (revealed)

​GET /api/v1/admin/pay/export.csv

​DELETE /api/v1/admin/pay/

​Path parameters

​Response

​GET /api/v1/admin/coverage

​Response

​Configuration

​GET /api/v1/admin/config

​PATCH /api/v1/admin/config

​Example

​Response

​Role management

​GET /api/v1/admin/roles

​PUT /api/v1/admin/roles

​DELETE /api/v1/admin/roles/

​Audit log

​GET /api/v1/admin/audit

​Response example

​Directory

​GET /api/v1/admin/directory

​Query parameters

​Response example

​Adapters and sync

​GET /api/v1/admin/adapters

​POST /api/v1/admin/sync/directory

​POST /api/v1/admin/sync/hris

​GET /api/v1/admin/sync-state

Pay data

POST /api/v1/admin/pay/upload

Query parameters

Response

Example

POST /api/v1/admin/pay

Example

GET /api/v1/admin/pay

Query parameters

Response example (masked)

Response example (revealed)

GET /api/v1/admin/pay/export.csv

DELETE /api/v1/admin/pay/

Path parameters

Response

GET /api/v1/admin/coverage

Response

Configuration

GET /api/v1/admin/config

PATCH /api/v1/admin/config

Example

Response

Role management

GET /api/v1/admin/roles

PUT /api/v1/admin/roles

DELETE /api/v1/admin/roles/

Audit log

GET /api/v1/admin/audit

Response example

Directory

GET /api/v1/admin/directory

Query parameters

Response example

Adapters and sync

GET /api/v1/admin/adapters

POST /api/v1/admin/sync/directory

POST /api/v1/admin/sync/hris

GET /api/v1/admin/sync-state