Your records, in and out of Sand.

Create a key

In Sand, open Settings → API keys and choose Create key. Give it a name you will recognise in six months — the system it is for, not “key 1” — and tick only the scopes that system actually needs.

A key looks like sand_ followed by 64 characters. It can be revoked at any time from the same screen, and it stops working immediately.

Your first call

Send the key in the x-api-key header. That is the whole of it:

curl https://api.yourdomain.com/api/v1/crm/contacts \
  -H "x-api-key: sand_xxxxxxxxxxxxxxxx"

You get your contacts back, newest first, in pages:

{
  "success": true,
  "data": {
    "contacts": [ { "id": 182, "firstName": "Anita", "lastName": "Rao", … } ],
    "total": 1463,
    "page": 1,
    "pages": 59
  }
}

Every address starts /api/v1, and those are the only ones a key opens. The header is the only place Sand accepts a key — never put it in the web address, where it would be written into every server log it passes through.

What your plan includes

API access comes with Grain · Enrichment, Base + Grain and Base + Grain + Wave. It covers the modules your plan covers — nothing more, nothing less — and there is no separate API charge.

Base · CRM on its own does not include the API: a key cannot be made, and every call answers 403 with the code PLAN_NO_API.

Wave is a talk-to-us tier, so outreach arrives with the plan rather than off the price list. Once your workspace has it, its endpoints behave exactly like the rest.

Scopes

Each key is granted only the parts of the API it needs. A website form that creates leads has no business spending enrichment credits, even though the person who made the key could.

Two rules worth knowing. A scope can only narrow what a key reaches — it can never open a module your plan does not include. And a key created with no scopes at all is read-only, not unrestricted.

Reading and writing records

Contacts are shown here; companies, deals and leads work the same way at /v1/crm/companies, /v1/crm/deals and /v1/crm/leads — list, create, get, update, delete.

Pull a page at a time

curl 'https://api.yourdomain.com/api/v1/crm/contacts?page=1&limit=100' \
  -H "x-api-key: $SAND_KEY"

Up to 100 per page. Keep asking until page reaches pages.

Push one in

curl -X POST https://api.yourdomain.com/api/v1/crm/contacts \
  -H "x-api-key: $SAND_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "Anita",
    "lastName": "Rao",
    "email": "anita@acme.example",
    "phone": "+91 80 2222 3333",
    "companyName": "Acme Agri",
    "title": "Head of Procurement"
  }'

The answer carries the new record and, if Sand spots someone who looks like the same person, a possibleDuplicates list. That is a warning, not a refusal — the record is created either way, so your sync can log it and move on.

Push up to a hundred at once

For a first load or a nightly sync, send a batch rather than a request per person. The answer says, row by row, what was created and what was skipped and why — so your sync can retry the failures without sending what already landed.

curl -X POST https://api.yourdomain.com/api/v1/crm/contacts/bulk_create \
  -H "x-api-key: $SAND_KEY" -H 'Content-Type: application/json' \
  -d '{"contacts":[
        {"firstName":"Anita","email":"anita@acme.example"},
        {"firstName":"Ravi","email":"ravi@harvest.example"}
      ]}'

A row whose email already belongs to one of your contacts is skipped with that contact’s id rather than duplicated, so sending the same batch twice adds nobody twice.

Enrichment

Enrichment is the metered part, and only revealing a person or enriching a company spends credits. Searching and matching are free, and nothing is ever charged for an empty result.

Find companies

curl -X POST https://api.yourdomain.com/api/v1/enrichment/companies/search \
  -H "x-api-key: $SAND_KEY" -H 'Content-Type: application/json' \
  -d '{"q":"seeds","states":["Karnataka"],"sizes":["11-50"],"has":["email"]}'

Match your own list

Your systems hold domains and GSTINs, not Sand’s ids. Send up to 25; a name that several companies share comes back with candidates to choose from rather than a guess.

curl -X POST https://api.yourdomain.com/api/v1/enrichment/companies/match \
  -H "x-api-key: $SAND_KEY" -H 'Content-Type: application/json' \
  -d '{"companies":[{"domain":"acme-agri.example"},{"gstin":"29AAAAA0000A1Z5"}]}'

Reveal, and fill in your CRM

# a person's email or phone — charged once, never for an empty one
curl -X POST https://api.yourdomain.com/api/v1/enrichment/people/reveal \
  -H "x-api-key: $SAND_KEY" -H 'Content-Type: application/json' \
  -d '{"ref":"p123","channel":"email"}'

# your own companies, filled in from the database
curl -X POST https://api.yourdomain.com/api/v1/crm/companies/enrich \
  -H "x-api-key: $SAND_KEY" -H 'Content-Type: application/json' \
  -d '{"ids":[12,15]}'

Nothing is guessed: a field the database cannot back up stays empty rather than being filled in.

Limits

Ask, rather than finding out the hard way. This works with any valid key, whatever its scopes:

curl https://api.yourdomain.com/api/v1/usage \
  -H "x-api-key: $SAND_KEY"

It tells you the key’s scopes, your plan, your credit balance and your request budget — 3,000 requests every 15 minutes per key, counted per key, so one integration cannot eat another’s allowance. Every response also carries RateLimit- headers with what is left in the current window.

When something is refused

Every refusal answers in the same shape, with a plain-language message you can log.

Keeping a key safe

A key is a password that will sit in a configuration file for years. Four habits cover most of it:

• Keep it in an environment variable or a secret store — never in your source code, and never in a web address.
• One key per system, so you can revoke the one that leaked without stopping everything else.
• Grant the fewest scopes that work. A read-only key cannot damage anything.
• Set an expiry on anything temporary, and revoke keys for systems you have retired.

If a key is ever exposed, revoke it first and investigate second — revoking takes effect immediately, and making a replacement takes a few seconds.