API Overview

The OnboardingHub API is a RESTful JSON API that lets you programmatically manage contacts, organisations, enrollments, guides, and webhook endpoints within your workspace.

Interactive reference: The full API specification with request/response schemas and a built-in "Try it out" tool lives at the interactive API reference. This page is a narrative overview -- use the interactive reference for endpoint-level details.

Base URL

All API endpoints are available at:

https://onboarding-hub.com/api/v1/

Authentication

Every request must include an Authorization header with a Bearer token:

Authorization: Bearer YOUR_API_KEY

There are two ways to get a token:

API keys -- create a key in your workspace under Integrations → API Keys and paste it directly into the Authorization header. The key itself is the Bearer token -- no token exchange required.
OAuth 2.0 authorization code grant -- for third-party applications that act on behalf of a user. See Authentication in the API reference.

Scopes

API keys and OAuth tokens are granted specific scopes that limit which endpoints they can call:

Scope	Grants access to
`contacts:read`	List and view contacts
`contacts:write`	Create, update, and delete contacts
`organisations:read`	List and view organisations
`organisations:write`	Create, update, and delete organisations
`enrollments:read`	List and view enrollments
`enrollments:write`	Create, update, and delete enrollments
`guides:read`	List and view published guides
`webhooks:manage`	Full CRUD on webhook endpoints

Quick start

curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://onboarding-hub.com/api/v1/contacts

Available endpoints

Resource	Operations	Required scopes
Contacts	List, Get, Create, Update, Delete, Search	`contacts:read`, `contacts:write`
Organisations	List, Get, Create, Update, Delete	`organisations:read`, `organisations:write`
Enrollments	List, Get, Create, Update, Delete	`enrollments:read`, `enrollments:write`
Guides	List, Get (read-only)	`guides:read`
Webhook Endpoints	List, Get, Create, Update, Delete, Test	`webhooks:manage`

Rate limits

All authenticated API requests are rate-limited:

60 requests per minute per token
500 requests per hour per token

Every response includes the following headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests in the current window
`X-RateLimit-Remaining`	Requests remaining in the current window
`X-RateLimit-Reset`	Unix timestamp when the window resets

When you exceed a limit you will receive a 429 Too Many Requests response with a Retry-After header.

Error format

All errors use a consistent JSON envelope:

{
  "error": {
    "type": "not_found",
    "message": "Couldn't find Contact with id=..."
  }
}

Validation errors include field-level detail:

{
  "error": {
    "type": "validation_error",
    "message": "Email has already been taken",
    "errors": {
      "email": ["has already been taken"]
    }
  }
}

Common error types: authentication_required, invalid_token, token_expired, insufficient_scope, forbidden, not_found, validation_error, rate_limited.

Pagination

List endpoints support page-based pagination via page and per_page query parameters. Pagination metadata is returned in response headers:

Header	Description
`X-Total-Count`	Total matching records
`Link`	RFC 5988 pagination links (first, prev, next, last)

SDKs and integrations

Zapier -- connect OnboardingHub to thousands of apps. See Zapier Integration.
n8n -- self-hosted automation with the OnboardingHub community node. See n8n Integration.
MCP -- let AI assistants manage your workspace. See MCP Integration.
Webhooks -- receive real-time notifications when events happen. See Webhooks.