API reference
Every endpoint and webhook event of the Agoo REST API, generated from the OpenAPI 3.1 contract.
This is a published preview. Names and fields may still change before general availability; changes will be listed in the changelog.
The Agoo REST API lets your own systems work with your organisation's front door: invite visitors and check them in, sync your staff directory, take bookings, record clock-ins from your own terminals, start roll calls and receive events as they happen.
This reference is generated from the API's OpenAPI 3.1 contract, version 1.0.0-preview. The API ships in phase P9; until general availability, names and fields may still change, and every change is listed in the changelog.
Base URL and authentication
https://api.agoo.ardent.africa/v1Live and test mode share the base URL; the key you send decides which one you're in. Authenticate every request with a bearer token in the Authorization header: a secret API key (agoo_sk_live_… or agoo_sk_test_…), a publishable key (agoo_pk_…) for the few browser-safe calls, or an OAuth 2.1 access token. See authentication.
The API speaks JSON over HTTPS (TLS 1.2 or later). Send Content-Type: application/json with every request body.
Your first request
With a test key in AGOO_API_KEY, ask which organisation and mode the key belongs to (scope organisation:read):
curl https://api.agoo.ardent.africa/v1/organisation \
-H "Authorization: Bearer $AGOO_API_KEY"{
"id": "org_01kjpsrza0etzb0a4vf72x8ang",
"name": "Volta Bank",
"slug": "voltabank",
"plan": "pro",
"country": "GH",
"time_zone": "Africa/Accra",
"wallet_balance": { "amount": 29900, "currency": "GHS" },
"livemode": false,
"created_at": "2026-03-02T08:14:00Z"
}For a guided tour that invites a visitor and receives a webhook, follow make your first API call.
Conventions
Every endpoint follows the same rules.
| Topic | In short | Details |
|---|---|---|
| Test mode | _test_ keys work on a sandbox copy of your organisation. No messages are sent; nothing is billed. | Environments |
| IDs | TypeIDs with a type prefix, such as visit_01m4k5z4j0fxbte6sn6e8tpgza | IDs, objects and formats |
| Timestamps | RFC 3339 in UTC, such as 2026-10-14T09:30:00Z. Sites carry an IANA time zone. | IDs, objects and formats |
| Phone numbers | E.164, such as +233241234567 | IDs, objects and formats |
| Money | Integer minor units and a currency: { "amount": 29900, "currency": "GHS" } is GH₵299.00 | IDs, objects and formats |
| Lists | limit (1–100, default 25) and cursor; responses have data, next_cursor and has_more | Pagination |
| Errors | RFC 9457 problem details with a stable code, such as validation_failed | Errors |
| Retries | Send an Idempotency-Key UUID with every POST; keys last 24 hours | Idempotency |
| Rate limits | Per organisation and mode; RateLimit-* headers; 429 with Retry-After | Rate limits |
| Request IDs | Every response has an Agoo-Request-Id header. Quote it to support. | Errors |
| Versioning | /v1 in the path; additive changes ship without notice, so ignore unknown fields | Versioning |
| Custom fields | Each organisation's own fields, in custom_fields, defined by JSON Schemas from GET /forms; one form per visit type (GET /visit-types), with a public_form for types open for pre-registration | Custom fields |
| Webhooks | Signed with Standard Webhooks; retried for about 27 hours | Webhooks |
Plan access
| Plan | Live mode | Test mode | Live rate limit |
|---|---|---|---|
| Free, Starter | No API access | Every endpoint | – |
| Growth | Webhook endpoints and events only | Every endpoint | 100 requests a minute |
| Pro | The full REST API, OAuth apps and the MCP server | Every endpoint | 600 requests a minute |
| Enterprise | Everything in Pro, with custom scopes and IP allow-lists | Every endpoint | 3,000 requests a minute, can be raised |
Website embeds. The embed script and the WordPress plugin's blocks work on every plan that has booking pages, because they show your hosted pages from app.agoo.ardent.africa in a frame. The React components call the API directly, so in live mode they need Pro or Enterprise; in test mode they work on every plan.
Test mode is limited to 100 requests a minute on every plan. A live call your plan doesn't include returns plan_required. Each endpoint's description states the scope and plan it needs. See plans and limits for the rest of each plan.
Plan history. In live mode, your plan's visitor history (up to 5 years on Pro, as agreed on Enterprise) decides which visits and visitor records the API shows, and its audit-trail period which audit events. Moving to a lower plan never deletes data: older records are kept, hidden, and come back when you move up. Lists leave them out, and reading or acting on one by ID returns plan_required, not not_found. Visits that are still expected, awaiting approval or checked in are never hidden, and erasing a visitor covers hidden records too.
Publishable keys can read the visit types open for pre-registration, with their public forms, and create pre-registrations and bookings. See authentication.
How this reference is organised
Endpoints are grouped by resource, in the sidebar and below. Each page shows the scope it needs, its parameters and request body, every response with an example, and the code to call it.
| Resource | What it covers |
|---|---|
| Organisation | The organisation your key belongs to, its plan and mode |
| Sites | Locations, with their gates and paired kiosks |
| People | Hosts and employees: create, update, deactivate |
| Visits | Invitations and walk-ins: check in, check out, approve, deny, cancel, resend passes |
| Visitors | Visitor records across visits, and erasure under Act 843 |
| Deliveries | Parcels received at reception and collected |
| Bookings | Booking types, free slots, and bookings: create, confirm, decline, reschedule, cancel |
| Attendance | Clock-ins and clock-outs, daily summaries and shifts |
| Watchlist | People your security team wants to know about |
| Roll calls | Emergency and drill roll calls |
| Webhooks | Webhook endpoints: create, update, rotate secrets, send test events |
| Events | Events, redelivery, and the payload of each of the 29 event types |
| Audit | The hash-chained audit trail |
| Forms | Your visit types, built-in and your own, the JSON Schemas behind your custom fields, and the public forms for pre-registration |
| Files | Photos, ID images, signatures, selfies and documents: register an upload, check its status, get a short-lived download link |
The OpenAPI document
Download the contract from docs.agoo.ardent.africa/openapi.yaml. Once the API is live it will also be served at https://api.agoo.ardent.africa/v1/openapi.json. Use it to generate a client in any language with an OpenAPI generator, import it into an API tool, or check your integration against it in CI. Official SDKs for TypeScript, PHP, Python and Go, generated from the same document, are planned.