Docs
API referenceVisits

Check a visitor in

Preview· P9
POST/visits/{visit_id}/check-in

Checks in the visitor on an expected visit, for example from your own gate system or reception desk. To record a walk-in from your own system, create the visit first, then check it in.

  • If the site's rules need host approval, and the host hasn't approved the visit ahead of time, the visit moves to awaiting_approval, the host is asked and visit.approval_requested fires. Approving the visit then checks the visitor in.
  • Otherwise the visit moves to checked_in, the host is told their visitor has arrived and visit.checked_in fires.
  • The watchlist is checked just as it is at the kiosk. A match holds the check-in for security (awaiting_approval), fires watchlist.matched and alerts the site's security leads. The host isn't told.
  • A visit already held for security when it was created records that the visitor has arrived, alerts security and stays awaiting_approval.
  • Any other status returns invalid_state.

Scope: visits: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: visits:write

Path Parameters

visit_id*string

The visit's ID.

Match^visit_[0-7][0-9a-hjkmnp-tv-z]{25}$
Example"visit_01m4k5z4j0fxbte6sn6e8tpgza"

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.

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

application/problem+json

curl -X POST "https://example.com/visits/visit_01m4k5z4j0fxbte6sn6e8tpgza/check-in" \  -H "Idempotency-Key: 3f6b2a1e-8c4d-4f7a-9b2e-5d1c0a7e9f64" \  -H "Content-Type: application/json" \  -d '{    "gate_id": "gate_01kjpt7m20fpf9vcsaexsxgqr3"  }'

{  "id": "visit_01m4k5z4j0fxbte6sn6e8tpgza",  "status": "checked_in",  "type": "meeting",  "source": "invitation",  "site_id": "site_01kjpt3yw0fz0v414608h9x65s",  "gate_id": "gate_01kjpt7m20fpf9vcsaexsxgqr3",  "host_id": "person_01kjsesxm0e4zbyvkr7bcfxbfg",  "visitor": {    "id": "visitor_01krdtb870fxj8t6ntdtcxwdk5",    "name": "Ama Owusu",    "phone": "+233241234567",    "email": "ama@coastline.example",    "company": "Coastline Consult"  },  "purpose": "Quarterly treasury review",  "expected_at": "2026-10-14T09:30:00Z",  "expected_until": "2026-10-14T11:30:00Z",  "checked_in_at": "2026-10-14T09:31:02Z",  "checked_out_at": null,  "cancelled_at": null,  "decision": null,  "booking_id": null,  "pass": {    "channels": [      "whatsapp"    ],    "last_sent_at": "2026-10-10T15:12:44Z"  },  "custom_fields": {    "vehicle_plate": "GR 4521-24",    "bringing_laptop": true  },  "created_at": "2026-10-10T15:12:40Z",  "updated_at": "2026-10-14T09:31:02Z"}

Update a visit PATCH

Changes a visit's details. Send only the fields you want to change. `custom_fields` are merged key by key, and a key set to `null` is removed. - `site_id`, `host_id`, `type`, `expected_at` and `expected_until` can change only while the visit is `expected`. A new `type` must be turned on for your organisation, and the visit's `custom_fields` must fit that type's form. - `purpose` and `custom_fields` can change while the visit is `expected`, `awaiting_approval` or `checked_in`. - Visits that have ended (`checked_out`, `denied`, `cancelled`, `no_show`) can't change (`invalid_state`). - Fires `visit.updated`. Agoo doesn't message the visitor about the change; call `POST /visits/{visit_id}/resend-pass` to send them an updated pass. **Scope:** `visits:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.

Check a visitor out POST

Checks out the visitor on a `checked_in` visit and fires `visit.checked_out`. Any other status returns `invalid_state`. **Scope:** `visits:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.