Docs
API referenceVisits

Approve a visit

Preview· P9
POST/visits/{visit_id}/approve

Approves a visit that is awaiting_approval. What happens depends on whether the visitor has arrived:

  • On site (they checked in and the host must approve, or they walked in): the visitor is checked in. Fires visit.approved and then visit.checked_in. Reception sees the decision straight away.
  • Not arrived yet (a pre-registration waiting for the host): the visit is approved ahead of time. It goes back to expected with the decision, nobody is checked in, and Agoo sends the visitor their QR pass with the news. Fires visit.approved, then pass.sent once the pass is sent. When they arrive, checking in doesn't ask the host again.

A visit held by a watchlist match returns invalid_state until your security team resolves the match.

With an OAuth token, decision.decided_by is the signed-in person; with an API key it is null and the key is recorded in the audit trail. 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

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/visits/visit_01m4k5z4j0fxbte6sn6e8tpgza/approve" \  -H "Idempotency-Key: 3f6b2a1e-8c4d-4f7a-9b2e-5d1c0a7e9f64"

{  "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": {    "outcome": "approved",    "decided_at": "2026-10-14T09:31:02Z",    "decided_by": "person_01kjsesxm0e4zbyvkr7bcfxbfg",    "reason": 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"}

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.

Deny a visit POST

Denies a visit that is `awaiting_approval` and fires `visit.denied`. Reception is told straight away. A visitor who hasn't arrived yet (a pre-registration) is told the visit can't go ahead. The optional reason is stored on the visit for reception and the audit trail; Agoo doesn't send it to the visitor. Any other status returns `invalid_state`. **Scope:** `visits:write` · **Plan:** Pro and Enterprise in live mode; every plan in test mode.