REST API Basics

This article covers the conventions shared by every BusinessHRM REST API endpoint: the base URL, authentication, request and response format, and the query parameters for pagination, choosing fields, sorting and filtering. For the full list of endpoints and live examples, use the interactive docs at https://app.businesshrm.com/developers.

Base URL

https://app.businesshrm.com/api/v1

Every endpoint is appended to this base — for example GET https://app.businesshrm.com/api/v1/contact.

Note: If your workspace uses a custom subdomain, use that host instead (for example https://acme.businesshrm.com/api/v1).

Authentication

All requests must include an API key as a Bearer token in the Authorization header:

curl https://app.businesshrm.com/api/v1/contact \
  -H "Authorization: Bearer YOUR_API_KEY"

The key determines which workspace the request runs against and what it can do (see API Keys). Requests without a valid key, or to a resource the key isn't scoped for, are rejected.

Request and response format

Responses are JSON.
For POST/PUT requests, send a JSON body and set Content-Type: application/json (form-encoded bodies are also accepted).
List endpoints return an array of records plus pagination details; single-record endpoints return one object.

Pagination

List endpoints are paginated. Control the page window with:

Parameter	Meaning	Example
`limit`	How many records to return per page.	`limit=25`
`offset`	How many records to skip before returning results.	`offset=50`

# Records 51–75
curl "https://app.businesshrm.com/api/v1/contact?limit=25&offset=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Choosing fields

Ask for only the fields you need with the fields parameter (comma-separated). This makes responses smaller and faster.

curl "https://app.businesshrm.com/api/v1/contact?fields=id,name,email" \
  -H "Authorization: Bearer YOUR_API_KEY"

Sorting

Use order to sort results. Prefix a field with - for descending order.

# Newest contacts first
curl "https://app.businesshrm.com/api/v1/contact?order=-created_at" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filtering

Use the filters parameter to return only matching records. Each filter names a field, an operator, and a value. Common operators:

Operator	Meaning
`eq`	Equals
`ne`	Not equal
`gt`	Greater than
`gte`	Greater than or equal
`lt`	Less than
`lte`	Less than or equal
`lk`	Like (partial / contains match)
`in`	Matches any value in a list

# Contacts whose name contains "acme"
curl "https://app.businesshrm.com/api/v1/contact?filters[name][lk]=acme" \
  -H "Authorization: Bearer YOUR_API_KEY"

Tip: Combine filters, order, fields, limit and offset in a single request to fetch exactly the slice of data you need. The interactive docs show which filters each endpoint supports.

Error codes

The API uses standard HTTP status codes:

Status	Meaning	What to do
`200`	Success	Request succeeded.
`201`	Created	A new record was created.
`400`	Bad request	Check your parameters or JSON body.
`401`	Unauthorized	Missing or invalid API key.
`403`	Forbidden	The key is valid but not allowed to access this resource (check its permissions).
`404`	Not found	The endpoint or record doesn't exist.
`422`	Validation error	One or more fields failed validation; the response body lists the problems.
`429`	Too many requests	You're being rate-limited; slow down and retry.
`500`	Server error	Something went wrong on our side; retry later.

Error responses include a JSON body with a message (and, for 422, per-field validation details) to help you diagnose the problem.

Explore everything

The base conventions above apply across the API, but each resource has its own fields and filters. Browse them — and run live test calls — in the interactive documentation at https://app.businesshrm.com/developers, or import /developers/openapi.json into your own tools.