Docs
API referencePeople

Create a person

Preview· P9
POST/people

Adds a host or employee to your directory. Give an email address or a phone number (or both) so Agoo can notify them when visitors arrive: with neither, the request returns validation_failed at body.email and body.phone.

  • Fires person.created.
  • Counts towards your plan's host and attendance limits. Going over a limit returns plan_required.
  • Returns conflict if another person already uses the email address.

Scope: people:write · Plan: Pro and Enterprise in live mode; every plan in test mode.

Authorization

AuthorizationBearer <token>

Send Authorization: Bearer <token> on every request. The token is one of:

PrefixWhat it isWhere it may be used
agoo_sk_live_Secret key, live modeYour servers only
agoo_sk_test_Secret key, test modeYour servers only
agoo_pk_live_Publishable key, live modeBrowsers and apps: create pre-registrations and bookings, read public booking types (with their intake questions) and their free slots, read the visit types open for pre-registration with their public forms. Never lists people.
agoo_pk_test_Publishable key, test modeAs above, in test mode

Admins create keys in Console → Developers → API keys and choose each key's scopes. A key is shown once. Never put a secret key in a URL, a browser or a mobile app.

In: header

Scope: people:write

Header Parameters

Idempotency-Key*string

A UUID you generate for this operation. If you retry with the same key within 24 hours, Agoo returns the original response instead of acting twice. While the first request is still running, a retry returns conflict. Reusing a key with a different request returns idempotency_key_reused. Responses with rate_limited, internal_error or unavailable aren't stored, so retry those with the same key.

Formatuuid

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

A new host or employee. Give an email address, a phone number or both.

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X POST "https://example.com/people" \  -H "Idempotency-Key: 3f6b2a1e-8c4d-4f7a-9b2e-5d1c0a7e9f64" \  -H "Content-Type: application/json" \  -d '{    "name": "Nii Armah",    "email": "nii.armah@voltabank.example",    "job_title": "Operations officer",    "department": "Operations",    "employee_number": "VB-0217",    "site_ids": [      "site_01kjpt3yw0fz0v414608h9x65s"    ],    "can_host": true,    "tracks_attendance": true,    "custom_fields": {}  }'
{  "id": "person_01kjw4mg80efgb5aqbsqnxhtbh",  "name": "Nii Armah",  "email": "nii.armah@voltabank.example",  "phone": null,  "job_title": "Operations officer",  "department": "Operations",  "employee_number": "VB-0217",  "site_ids": [    "site_01kjpt3yw0fz0v414608h9x65s"  ],  "can_host": true,  "tracks_attendance": true,  "status": "active",  "custom_fields": {},  "created_at": "2026-03-04T10:00:00Z",  "updated_at": "2026-03-04T10:00:00Z",  "deactivated_at": null}

List people GET

Returns the hosts and employees in your directory, newest first. Filter by name, email, site or status, for example to find the `host_id` for an invitation. **Scope:** `people:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.

Get a person GET

Returns one host or employee, including deactivated people. **Scope:** `people:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.