What we do
Tools
Industries
Department
How we workLet's talk →
Home/Help Scout/Help Scout API
Help Scout

The Help Scout API Is Two APIs: Inbox for Conversations, Docs for Articles

You've been asked to push refund-tagged conversations into billing, or to publish release notes into the help center from your repo. Those jobs use different Help Scout APIs, with different auth and different limits. The Inbox API (Mailbox API 2.0) uses OAuth2 and covers conversations, customers and tags. The Docs API uses a plain API key and covers articles. Pick the right one and the first request takes minutes.

Inbox API or Docs API: they share a name and little else

Inbox API (Mailbox 2.0)

Conversations, customers, tags

  • Base URL https://api.helpscout.net/v2, HTTPS only.
  • OAuth2: client credentials for your own account, authorization code for apps other accounts install.
  • Conversations, threads, customers, tags, mailboxes, users and reports. Standard plans don't get the reporting endpoints.
  • Rate limit set by your plan and shared by every user on the account.
Docs API

Sites, collections, articles

  • Base URL https://docsapi.helpscout.net/v1.
  • An API key from Your Profile, then Security and Access, sent as the Basic auth username with any dummy password.
  • Create, update, upload and delete articles, and save drafts.
  • Limit tied to how many Docs sites you have: 2,000 requests per 10 minutes for one site.

Mixing them up is the most common first-day stall: an OAuth token won't open the Docs API, and a Docs key won't open a mailbox.

A first Inbox API token for your own account

For an internal integration, the client credentials flow skips the browser redirect entirely.

  1. 1

    Create an OAuth2 app

    Your Profile My apps

    Help Scout asks for a redirect URL even if you'll never use it. For client credentials only, a placeholder URL is fine. Copy the App ID and App Secret.

    Watch for: the app acts as the user who created it. That person has to stay an active, invited user, or every call starts returning 401.

  2. 2

    Exchange the credentials for a token

    POST to https://api.helpscout.net/v2/oauth2/token with grant_type=client_credentials, your client ID and your client secret. The response holds an access token with expires_in of 172800 seconds, which is two days.

  3. 3

    Send it on every request

    Put it in the Authorization header as a Bearer token. Store it in a field with no fixed length, because Help Scout says token length can change.

  4. 4

    Renew on 401, not before

    An expired token shows up as a 401. Request a new one then, rather than minting a fresh token on every run.

    Watch for: building something other Help Scout accounts will install? Use the authorization code flow instead. The user approves at secure.helpscout.net, and you get a refresh token to swap for new access tokens.

How a minute of Help Scout requests adds up

Plan caps from Help Scout's docs: Standard up to 200 calls a minute, Plus up to 400, Pro up to 800. The Free plan has no API access. Writes and v3 searches count double.

Example minute on a Standard plan
Allowance for the account (Shared by every user and every integration) 200
60 conversation reads − 60
30 tag updates (writes count as 2) − 60
20 customer searches on v3 (count as 2) − 40
A second integration someone else installed (Same budget, nobody told you) − 50
Short this minute, so the next calls get 429s − 10

Over the cap you get a 429. Read X-RateLimit-Remaining-Minute as you go, and wait the seconds in X-RateLimit-Retry-After before trying again.

Why a Help Scout webhook goes quiet

Webhooks are switched on under Settings, then Workspace, then Apps, then Webhooks. These are the ways they stop delivering.

Your endpoint was down long enough

How you'll know: Events stopped and the webhook shows as inactive.

Fix: Any status outside 200 to 299 is a failure. Help Scout retries a failed event up to 10 times with growing gaps, then discards it, and once ten or more events are discarded it deactivates the webhook. Answer 200 straight away, queue the work, and pull anything missed from the Inbox API after an outage.

Something returned a 410

How you'll know: The webhook vanished after a deploy.

Fix: A 410 tells Help Scout to deactivate or delete the webhook. Make sure no framework default or retired route answers with it.

Signatures don't match

How you'll know: Every request fails your check, or only ones with accented names do.

Fix: The X-HelpScout-Signature header is an HMAC-SHA1 of the raw body with your secret key, base64-encoded. Compute it on the bytes you received, before any JSON parsing or re-encoding.

customer.created fires for everything

How you'll know: Your handler for one inbox gets customers from all of them.

Fix: That event can't be filtered by inbox and fires for every customer created in the account. Filter on your side.

From a fired event to a refund that actually happens

The API hands you data, not decisions. It will tell you a conversation was tagged refund, or that a customer replied, but it has no view on what a refund means in your payment system or which order a reply is about. That logic, with its auth, retries and logging, lives outside Help Scout.

n-frames builds and runs that receiving end: a handler that turns a refund or cancel tag into the real action in the system that owns it and writes a note back onto the conversation, or a lookup that fires on conversation created so order and billing details are waiting when an agent opens it. For showing account details to customers in the widget, see Help Scout Beacon. For specific pairings, there are pages on Slack, Shopify and Salesforce, and the Help Scout overview covers the product itself.

Help Scout API questions

Does Help Scout have an API, and which one do I need?

Two. The Inbox API, still called Mailbox API 2.0 in places, is a REST API at api.helpscout.net/v2 for conversations, threads, customers, tags, mailboxes, users and reports. The Docs API at docsapi.helpscout.net/v1 manages knowledge-base sites, collections and articles. The older Mailbox API 1.0 is deprecated.

Does Help Scout support webhooks and event notifications?

Yes. Events cover conversations (created, assigned, moved, merged, deleted, status, tags, custom fields, replies, notes), customers, organizations, tags, ratings, Beacon chats, survey responses and user status changes. Each request carries an X-HelpScout-Signature header so you can confirm it came from Help Scout.

Do I need a developer to use Help Scout's API?

For a simple sync through a third-party connector, often not. To react to webhooks in real time, like issuing a refund when a tag is applied, yes: something has to receive the event, verify it and act on it, and keep doing that every day. n-frames builds that receiving end and keeps it running.

Is Help Scout's API available on every plan?

No. Help Scout's docs say the Free plan doesn't include the API or integrations. Standard gets up to 200 calls a minute without the reporting endpoints, Plus up to 400 and Pro up to 800 with all endpoints. Check your plan before choosing a design that depends on reports or a high call rate.

How long does a Help Scout access token last?

Two days. Both OAuth2 flows return tokens with expires_in of 172800 seconds. When a call comes back 401, get a new token; with the authorization code flow, swap the refresh token for it.

Let's talk

Tell us the one thing your team does manually that eats up time. We read every message and reply within a day.