ReachHQ

Start free

Product +

Lead & prospect finder ★Email finder Email verification Inbox warmup ★Realtime health ★Campaigns Analytics API & MCP

Solutions +

For founders & SDRs For sales teams For lead-gen agencies For recruiters

Pricing FAQ

Start free

REST API · v1

REST API

A scoped, versioned HTTP/JSON API covering the whole ReachHQ platform. Authenticate with a workspace API key, request only the scopes you need, and get typed errors and consistent pagination on every endpoint.

On this page

Base URL Authentication Scopes Pagination Errors Rate limits Full reference

Base URL & versioning

All endpoints live under the /api/v1 prefix:

Production: https://api.reachhq.io/api/v1
QA: https://api.qa.reachhq.io/api/v1

The version is in the path. Breaking changes ship under a new version rather than silently changing v1.

Authentication

Create an API key in the ReachHQ app under Settings › API keys and select the scopes it should carry. The secret (prefixed rhq_live_) is shown once at creation. Send it as a bearer token:

bash

curl https://api.reachhq.io/api/v1/campaigns \
  -H "Authorization: Bearer rhq_live_xxx"

A key can never carry more authority than the workspace role of the member who created it. AI assistants can use a key the same way, or connect through the OAuth connector.

Scopes

Every operation declares the scope it requires: one <resource>:read and one <resource>:write per domain, plus a dedicated scope for anything existentially risky. Actions that send email or change who can receive it, and other sensitive scopes, are never part of a broad grant.

Account

Scope	Allows	Flags
`account:read`	View your name, email, and the workspaces you can access.

Workspace

Scope	Allows	Flags
`workspace:read`	View workspace settings, sending credits, and health score.
`workspace:write`	Update workspace settings and tracking domains.	sensitive
`members:read`	View workspace members and their roles.
`members:write`	Invite, change the role of, and remove members.	sensitive

Campaigns

Scope	Allows	Flags
`campaigns:read`	View campaigns, sequences, settings, reports, and analytics.
`campaigns:write`	Create and edit campaigns, sequences, and settings.
`campaigns:launch`	Launch, pause, and resume campaign sending.	sends email sensitive

Recipients

Scope	Allows	Flags
`recipients:read`	View campaign recipients and their delivery status.
`recipients:write`	Add, import, and remove recipients on a campaign.

Leads

Scope	Allows	Flags
`leads:read`	View and export leads, tags, and notes.
`leads:write`	Create, edit, import, and delete leads, tags, and notes.
`leads:suppress`	Suppress or unsuppress leads. Changes who can receive email.	sensitive
`lead_lists:read`	View lead lists and their members.
`lead_lists:write`	Create, edit, and delete lead lists and members.
`custom_fields:read`	View custom fields and template variables.
`custom_fields:write`	Create, reorder, edit, and delete custom fields.

Deals

Scope	Allows	Flags
`deals:read`	View deals.
`deals:write`	Create and delete deals.

Mailboxes

Scope	Allows	Flags
`mailboxes:read`	View connected mailboxes, settings, and auth status.
`mailboxes:write`	Edit mailbox settings and tags; pause or resume.
`mailboxes:connect`	Connect, disconnect, and delete sending mailboxes.	sensitive

Inbox

Scope	Allows	Flags
`inbox:read`	Read inbox threads, messages, and drafts.
`inbox:write`	Manage threads, drafts, and message categories.
`inbox:send`	Send and schedule replies from your mailboxes.	sends email sensitive

Warmup

Scope	Allows	Flags
`warmup:read`	View warmup status, bounce analysis, and pools.
`warmup:write`	Enrol, configure, and start/pause/stop warmup and pools.

Verification

Scope	Allows	Flags
`verification:read`	View verification jobs, results, usage, schedules.
`verification:write`	Create, cancel, retry, and configure verification.

Deliverability

Scope	Allows	Flags
`deliverability:read`	View scores, domains, alerts, placement tests.
`deliverability:write`	Run checks and manage alerts, settings, Postmaster.
`block_list:read`	View the suppression / block list.
`block_list:write`	Add or remove block-list entries. Changes who can receive email.	sensitive

Analytics

Scope	Allows	Flags
`analytics:read`	Read reporting and analytics data.

CRM

Scope	Allows	Flags
`crm:read`	View CRM connections and segments.
`crm:write`	Connect and disconnect CRM integrations.	sensitive

Webhooks

Scope	Allows	Flags
`webhooks:read`	View outbound webhooks and delivery history.
`webhooks:write`	Create, test, requeue, and delete outbound webhooks.

Billing

Scope	Allows	Flags
`billing:read`	View subscription, plan, and credit status.	sensitive
`billing:write`	Start checkout, change the plan, buy seats and credits.	sensitive

Agency

Scope	Allows	Flags
`agency:read`	List the client workspaces you own or administer.

Lead Search

Scope	Allows	Flags
`lead_search:browse`	Search external B2B data. Email/phone masked until revealed.
`lead_search:reveal`	Reveal a result's email/phone and save it. Spends credits.	sensitive
`lead_search:lists`	Manage saved prospect lists and add results to them.

Pagination

List endpoints accept page (default 1) and pageSize (default 50, max 200) and return a consistent envelope:

json

{
  "items": [ /* ... */ ],
  "total": 184,
  "page": 1,
  "pageSize": 50
}

Errors

Errors use standard HTTP status codes and a typed JSON body: { code, message, traceId, details? }. The code is a stable machine-readable string; traceId correlates the request in our logs.

Status	Code	Meaning
400	`VALIDATION_ERROR`	The request body or query failed validation.
401	`UNAUTHORIZED`	Missing, invalid, or expired credentials.
403	`FORBIDDEN`	The credential lacks a required scope.
404	`NOT_FOUND`	The resource does not exist in this workspace.
409	`CONFLICT`	A version conflict or duplicate.
429	`RATE_LIMITED`	Too many requests; back off and retry.
503	`SERVICE_UNAVAILABLE`	A downstream service was unavailable; retry.

Example, calling a launch endpoint with a read-only key:

http

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", scope="campaigns:launch"

{
  "code": "FORBIDDEN",
  "message": "Insufficient scope",
  "details": { "required": ["campaigns:launch"], "missing": ["campaigns:launch"] },
  "traceId": "3f9c2a8e..."
}

Rate limits

The REST surface is limited to 600 requests per 60 seconds per credential. Exceeding it returns 429 with code RATE_LIMITED. The MCP server has its own limit of 240/min.

Full reference

The complete, always-current list of endpoints, parameters and responses is generated from the running API:

Open the API reference