PlumHelp
Help · Workspace settings

The API

Let your own tools and other services read this workspace's accounts, contacts, deals and revenue, and add or change CRM records, with a key you make and can revoke.

Owners and admins make and revoke keys

Make a key

  1. Open API and webhooks in the workspace settings.
  2. Under Create a key, give it a name you'll recognize, like the tool it's for.
  3. Choose Read only, or Read and change.
  4. Select Create key, and copy the key straight away. It is shown once and can't be shown again; Plum keeps only a fingerprint of it.

Give each tool its own key, so you can revoke one without the others. Revoking a key stops it working at once. A key also stops working if the person who made it is no longer an owner or admin, or if the workspace is suspended.

Send it

Every request carries the key in a header: Authorization: Bearer plum_ followed by the rest of the key. Requests go to your Plum address followed by /api/v1, for example https://runonplum.com/api/v1/accounts. Bodies are JSON.

What you can reach

GET /api/v1/accounts
A page of accounts. Add q= to search names and domains.
POST /api/v1/accounts
Add an account: name, and optionally domain, lifecycle, lead_source, do_not_prospect.
GET /api/v1/accounts/{id}
One account, with its contacts, deals, licenses, holdings, live ARR and next renewal.
PATCH /api/v1/accounts/{id}
Change the fields you send.
GET /api/v1/contacts
A page of contacts. q= searches names and email.
POST /api/v1/contacts
Add a contact: a name or an email, and optionally account_id, phone, title, lead_source.
GET /api/v1/contacts/{id}
One contact.
GET /api/v1/deals
A page of deals. q= searches names.
POST /api/v1/deals
Add a deal: name, and optionally account_id, stage_key, arr, one_time_amount, close_date, next_step. Without a stage it starts in the first open one.
GET /api/v1/deals/{id}
One deal.
PATCH /api/v1/deals/{id}
Move a deal by sending stage_key, or change any other field.
POST /api/v1/activities
Log a note, call, meeting or email on an account or deal, or on whoever has contact_email. Send external_id and the same activity sent twice is kept once.
POST /api/v1/tasks
Add a task: title, and optionally account_id, deal_id, due_date.
GET /api/v1/renewals?days=90
Licenses ending within that many days with no renewal on file.
GET /api/v1/metrics
The headline numbers: live ARR and MRR, retention, weighted pipeline, revenue by kind.
GET /api/v1/licenses
A page of licenses. Read only.
GET /api/v1/holdings
A page of what customers bought once, projects and retainers. Read only.
GET /api/v1/objects
Your own kinds of record (custom objects) in use, each with its key and fields. Then GET /api/v1/objects/{key} for a page of its records and /api/v1/objects/{key}/{id} for one. Read only.
POST /api/v1/enrich
Up to 500 contacts and accounts from a lead-generation tool, matched to who is already there and merged by your rules for that tool, with outreach activity if you like. See Lead generation.
GET /api/v1/segments
The built-in segments, with how many accounts and people are in each.
GET /api/v1/segments/{key}
One segment's people, one row each. without_offer also needs offer= with an offer id.
GET /api/v1/suppression
The domains and email addresses outbound tools should never prospect: your current customers and every account marked do not prospect.

Adding and changing needs a key that can read and change; a read-only key gets 403. Licenses, holdings and revenue are read only through the API: they change in Plum, where the ARR walk is kept in step.

Examples

Request: GET /api/v1/accounts?limit=2&q=northwind

Answer: { "data": [ { "id": "6f1c…", "name": "Northwind", "domain": "northwind.com", "lifecycle": "customer", … } ], "next": null }

Request: POST /api/v1/activities with { "contact_email": "dana@northwind.com", "kind": "call", "subject": "Renewal check-in", "external_id": "call-981" }

Answer: 201 { "data": { "id": "0b7e…", "duplicate": false } }. Sent again: 200 with "duplicate": true.

Request: PATCH /api/v1/deals/{id} with { "stage_key": "proposal" }. Answer: 200 { "data": { the deal, in its new stage } }.

Paging

Lists return up to 50 records, or as many as limit= asks for, up to 200, in id order. When there may be more, next holds an id: ask again with after= set to it. When next is null, you have them all. Add updated_since= with a date and time, like 2026-10-01T00:00:00Z, to fetch only what changed since then.

Errors

An error answers with a status and a body like { "error": { "code": "invalid", "message": "…" } }. An invalid request also lists issues, each with the path of the field and what is wrong with it.

400 invalid, not_json
A field is missing or not allowed, or the body isn't JSON.
401 unauthorized
No key, or a key that is unknown, revoked or whose workspace isn't active.
403 read_only
A read-only key tried to change something.
404 not_found
No record with that id in this workspace, or one the request refers to doesn't exist.
409 conflict
It already exists: an account with that domain, or a contact with that email. The message names the existing record.
413 too_large
The body is over 1 MB.
429 rate_limited
Over the limit. Wait the number of seconds in Retry-After.

Limits

  • 600 calls a minute for each key.
  • Request bodies up to 1 MB.
  • Up to 25 keys in use in a workspace at once, and 20 new keys a day.

A key is as powerful as a password for your workspace's data. Keep it in your tool's secret settings, never in a web page or a shared document, and revoke it if it may have been seen.

Related