Conventions

Beta. This endpoint is not final. Field names and response shapes can change before general availability.

Base URL

Every request goes to one host:

https://api.hirefinn.ai/v1

The version lives in the path, not in a header. There is no unversioned root. A request to https://api.hirefinn.ai/agents without /v1 will not resolve to the current API.

All requests must use HTTPS. Plain HTTP requests are rejected rather than redirected, so a client that follows redirects will not silently retry over TLS.

Authentication

Send your API key as a bearer token on every request:

curl https://api.hirefinn.ai/v1/finns \
  -H "Authorization: Bearer $FINN_API_KEY"

Keys are scoped to one workspace. A key from one workspace cannot read or write another workspace's resources, and there is no account-level key that spans workspaces. See Authentication for how to create and rotate keys, and Errors for what a rejected key looks like.

Versioning

Write clients that ignore unknown fields. New response fields and new enum values arrive inside v1 without a version bump, so a client that validates strictly against a fixed schema will start failing on a change that is not breaking. In particular, treat status and outcome fields as open string sets, not closed enums.

Because this API is in beta, the table above describes the intended contract after general availability. During beta, breaking changes can land inside v1. Watch Changelog.

Requests and responses

Send Content-Type: application/json on any request with a body. Responses are JSON with UTF-8 encoding.

curl -X POST https://api.hirefinn.ai/v1/calls \
  -H "Authorization: Bearer $FINN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "finn_id": "finn_8kJ2mQ4xR7vNpL",
    "to": "+14155550123"
  }'

Field names use snake_case. Booleans are real JSON booleans, not the strings "true" and "false". Money and duration fields are integers in a base unit rather than floats, so you do not carry rounding error through arithmetic. Where a value is optional and unset, the field is present with null rather than omitted. Whether every optional field follows that rule consistently across all endpoints is not yet settled in beta.

Object IDs

IDs are opaque strings with a type prefix and an underscore:

finn_8kJ2mQ4xR7vNpL
call_3nW9tB6yH2kFdM

Do not parse an ID. The prefix is stable and useful for logging, but the part after the underscore carries no ordering, no timestamp, and no meaning you can depend on. Do not sort by ID and expect chronological order. Store IDs as variable-length strings up to 64 characters. Fixing a column at the length you observe today will break when a prefix or suffix length changes.

IDs are case-sensitive. finn_8kJ2mQ4xR7vNpL and finn_8kj2mq4xr7vnpl are not the same resource, and the lowercased form will return a 404.

Timestamps

All timestamps are RFC 3339 in UTC with a Z suffix and no offset:

{
  "id": "call_3nW9tB6yH2kFdM",
  "created_at": "2026-07-30T14:22:08Z",
  "ended_at": null
}

Timestamp fields end in _at. Duration fields end in _seconds or _ms and are integers.

The API never returns a local time, and it does not accept one on input. If you send a timestamp with an offset like 2026-07-30T09:22:08-05:00, treat that as unsupported rather than as something that will be converted for you. Convert to UTC in your client first.

Do not treat timestamps as a substitute for a cursor. Two records can share the same created_at value, so paginating by timestamp will drop or duplicate rows at the boundary. Use the cursor described in Pagination.

Related pages