Workspace API
Endpoints
Workspace API operations for accounts, projects, contacts, Views, Favorites, and workspace meta reads.
Ordinary account, contact, and project searches remain your book. Broader Dynamic/Static View execution uses POST /workspace/views/{id}/records/search. See Workspace Views.
Workspace meta reads return plan and usage information for the calling workspace. They cost 0 credits and never throttle.
| Operation | Method + path | Credits |
|---|---|---|
| Get workspace info | GET /workspace | 0 |
| Get credits | GET /workspace/credits | 0 |
The Workspace API also exposes four operations for each of its three datasets: accounts, projects, and contacts. Two are reads and two are writes. All share the { data, metadata } response envelope.
| Operation | Method + path | Credits |
|---|---|---|
| Search accounts | POST /workspace/accounts/search | 1 per row returned |
| Get an account | GET /workspace/accounts/{id} | 1 per call |
| Upsert account | POST /workspace/accounts/upsert | 0 |
| Delete account | DELETE /workspace/accounts/{id} | 0 |
| Batch upsert accounts | POST /workspace/accounts/upsert/batch | 0 |
| Batch delete accounts | POST /workspace/accounts/delete/batch | 0 |
| Search projects | POST /workspace/projects/search | 1 per row returned |
| Get a project | GET /workspace/projects/{id} | 1 per call |
| Upsert project | POST /workspace/projects/upsert | 0 |
| Delete project | DELETE /workspace/projects/{id} | 0 |
| Batch upsert projects | POST /workspace/projects/upsert/batch | 0 |
| Batch delete projects | POST /workspace/projects/delete/batch | 0 |
| Search contacts | POST /workspace/contacts/search | 1 per row returned |
| Get a contact | GET /workspace/contacts/{id} | 1 per call |
| Upsert contact | POST /workspace/contacts/upsert | 0 |
| Delete contact | DELETE /workspace/contacts/{id} | 0 |
| Batch upsert contacts | POST /workspace/contacts/upsert/batch | 0 |
| Batch delete contacts | POST /workspace/contacts/delete/batch | 0 |
Shared Views and personal Favorites:
| Operation | Method + path | Credits |
|---|---|---|
| List Views | GET /workspace/views | 0 |
| Get a View | GET /workspace/views/{id} | 0 |
| Upsert View | POST /workspace/views/upsert | 0 |
| Batch upsert Views | POST /workspace/views/upsert/batch | 0 |
| Delete a View | DELETE /workspace/views/{id} | 0 |
| Batch delete Views | POST /workspace/views/delete/batch | 0 |
| Add View records | POST /workspace/views/{id}/records/add | 0 |
| Batch add View records | POST /workspace/views/{id}/records/add/batch | 0 |
| Remove a View record | DELETE /workspace/views/{id}/records/{recordId} | 0 |
| Batch remove View records | POST /workspace/views/{id}/records/delete/batch | 0 |
| Search View records | POST /workspace/views/{id}/records/search | 1 per row returned |
| List Favorite Views | GET /workspace/favorite-views | 0 (user JWT) |
| Upsert Favorite View | POST /workspace/favorite-views/upsert | 0 (user JWT) |
| Batch upsert Favorites | POST /workspace/favorite-views/upsert/batch | 0 (user JWT) |
| Delete a Favorite | DELETE /workspace/favorite-views/{viewId} | 0 (user JWT) |
| Batch delete Favorites | POST /workspace/favorite-views/delete/batch | 0 (user JWT) |
Batch writes accept 1-100 records per call and return per-item results in input order. One record failing never aborts the rest. See Batch writes for the shared request and response shapes.
Signal subscriptions are workspace configuration, not a dataset. They control which signal types the workspace tracks and how alerts are delivered.
| Operation | Method + path | Credits |
|---|---|---|
| List subscriptions | GET /workspace/signal-subscriptions | 0 |
| Upsert subscription | POST /workspace/signal-subscriptions/upsert | 0 |
| Delete subscription | DELETE /workspace/signal-subscriptions/{id} | 0 |
Members and invitations are workspace administration, not a dataset. They let you inspect and manage who has access to the workspace and invite new team members.
| Operation | Method + path | Credits |
|---|---|---|
| List members | GET /workspace/members | 0 |
| Update a member | PATCH /workspace/members/{userId} | 0 |
| Remove a member | DELETE /workspace/members/{userId} | 0 |
| Invite a user | POST /workspace/invitations | 0 |
| List invitations | GET /workspace/invitations | 0 |
| Revoke an invitation | DELETE /workspace/invitations/{id} | 0 |
Shared response envelope
Every response wraps its payload in a { data, metadata } envelope, matching the Data API shape. Search responses include pagination fields; get, upsert, and delete responses include only credits.
Upsert match rules
Upsert endpoints accept either an explicit UUID or a natural-key match to identify the target record. The available match strategies differ by entity:
- Accounts accept
account_id(UUID) ormatch: { domain }. - Contacts accept
contact_id(UUID) ormatch: { email }. - Projects accept
project_id(UUID) only. Projects have no natural key.
When using a natural-key match (domain for accounts, email for contacts):
| Matches | Result |
|---|---|
| Exactly 1 record | Upsert proceeds |
| 0 records | 404 not_found |
| More than 1 record | 409 ambiguous_match (use the explicit UUID instead) |
Partial update semantics
Upsert applies partial updates to your workspace’s custom fields:
- Omitted fields are left unchanged. You can update
workspace_statuswithout touchingnotesortags. - Explicit
nullclears a field. Sending"notes": nullremoves the existing note. tagsis full-replace. Sending"tags": ["boston"]replaces the entire tag set. To clear all tags, send"tags": [].
Metering
Book entity searches and gets, plus View-record search, cost 1 credit per row returned or record fetched. View definition reads (list/get Views), Favorite reads and writes, View upsert/delete, membership add/remove, and book upserts/deletes cost 0 credits. Credits roll over a 24-hour window with a ceiling of 250,000 per Pro workspace. See Credits.