REST API
Read and write your workspace's CRM data from your own services with an API key.
The XODASH public REST API lets your own services read and write companies, people, deals, activities, marketing lists and subscriptions, and submit web leads. Each request is authenticated with an API key that belongs to one workspace.
Base URL and reference
https://api.xodash.ioThe interactive reference is at api.xodash.io/api/public/docs. It lists every endpoint with its parameters and responses, and you can authorize with your key and try requests against your own data.
Create an API key
Who can do this
Only workspace admins see the API tab in Settings.
Open API Keys
Go to Settings → API.
Select Create API Key
Give the key a name that says what it's for.
Choose its scopes
New keys start with no permissions. Tick each scope the integration needs. If you tick Web Lead Ingestion, you can also add email addresses that XODASH notifies whenever a new lead is submitted.
Copy the key
XODASH shows the key once, under Save your API key. Select Copy Key, store it somewhere safe, then confirm that you've saved it.
The key list shows each key's scopes and when it was Last used. Delete removes a key for good, and any integration using it stops working. If you lose a key, delete it and create a new one.
Keep keys on your server
Call the API from your own server, never from browser or mobile app code. Anyone who can see a key can use it, and browser requests carrying a key are refused.
Authenticate
Send the key in the X-API-Key header on every request:
curl https://api.xodash.io/api/public/people \
-H "X-API-Key: YOUR_API_KEY"A key can only reach the workspace it was created in.
Scopes
| Scope | Label in Settings | Allows |
|---|---|---|
read:companies | Read Companies | Read companies |
read:people | Read People | Read people, and look a person up by email |
read:deals | Read Deals | Read deals |
read:activities | Read Activities | Read activities |
read:crm | Read CRM (people, companies, lists) | Read people, companies, lookups, campaigns and lists |
read:lookups | Read Lookups | Read lookup values such as industries, statuses and tags |
write:companies | Write Companies | Create and update companies |
write:people | Write People | Create and update people, and change their email subscription |
write:lists | Write Lists | Add and remove list members, and bulk unsubscribe |
write:activities | Write Activities | Log activities |
write:lookups | Write Lookups | Manage person industry and partner tags |
leads | Web Lead Ingestion | Submit leads from a web form |
delete:companies | Delete and restore companies | Delete and restore companies |
delete:people | Delete and restore contacts | Delete and restore contacts |
Read CRM never includes deals, activities or any write access; add those scopes separately. The delete scopes are never implied by another scope, and they only work while the person who created the key may delete those records in XODASH. Deletes and restores are recorded in the workspace's activity log under that person.
A 403 means the key is valid but lacks the scope. Create a key with the right scope instead of
retrying.
What you can read
- Companies, with their address and tags.
- People, with their title, department, LinkedIn address and buying role, and a lookup by email.
- Deals and activities.
- Campaigns, lists and list members.
- Lookups: company industries, statuses, types, service types and tags; person industries, partners and statuses.
Records marked private in XODASH are never returned, whatever the key's scopes. List endpoints take
page and per_page (up to 100) and return a meta block with total and total_pages.
Rate limits
Each key can make 1,000 requests a minute. Every response carries X-RateLimit-Limit and
X-RateLimit-Remaining. Over the limit, the API answers 429 with the code
RATE_LIMIT_EXCEEDED and a Retry-After header saying how many seconds to wait.
Errors
Every error uses the same shape:
{
"error": {
"code": "VALIDATION_ERROR",
"message": "body/email: Invalid email",
"status": 400
}
}| Code | Status | When |
|---|---|---|
VALIDATION_ERROR | 400 or 422 | The body or query is invalid; the message names the field |
UNAUTHORIZED | 401 | The key is missing or invalid |
FORBIDDEN | 403 | The key lacks the scope |
NOT_FOUND | 404 | The record doesn't exist in this workspace |
DUPLICATE_EMAIL | 409 | Another person already has that email; existing_id names them |
DUPLICATE_COMPANY | 409 | A company with that domain or name exists; existing_id names it |
RATE_LIMIT_EXCEEDED | 429 | Too many requests this minute |
INTERNAL_ERROR | 500 | Something failed on our side |
A 500 never includes technical details. It carries a request_id, also sent as the
x-request-id header. Include it when you contact support.
Good to know
- Retries without duplicates. Activity logging, list membership and subscription writes accept
sourceandsource_event_id. Send a stable event id from your system and a replay changes nothing. - Company domains. Creating a company with a
websiteand nodomainsets the domain from the website, unless another company already has it. - Agent webhooks. A named agent can also be started by a signed webhook call. Its address and secret come from the agent's page, not from an API key.