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

The Basecamp API: What Your First Integration Needs to Get Right

Your script works on the first try in Postman, then returns a 400 from your server, or runs for a week and quietly misses every project created after launch. Basecamp's REST API is small and well documented on GitHub, and most of the trouble sits in a few rules around it. Here they are, in the order you'll meet them.

However you want to go about it
01
Where it lives

Every URL starts with https://3.basecampapi.com/ followed by the account ID. JSON only, HTTPS only. Basecamp 4 accounts use this API.

02
Auth

OAuth 2.0 through 37signals Launchpad. Basic auth is no longer supported. Access tokens last two weeks, and you refresh them.

03
The header people forget

A User-Agent with your app's name and a link or contact email. Leave it off and every request gets a 400.

04
Limits

Currently 50 requests per 10 seconds per IP address, plus other limits that adjust. Over it, you get a 429 with Retry-After.

From a Launchpad app to your first Basecamp request

  1. 1

    Register the integration

    launchpad.37signals.com/integrations Register

    Give it a name and a redirect URI. Launchpad hands back a client ID and a client secret. One registration serves every Basecamp account that later authorizes it.

  2. 2

    Send the user to authorize

    Redirect to launchpad.37signals.com/authorization/new with type=web_server, your client ID and the redirect URI. After they approve, Launchpad sends a code back to that URI.

  3. 3

    Swap the code for tokens

    POST to launchpad.37signals.com/authorization/token with type=web_server, the code and your credentials. Store the refresh token. When the access token runs out, POST to the same URL with type=refresh.

    Watch for: the two-week lifetime. A job that runs fine for a fortnight and then fails every call is almost always a refresh that never got written.

  4. 4

    Find the account ID

    Call launchpad.37signals.com/authorization.json with the bearer token. It lists every account the user can reach. Pick the one with product bc3. Its href is the base URL for everything after this.

  5. 5

    Make a real request

    GET /projects.json on that base URL, with Authorization: Bearer <token> and your User-Agent. When you POST or PUT, also send Content-Type: application/json; charset=utf-8.

Errors and silences a Basecamp integration runs into

Most of these show up in the first week. The last two show up only after something's already been missed.

400 Bad Request on every call

How you'll know: The same request works from one tool and fails from your code.

Fix: Your HTTP client isn't sending a User-Agent. Set one that names the app and gives a URL or email, for example Client Portal Sync (ops@example.com).

415 on writes

How you'll know: Reads succeed, but creating a to-do or posting a message fails.

Fix: The Content-Type header is missing or wrong. It has to be application/json; charset=utf-8.

429s during a big pull

How you'll know: A backfill of every project's to-dos stops partway with Too Many Requests.

Fix: Read the Retry-After header and wait that many seconds before trying again. Follow the Link header for the next page instead of building page URLs yourself, and send back the ETag so unchanged lists come back as 304s.

New projects never fire anything

How you'll know: Webhooks work for the projects you set them up on. Anything created later is silent.

Fix: A webhook belongs to one project (POST /buckets/{project_id}/webhooks.json). There's no account-wide subscription, so something has to notice each new project and create its webhook.

A webhook switched itself off

How you'll know: Events stopped after your endpoint had a bad afternoon.

Fix: Basecamp tries a delivery up to 10 times, with longer gaps each time, then deactivates the webhook. Only 2xx counts, and redirects aren't followed. Check the recent deliveries on the webhook (up to 25 are kept), fix the endpoint and turn it back on.

Built on Basecamp webhooks and the API

Each of these starts from a webhook and calls the API back for the detail, because the payload carries a generic recording rather than every field.

01

Basecamp to the CRM

A milestone to-do marked done updates the matching account or deal in the CRM your account team works from, so client status isn't kept in two places that disagree.

02

GitHub or GitLab status in the to-do

A merged pull request or a closed issue posts a comment on the Basecamp to-do it belongs to, so the client-facing update doesn't depend on someone copying it across.

03

A watcher for new projects

A small job checks for projects created since it last ran and subscribes each one, then alerts if any webhook has been deactivated.

04

Posting into Campfire

Chat isn't one of the webhook types. Messages into a project's Campfire go through Basecamp's chatbot API instead, which suits build alerts or a daily summary.

Questions people ask

Does Basecamp have an API?

Yes. A documented REST API, published in the bc3-api repository on GitHub, covering projects, to-dos, message boards, documents, schedules, card tables and people, with webhooks for changes. It isn't compatible with the old Basecamp Classic or Basecamp 2 APIs.

Can Basecamp connect to Salesforce?

Basecamp doesn't make a Salesforce connector itself, so look at its integrations directory and Zapier first. For anything past a one-step trigger, such as a milestone that updates an opportunity and a won deal that creates the project, it's custom work against both APIs.

Does Basecamp integrate with Slack natively?

There's no two-way Slack app from Basecamp. Simple notices, like a new message or a finished to-do posting to a channel, are a short build on Basecamp webhooks and Slack's own API, or a Zapier step.

Does Basecamp work with GitHub or GitLab?

Not natively. Getting commit, pull request or issue status into the right Basecamp to-do means listening to the dev tool's webhooks and writing a comment or update through Basecamp's API.

What if something I need to automate in Basecamp doesn't have an API endpoint?

It happens now and then with narrower settings that only exist in the app. In that case we automate the action through the browser instead, and keep that piece small, since a screen can change in a way an endpoint won't.

Who builds Basecamp integrations?

n-frames builds and runs them: the Launchpad app, token refresh, the per-project webhook watcher and the handoff into your CRM, Slack or dev tools, so your team doesn't have to keep an eye on the plumbing.

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.