Skip to main content

REST API & webhooks

Do from your own code what the app does — create workers, run checks, read compliance state — and get pushed an event the moment a result changes.

Who it's for: Developers building an integration on top of Oho

Availability: Available

What you get​

  • Create and update workers, credentials, applicants, and fetch requests over a REST API
  • Look a resource up by your own upstream ID, so you don't have to keep a map of Oho IDs
  • Subscribe to events and stop polling — deliveries are signed, retried, and replayable
  • Trace any call end to end with a request ID you can quote in a support ticket
  • Try any endpoint from the reference before you write a line of code

Turn it on​

→ API Basics — base URLs, the Authorization header, ID shapes, the response envelope, and the error shapes every endpoint relies on.

How it works​

Requests carry a bearer token generated from Settings → Access Tokens, authorised per entity type, against a per-tenant base URL. Resources are addressed by prefixed synthetic IDs the server mints (wkr_, cred_, app_); reads and writes return a data object with a meta companion, and DELETE is a soft delete that preserves the record and its history. For events, you give Oho an endpoint and the event types you care about, and Oho POSTs each matching event to you, signed.

→ Webhooks — the plain-language version of what Oho sends and when → API Reference — every endpoint, field, and query parameter

For developers

The full technical detail, in the order you'll need it:

→ Authentication & tokens · Errors, retries & idempotency · Pagination, filtering & sorting → Workers & credentials · Fetch Requests · Screening an applicant · Bulk import → Webhooks & event delivery — subscribing, signature verification, retries, replay, and the recovery runbook

Good to know​

  • Subscribable events cover the credential lifecycle (credential.added, credential.verified, credential.linked, and more) plus recruitmentCheck.completed and fetchRequest.completed. Exact types and wildcards are validated against a live catalogue at subscription time.
  • Every delivery is signed with an X-Oho-Signature header. Verify it against the raw request bytes, dedupe on the delivery ID, and return 200 quickly.
  • Retries are exponential and capped at six attempts by default, both configurable per subscription. A subscription auto-disables after 50 consecutive failures, and failed deliveries can be replayed once your endpoint is healthy again.
  • pageSize defaults to 25 and is capped at 100, so reporting queries page rather than pull a whole workforce at once.
  • Production is served per tenant — https://<tenant>.weareoho.com/openapi/v1, with staging available separately.
  • Outbound webhooks (Oho to you) are a separate surface from the inbound one police-check providers use to POST status updates to Oho. See Webhooks & event delivery.
  • Prefer not to write code? A connector may already cover it — see HRIS & payroll integrations.