What is an API? Definition, examples and a call you can run

API definition: a contract between two programs

An API (application programming interface) is the set of requests one program agrees to accept from another, and the answers it promises to give back. The word "interface" is the important one: an API hides how a system works and exposes only how to use it. You do not need to know how a registry search is built to send a name and get a list of matches; the API is the agreement that makes that possible.

On the web, an API is usually a set of HTTP endpoints that take and return JSON. A program sends a request to a URL with a method, headers and a body; the server answers with a status code and a body. That is what people mean by a "web API" or "REST API", and it is what this page is about. (Operating systems, libraries and browsers also have APIs — the fetch function in a browser is one — but the word on this page means the web kind unless it says otherwise.)

An API example you can run right now

Definitions stick when you run one. This is one call to the OffenderSearch background check API: it sends a person's name and date of birth and gets back the people on 58 US sex offender registries who match. The sandbox host is free and the test name Exact Match always returns one verified person, so you will see exactly this.

curl -X POST https://sandbox.offendersearch.app/v1/search \
  -H "X-API-Key: $OFFENDERSEARCH_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": {"firstName": "Exact", "lastName": "Match", "dob": "1980-01-01"}}'

# → {"status": "complete", "counts": {"records": 1, …}, "records": [{"matchState": "dob_match", …}]}

Everything in that call has a name, and every name is defined below: the endpoint (POST /v1/search), the header (X-API-Key), the request body (the JSON after -d), the response (the JSON after the arrow), the status and the records. The full walkthrough, with Python and Node versions, is the RESTful API example. A free test key takes a minute at /sign-up.

API: how it works, in four steps

1. The client builds a request. A method (POST), a URL (https://sandbox.offendersearch.app/v1/search), headers (who you are, what format you send) and a body (the question).
2. The server authenticates and validates. It checks the key, then checks the body against the schema. A bad key is a 401; a bad body is a 422 that names the field.
3. The server does the work. Here, it searches the continuously updated registry store, scores each candidate against the name and date of birth, and assembles the answer.
4. The server responds. A status code (200) and a JSON body: the search id, whether it is complete, the counts, and the records. The client reads the fields it needs and moves on.

When step 3 takes longer than a request should wait, the API answers 202 with an id to poll, or calls you back with a webhook. That branch is the subject of webhooks vs API polling.

Types of API: REST, webhook, MCP, SDK and more

API glossary: the request

API endpoint

A method and a URL that together name one operation: POST /v1/search, GET /v1/searches/{searchId}. "Endpoint" is also used loosely for the URL alone. The RESTful API example takes one apart piece by piece.

API base URL

The scheme and host every endpoint path is appended to. Here there are two: https://api.offendersearch.app for live keys and https://sandbox.offendersearch.app for test keys. Paths are identical on both. See sandbox and production.

API request

One HTTP message from client to server: method, URL, headers and (optionally) a body. A request is stateless — it carries everything the server needs, including the credential.

API request body (payload)

The data sent with a POST, PUT or PATCH, as JSON. "Payload" means the same thing. On this API the body is {"query": {"firstName", "lastName", "dob", …}}; the request body section lists every field.

API header

A name/value pair sent before the body. The ones you set here: X-API-Key (who you are), Content-Type: application/json (what the body is). The ones you read: Retry-After on a 429, X-Offendersearch-Signature on a webhook.

API method (HTTP verb)

GET reads, POST creates, PUT replaces, PATCH edits, DELETE removes. Safe methods (GET) change nothing; idempotent methods (GET, PUT, DELETE) can be repeated without a different outcome; POST is neither.

API parameter

An input to an endpoint. Path parameters sit in the URL (/v1/monitors/{monitorId}), query parameters after ?, body parameters in the JSON. Sensitive inputs — a person's name and birth date — belong in the body, never the URL.

Query string

The ?key=value&key2=value2 part of a URL. Fine for paging and filters on a GET; wrong for anything private, because URLs land in logs, histories and referrer headers.

API resource

A thing with an identity that the API lets you act on: a search, a record, a monitor, an order. Resources have URLs; collections of them have URLs too (/v1/monitors).

API route

The server-side name for the path pattern an endpoint matches, such as /v1/searches/{searchId}. Clients say endpoint; frameworks say route.

API version

A prefix (/v1) or header that pins the contract you integrated against. A breaking change ships as a new version; the old one keeps working. See requests and responses.

Content type

The Content-Type header names the format of a body: application/json for JSON, application/pdf for a report. Send it on every request that has a body, and read it on responses that might not be JSON.

Request id

An identifier the server attaches to each request so a support conversation can find it. On this API the created resource's id (searchId) plays that role; keep it.

Idempotency

A request is idempotent when sending it twice has the same effect as once. GET and DELETE are; POST /v1/search is not — two posts are two searches. This API reads no idempotency header, so make retries safe by persisting the id from the first acknowledgement. See async jobs.

API glossary: the response

API response

The HTTP message back: a status code, headers and a body. On this API the body of a successful search is a JSON envelope — metadata first (searchId, status, counts), data last (records[]). See the response example.

Status code

The three-digit number that classifies the response. 2xx success, 4xx your request was wrong, 5xx the server failed. The codes this API uses, and which to retry, are in API errors.

API error

A non-2xx response with a JSON body that says why: a detail list naming each bad field on a 422, an object with a code on a refusal, retryAfterSeconds on a 429. Branch on codes, never on sentences.

Response envelope

A wrapper object around the data that carries metadata about the answer: whether it is complete, how many items there are, which sources finished. The envelope is why an empty records[] is only "no match" when status is complete.

API schema

The formal description of every request and response shape: field names, types, which are required, allowed values. Published here as an OpenAPI document, which generates the SDKs, the Postman collection and the reference pages.

OpenAPI (Swagger)

The standard format for an API schema, a YAML or JSON file that tools can read. "Swagger" is the older name and the name of the tooling that renders it. The API documentation example shows how the schema becomes docs.

JSON

JavaScript Object Notation: the text format for objects, arrays, strings, numbers, booleans and null that nearly every web API speaks. A "JSON API" is just an API whose bodies are JSON.

Pagination

Returning a long list in pages. A GET takes limit and a cursor or after id and the response says how to fetch the next page. Alerts and FCRA events page this way; a person search does not need to.

Null vs missing vs empty

Three different facts: a field that is null (known to be absent), a field that is not present (not reported), and an empty string or array (reported, and empty). The data model rules say which the API uses where.

Match confidence

This API's 0–1 score for how strongly a returned record is the person you asked about, with matchBasis[] listing the fields that agreed and matchState giving the date-of-birth verdict. Specific to this API, but every data API has an equivalent you must read before trusting a row. See matching.

API glossary: authentication and keys

API key

A secret string that identifies the caller. Sent on every request in the X-API-Key header here. Keys have prefixes that say what they are for: os_live_… for production, os_test_… for the sandbox. The API token example covers creating, scoping, rotating and revoking one.

API token

Often used interchangeably with API key. Strictly, a token is any bearer credential, including short-lived ones issued by OAuth; a key is a long-lived one you create in a dashboard.

Access token

A short-lived credential issued by an authorization server (OAuth) that a client presents to an API. This API does not issue access tokens; it uses keys. The difference is explained in API key vs OAuth.

Bearer authentication

Sending a credential in Authorization: Bearer <token>. This API uses a dedicated X-API-Key header instead, which keeps the key out of generic proxy logging rules that treat Authorization specially.

OAuth 2.0

A protocol for letting a user grant an app limited access to their data on another service, and for machine-to-machine tokens (client credentials). Right when a user is delegating; unnecessary when your server calls a data API with its own account.

Client credentials

The OAuth flow for machine-to-machine access: a client id and secret are exchanged for a short-lived access token. The middle ground between an API key and a full user login.

API secret / client secret

The private half of a credential pair. Never in a browser, never in a repository, never in a URL. Store it in an environment variable or a secrets manager.

Key rotation

Creating a new key, moving traffic to it, and revoking the old one — on a schedule, and immediately after any suspected leak. The dashboard supports it; the authentication page describes the lifecycle.

Scope

What a credential is allowed to do. A test key is scoped to the sandbox host; an organisation credential can be limited to products. Least privilege: give a key only what the integration needs.

API signature

An HMAC computed over a request or webhook body with a shared secret, so the receiver can prove who sent it and that it was not altered. This API signs webhooks with X-Offendersearch-Signature: t=<unix>,v1=<hex>. See API signature.

HMAC

Hash-based message authentication code: a hash (SHA-256) keyed with a secret. The standard way to sign webhooks and some requests. Verify with a constant-time comparison.

TLS / HTTPS

The encryption every API request must travel under. An API that accepts a key over plain http:// has leaked it. Both hosts here are HTTPS only.

API glossary: webhooks, async and delivery

Webhook

An HTTP request the API sends to *your* URL when something happens — a monitor finds a change, an FCRA order completes. The reverse of a normal API call. Webhooks vs API polling explains when to use one; the webhook example shows receiving one.

Webhook URL (endpoint)

The HTTPS address on your server that receives webhook POSTs. You give it to the API (channels.webhookUrl when creating a monitor); the API calls it. Test one with the webhook tester.

Webhook secret

The shared secret used to sign deliveries to one webhook URL, shown once when the endpoint is registered (whsec_…). Keep it with your other secrets; rotate it from the API.

Event

A named thing that happened, with an id, a type and a timestamp: monitor.change_found, order.completed. Webhook bodies carry events; polling endpoints list them.

Polling

Asking repeatedly whether something is done: GET /v1/searches/{searchId} every few seconds until status is complete. Simple and reliable; wasteful at scale, which is what webhooks fix.

Asynchronous (async) API

An endpoint that accepts work and finishes it later. It answers 202 Accepted with an id and a path to poll, instead of holding the connection open. See async jobs and webhooks.

202 Accepted

The status code that means "I have your request; the result is not ready." Always comes with an id. Persist the id before doing anything else.

At-least-once delivery

A webhook may be delivered more than once (after a timeout, the sender retries). Key your processing on the event id so a duplicate is harmless.

Retry with backoff

Waiting longer between each retry (1 s, 2 s, 4 s…) so a struggling server is not hammered. When the server sends Retry-After, use that number instead of guessing.

Replay attack

Re-sending a captured, validly signed webhook later. Defeated by putting a timestamp inside the signed text (t=…) and refusing deliveries older than a tolerance window.

Batch API

An endpoint that takes many items in one request (a list of names) and processes them as one asynchronous job. See batch.

API glossary: limits, environments and operations

Rate limit

The number of requests a caller may make per window. Exceeding it returns 429 Too Many Requests with Retry-After. The sandbox allows 60 a minute and 2,000 a day per test key; the live host limits per account and tells you the wait in the header.

429 Too Many Requests

The rate-limit status. Nothing was processed or billed. Wait the seconds in Retry-After, then retry the identical request.

Throttling

Slowing a caller down rather than refusing outright — queuing briefly before answering. This API queues for a short time before it returns a 429.

Quota

A longer-window limit (per day, per month), often tied to a plan. Distinct from a per-second rate limit; both answer 429.

Sandbox

A separate host that accepts test keys, answers with the production response shape from fixed test data, and bills nothing. The place to build and test an integration. Public API for testing describes this one.

Environment

Which host and key you are talking to: sandbox or production (live). Same paths and shapes; different data and billing. See sandbox and production.

Test key vs live key

os_test_… keys work only on the sandbox and are never billed; os_live_… keys work only on the live host and are. Sending one to the other host is a 401, by design.

Mock API / dummy API

A fake server that returns canned responses so you can build before the real API is ready. A sandbox is the stronger version: the real server, real shapes, fixed data. See free and public APIs.

API gateway

A front door that routes requests to services and enforces keys, rate limits and logging in one place. You see it as the thing that answers a 429 before your request reaches the service.

Latency

How long a request takes end to end. The response reports its own server time in elapsedMs; a sandbox search answers in well under a second, a live search that re-checks many sources may go asynchronous.

Timeout

How long a client waits before giving up. Set one on every call (60 s is a sane default for a search). A timed-out POST may still have succeeded — recover by GET, not by resending.

Uptime / status page

The published availability of an API. Check it before concluding your integration is broken; see operations.

Metering / usage

How an API counts what you did for billing. Here, a live-host search is one billable call; live re-checks and documents are itemised in meterEvents[]; the dashboard shows usage. The sandbox meters nothing.

Pay per call

Pricing where each billable request costs a fixed amount with no subscription — $0.15 a call on this API, with 25 free calls at sign-up. Contrast with seat or report pricing. See API pricing.

API glossary: building, documenting and consuming APIs

API client

The code that calls an API: a thin object that owns the base URL, headers and error handling, with one method per endpoint. The RESTful API example builds one in 30 lines.

SDK (client library)

An API client published as a package in your language, with typed inputs and outputs. pip install offendersearch, npm i @offendersearch/sdk. Generated from the schema, so it matches the server. See SDKs.

CLI

A command-line program that wraps an API so you can call it from a terminal or a script: npx offendersearch search "Exact Match" --dob 1980-01-01.

API documentation

The human-readable contract: getting started, authentication, every endpoint with examples, errors, and a changelog. What good docs contain, with a worked teardown, is the subject of API documentation example.

API reference

The endpoint-by-endpoint part of the documentation: method, path, parameters, response schema, errors. Here: API reference.

Quickstart

The shortest path from zero to a successful call: key, host, one request, one response. Here: quickstart.

Postman collection

A file of saved, runnable requests for an API, importable into Postman or forked from a public workspace. Generated from the schema here; see Postman API documentation.

cURL

The command-line HTTP tool every API doc uses for examples, because it shows the literal request: method, headers, body. Every example on this site has a cURL tab.

API-first

Designing the API contract (the schema) before writing the server or the client, so both are built to the same agreement. The reason this site's SDKs, docs and Postman collection all come from one OpenAPI file.

Public API

An API anyone can sign up for and call, as opposed to a private or partner API. This one is public with a free sandbox. Directories of public APIs are listed in free and public APIs.

Data API

An API whose purpose is to return records about things — people, companies, places, products — rather than to perform actions in another app. A background check API is a data API.

Verification API

An API that answers a yes/no question about a claim — is this address real, does this name appear on a registry. The screening endpoints here are verification APIs over public records; they do not verify identity documents.

Search API

An endpoint that takes a query and returns ranked matches. POST /v1/search is one; the ranking is the matchConfidence order.

llms.txt / Markdown twin

A plain-text index of a site's documentation written for AI agents to read, plus a Markdown copy of each page. This site publishes both (/llms.txt, every page at .md), which is how a coding assistant can answer questions about the API accurately.

MCP (Model Context Protocol)

A standard for exposing an API as tools an AI assistant can call. The background check MCP server lets Claude or Cursor run a registry search as a tool call.

Changelog

The dated list of what changed in an API, including anything that could break a client. Read it before upgrading; here: changelog.

Deprecation

The announced retirement of an endpoint or field, with a date and a replacement. A well-run API deprecates loudly and keeps the old behaviour working until the date.

API limitations: what an API cannot tell you

An API can only answer within its contract. Three limits apply to every data API, and to this one in particular:

• It returns what the underlying records say, not more. A registry search returns people on sex offender registries; a criminal search returns public court, jail, prison and warrant records. Neither returns credit, driving, identity-document or international results, and the API never asks for a Social Security number.
• A match is a probability, not a fact. The score and the date-of-birth verdict are there to be read. A name-only match on a common name is weak evidence and the API labels it as such.
• Completeness is explicit. When a source did not answer, the envelope says so (status: "partial", sourceStatus[]). The API never pads an incomplete answer to look complete.

FAQ: what is an API, answered

What does API stand for?

Application programming interface. "Interface" is the operative word: how a program is used, not how it is built.

What is an API in simple words?

A menu of requests one program will accept from another, with a promise about what comes back. You send a question in an agreed format and get an answer in an agreed format.

What is an API used for?

Letting software use software: a hiring app checking a name against public records, a map showing registry pins, a monitoring job that tells you when something changes — each is a program calling an API rather than a person using a website.

What is the difference between an API and an endpoint?

The API is the whole contract; an endpoint is one operation in it (POST /v1/search). An API has many endpoints.

What is the difference between an API and a webhook?

With an API you call the server; with a webhook the server calls you. Both are HTTP. Webhooks vs API polling goes deeper.

Is an API free?

Many are free to try and paid to use at volume. This one has a free sandbox with no card and 25 free live calls at sign-up, then $0.15 a call. See free and public APIs for a list of genuinely free public data APIs.

Related

• Learn APIs by example (hub)
• RESTful API example — the call above, explained field by field
• API token example — keys, scopes, rotation
• API key vs OAuth — which credential when
• Webhooks vs API polling
• API errors — status codes and the error body
• API documentation example
• Free and public APIs
• Public API for testing — the free sandbox
• Background check API — the API used in every example
• Quickstart
• MCP server — the API as an AI tool