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
- Open API and webhooks in the workspace settings.
- Under Create a key, give it a name you'll recognize, like the tool it's for.
- Choose Read only, or Read and change.
- 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.