API Usage Guide

Use the SnapCRM API to add leads from your own apps, scripts, or integrations. This guide is public; to use the API you need an account and an API key.

Getting started: you need a SnapCRM account

The API is available to SnapCRM users only. To use it:

Create an account — Sign up for SnapCRM if you don’t have one yet.
Sign in — Sign in to your account.
Generate an API key — Go to Settings → API Access in the app and click “Generate API Key”. Copy and store the key securely; it’s shown only once.
Call the API — Send requests with your API key in the header (see below).

Create account Sign in

1. Authentication

Every API request must include your API key. You can send it in either of these ways:

Option A: X-API-Key header (recommended)

X-API-Key: snap_your_api_key_here

Option B: Authorization Bearer

Authorization: Bearer snap_your_api_key_here

Never share your API key or commit it to version control. Store it in environment variables or a secrets manager.

2. Base URL

Send requests to your SnapCRM site. For example:

https://your-snapcrm-site.com/api/v1/leads

Replace with your actual domain (e.g. https://snapcrm.app).

3. Create a lead (POST /api/v1/leads)

Add a new lead with a POST request. The lead is created under your account (and your team, if you have one).

Request

POST /api/v1/leads
Content-Type: application/json
X-API-Key: snap_your_api_key_here

{
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "phone": "+1 555-123-4567",
  "company": "Acme Inc",
  "website": "https://acme.com",
  "source": "website",
  "address": "123 Main St",
  "city": "New York",
  "state": "NY",
  "zipcode": "10001"
}

Required fields

firstName (string)
lastName (string)

Optional fields

email, phone, company, website
source (e.g. website, referral, cold_call)
address, city, state, zipcode
tagId (ID of an existing tag to assign)

Success response (201 Created)

{
  "id": "clx...",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "[email protected]",
  "status": "new",
  "createdBy": { ... },
  "tags": [],
  ...
}

cURL example

curl -X POST "https://your-site.com/api/v1/leads" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"firstName":"Jane","lastName":"Smith","email":"[email protected]"}'

4. Rate limits

Each API key is limited to a number of requests per minute (default is 200). Your limit can be increased by an admin.

Responses include X-RateLimit-Limit and X-RateLimit-Remaining headers.
If you exceed the limit, you get 429 Too Many Requests and a Retry-After header (in seconds).

To avoid hitting the limit, cache results when possible and space out bulk creates (e.g. add a short delay between requests).

5. Error responses

401

Unauthorized

Missing or invalid API key. Create an account, sign in, and generate a key in Settings → API Access.

400

Bad Request

Invalid JSON or missing required fields (e.g. firstName, lastName).

409

Conflict

A lead with the same email or name already exists in your account.

429

Too Many Requests

Rate limit exceeded. Wait and retry; check Retry-After header.

Quick checklist

1. Create an account and sign in, then get your API key from Settings → API Access.
2. Send X-API-Key or Authorization: Bearer <key> with every request.
3. Use POST /api/v1/leads with JSON body (firstName, lastName required).
4. Stay within your rate limit (default 200 requests/minute).

← Back to SnapCRM