Docs
API referenceVisits

Update a visit

Preview· P9
PATCH/visits/{visit_id}

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.

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"

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

The fields to change. Which fields can change depends on the visit's status.

Properties1 <= properties

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 PATCH "https://example.com/visits/visit_01m4k5z4j0fxbte6sn6e8tpgza" \  -H "Content-Type: application/json" \  -d '{    "expected_at": "2026-10-14T10:00:00Z",    "expected_until": "2026-10-14T12:00:00Z",    "custom_fields": {      "bringing_laptop": null    }  }'
{  "id": "visit_01m4k5z4j0fxbte6sn6e8tpgza",  "status": "expected",  "type": "meeting",  "source": "invitation",  "site_id": "site_01kjpt3yw0fz0v414608h9x65s",  "gate_id": null,  "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-14T10:00:00Z",  "expected_until": "2026-10-14T12:00:00Z",  "checked_in_at": null,  "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"  },  "created_at": "2026-10-10T15:12:40Z",  "updated_at": "2026-10-13T16:20:05Z"}

Get a visit GET

Returns one visit with its visitor, status and timestamps. In live mode, a visit created before your plan's visitor history returns `plan_required`, and so does any action on it. It's kept, not deleted, and comes back if you move to a plan with a longer history. **Scope:** `visits:read` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.

Check a visitor in POST

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.