---
title: "Add or update a person"
method: POST
path: "/people"
tags: ["people"]
---

# Add or update a person

`POST /people`

## Request

- Base URL: `https://api.fallax.io/v1`
- URL: `https://api.fallax.io/v1/people`
- Auth: HTTP bearer

Create a person, or update the one that already has this address. Safe to call more than once with the same address, which is what makes it usable from an onboarding workflow that may retry.

## Request body

- PersonInput
  - `email` string, required: Required. The person's address.
  - `firstName` string, nullable: Optional.
  - `lastName` string, nullable: Optional.
  - `department` string, nullable: Optional. Reporting and breakdowns group on this.
  - `position` string, nullable: Optional. Job title.
  - `locale` string, nullable: Optional BCP 47 tag, e.g. `nl-BE`. Decides which translation of a lure they are sent.
  - `timezone` string, nullable: Optional IANA zone, e.g. `Europe/Brussels`. Decides what local time they are sent at.
  - `status` 'active' | 'excluded' | 'archived': `active`, `excluded` (stays in the directory, never simulated, not billed) or `archived` (offboarded).

## Response `200`

Add or update a person

- PersonUpsert
  - `id` string, required
  - `email` string, required
  - `firstName` string, nullable, required
  - `lastName` string, nullable, required
  - `department` string, nullable, required
  - `position` string, nullable, required
  - `locale` string, nullable, required
  - `timezone` string, nullable, required
  - `status` 'active' | 'excluded' | 'archived', required
  - `syncedProvider` string, nullable, required
  - `createdAt` string, date-time, nullable, required
  - `created` boolean, required

## Other responses

- `400`: A parameter or body field the API cannot use. The message names the field.
- `401`: No key, an unknown key, or one that has been revoked.
- `403`: A read-only key was used on a write endpoint.
- `404`: No such endpoint, or no such row in this workspace. The two are deliberately indistinguishable from outside: another workspace's ids must not be probeable.
- `405`: The path exists but not with that verb. `Allow` lists the verbs that work.
- `429`: More than 120 requests in a minute on one key. `Retry-After` says how long to wait. A poll every minute, and the paging behind it, is nowhere near this.
- `500`: Our fault. Safe to retry.

---

[API](https://skmtc.dev/fallax/apis/fallax-api.md) · [All operations](https://skmtc.dev/fallax/apis/fallax-api/llms.txt) · [OpenAPI document](https://skmtc.dev/fallax/apis/fallax-api/revisions/b5731fd85ef8?raw)