Quickstart

From an installed app to a sent message: install, exchange the code for tokens, probe the token, read contacts, send.

Five steps take you from app credentials to a sent message. Every request is copy-paste ready. Swap in your own values as you go.

Before you start

App credentials. A client_id and client_secret, issued when your app is registered on the Custom integration page of the dashboard, or by Blue Reacher support. See Custom integrations.
A Blue Reacher user. Someone to install your app and consent to its scopes.
A callback URL. The redirect_uri registered on your app. The authorization code is delivered there.

Install your app

Send the user's browser to the install URL. They sign in if needed, review the scopes your app requests, and select Install.

https://app.bluereacher.com/integrations/install/<CLIENT_ID>?redirect_uri=<YOUR_CALLBACK>&state=<RANDOM>

On consent, the browser is redirected to your callback with a single-use ?code= query parameter. Exchange it right away. It expires after 10 minutes.

Exchange the code for tokens

curl -X POST https://api.bluereacher.com/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "authorization_code",
    "code": "<CODE_FROM_CALLBACK>",
    "client_id": "<YOUR_CLIENT_ID>",
    "client_secret": "<YOUR_CLIENT_SECRET>",
    "redirect_uri": "<YOUR_CALLBACK>"
  }'

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "Bearer",
    "expires_in": 86400,
    "scopes": ["contacts.read", "contacts.write", "messages.write"]
  }
}

Store both tokens, keyed by the installing user. The access token lasts 1 day. Use the refresh token, which lasts 365 days, to get a new pair when you see a 401.

Make your first call

GET /v1/integration/me is a wiring test. It verifies your token and shows the installer and the granted scopes.

curl https://api.bluereacher.com/v1/integration/me \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

{
  "success": true,
  "data": {
    "integration": { "id": 12, "name": "Your App" },
    "user": { "id": 42, "name": "Dana", "email": "dana@example.com" },
    "scopes": ["contacts.read", "contacts.write", "messages.write"]
  }
}

A 200 here means authentication works. Everything else is just endpoints.

Read some data

curl "https://api.bluereacher.com/v1/contacts?workspace_id=7&limit=5" \
  -H "Authorization: Bearer <ACCESS_TOKEN>"

This needs the contacts.read scope. A 403 means the token was not granted that scope. Reinstall with it included. workspace_id is required on most calls. List your workspaces with GET /v1/workspaces to find the id.

Send your first message

This needs the messages.write scope and a device assigned to the workspace (dashboard, Devices). One attachment per message, up to 5 MB.

curl -X POST https://api.bluereacher.com/v1/messages \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "workspace_id": 7,
    "phone": "+15551234567",
    "channel": "default",
    "message": "Hello from the Blue Reacher API"
  }'

A 200 means the message is queued for delivery. Poll GET /v1/messages/{id} with the returned message_id to follow its status. Sends are limited to 30 per 15 minutes per workspace. See Rate limits.

If something fails

Status	Cause	What to do
`401`	The token expired or is invalid.	Refresh it with `grant_type: refresh_token`.
`403`	The token is missing a scope.	Reinstall the app with that scope included.
`404`	The resource does not exist, or belongs to another installer.	Check the id and the workspace.
`429`	Rate limited.	Back off and retry. See Rate limits.

Authentication: the full flow, refresh and revocation.
Scopes: what each scope unlocks.
Rate limits: budgets and 429 handling.
API reference overview: every route.