Skip to Content
Docs

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.io

The 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

ScopeLabel in SettingsAllows
read:companiesRead CompaniesRead companies
read:peopleRead PeopleRead people, and look a person up by email
read:dealsRead DealsRead deals
read:activitiesRead ActivitiesRead activities
read:crmRead CRM (people, companies, lists)Read people, companies, lookups, campaigns and lists
read:lookupsRead LookupsRead lookup values such as industries, statuses and tags
write:companiesWrite CompaniesCreate and update companies
write:peopleWrite PeopleCreate and update people, and change their email subscription
write:listsWrite ListsAdd and remove list members, and bulk unsubscribe
write:activitiesWrite ActivitiesLog activities
write:lookupsWrite LookupsManage person industry and partner tags
leadsWeb Lead IngestionSubmit leads from a web form
delete:companiesDelete and restore companiesDelete and restore companies
delete:peopleDelete and restore contactsDelete 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
  }
}
CodeStatusWhen
VALIDATION_ERROR400 or 422The body or query is invalid; the message names the field
UNAUTHORIZED401The key is missing or invalid
FORBIDDEN403The key lacks the scope
NOT_FOUND404The record doesn't exist in this workspace
DUPLICATE_EMAIL409Another person already has that email; existing_id names them
DUPLICATE_COMPANY409A company with that domain or name exists; existing_id names it
RATE_LIMIT_EXCEEDED429Too many requests this minute
INTERNAL_ERROR500Something 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 source and source_event_id. Send a stable event id from your system and a replay changes nothing.
  • Company domains. Creating a company with a website and no domain sets 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.

Next steps

On this page