People
Create person
POST
/api/v1/people
on the Little Outreach JSON API. Send
Authorization: Bearer
or
X-Api-Key
on every request.
Description
Creates a Person record plus a citation on the same transaction.
**Required:** a profile body (at minimum `first_name` or `last_name`) and a citation with
`source_category` and an `http(s)` `url`.
**Body shapes accepted (pick one):**
1. Canonical nested — `{ "person": { … }, "source_reference": { … } }`.
2. Friendlier nested — same as above but `source` or `citation` instead of
`source_reference`; inside the citation, `category` is accepted for `source_category`.
3. Flat top-level — omit the `person:` wrapper and send profile fields at the top of the
body. Combine with `source: { … }` for the citation.
**Nested collections:** you may use Rails-style `name_aliases_attributes` /
`email_addresses_attributes`, or send the friendlier `aliases` / `emails` arrays. Arrays
can contain strings (`"Ada L"`, `"ada@example.com"`) or objects (`{ "name": "Ada L" }`,
`{ "address": "ada@example.com", "verified_at": "…" }`).
For the common "add a person (optionally under an organization)" case, prefer
`POST /api/v1/people/quick_add` — it takes a flat body and only requires
`first_name`, `last_name`, and `source_url`.
Requires an API key with `can_edit`. Costs one credit.
Try & reference
- Open in Swagger UI — this path is pre-selected; use Authorize with your API key.
- People playground — labelled form fields for this resource's most common actions.
- Full-surface playground — send any method to any path.
- OpenAPI YAML — full machine-readable specification.
Quick answers
- How do I call this endpoint?
-
Send
POST /api/v1/peopleto your deployment’s host withAuthorization: BearerorX-Api-Keyset to your API key. - Where can I try it interactively?
- Use Swagger UI (Authorize with your key) or the API playground.