Base URL & Headers

Every SMBcrm REST API request shares the same shape: one base URL, a bearer token, an API version, and JSON. Get this right once and every endpoint in the reference works the same way.

Base URL

https://services.smbcrm.com

All requests are made over HTTPS to this host. Endpoint paths in this documentation are relative to it. For example, GET /contacts/{contactId} means GET https://services.smbcrm.com/contacts/{contactId}.

About the base URL

services.smbcrm.com is the SMBcrm API gateway. It forwards standard REST API traffic to the same backend that powers your SMBcrm account. You can use it anywhere you would use a normal REST API host.

Required headers

Header	Value	Required
Authorization	Bearer <access_token_or_private_integration_token>	Always
Version	v3	Always
Accept	application/json	Recommended
Content-Type	application/json	On POST, PUT, and PATCH with a body

The Version header is required on every request and selects the API version. Send v3, the current version. The API also accepts older date-based versions (such as 2021-07-28) for backward compatibility, but new endpoints and improvements land in v3, so use it for anything new. See Versioning & Stability.

A complete request

cURL

curl https://services.smbcrm.com/contacts/<contact_id> \
  -H "Authorization: Bearer <access_token_or_private_integration_token>" \
  -H "Version: v3" \
  -H "Accept: application/json"

Node.js

const res = await fetch(`https://services.smbcrm.com/contacts/${contactId}`, {
  headers: {
    Authorization: `Bearer ${token}`,
    Version: 'v3',
    Accept: 'application/json',
  },
});
const data = await res.json();

Python

import requests

res = requests.get(
    f"https://services.smbcrm.com/contacts/{contact_id}",
    headers={
        "Authorization": f"Bearer {token}",
        "Version": "v3",
        "Accept": "application/json",
    },
)
data = res.json()

Your account/location ID

Most endpoints operate on a single SMBcrm account/location. Where an ID is required, this documentation uses the placeholder <location_id>. This is the identifier for your SMBcrm account/location. Depending on the endpoint it appears as:

• a path segment: GET /locations/<location_id>
• a query parameter: GET /contacts/?locationId=<location_id>
• a field in the JSON body: { "locationId": "<location_id>" }

Each endpoint page shows exactly where it belongs. A Private Integration Token is already scoped to one account/location, so some endpoints can infer it; when in doubt, pass it explicitly.

Content type & responses

Requests that send a body must set Content-Type: application/json and send valid JSON. Responses are JSON. Successful responses use standard 2xx status codes; errors use 4xx and 5xx with a JSON body describing the problem. See Errors & Troubleshooting.

Pagination

List endpoints are paginated. Most accept limit and either a skip/offset or a cursor (startAfterId / startAfter) parameter, and return a meta object with the total and the values to request the next page. The exact parameters are shown on each endpoint; always read meta rather than assuming a page size.

curl "https://services.smbcrm.com/contacts/?locationId=<location_id>&limit=20" \
  -H "Authorization: Bearer <token>" \
  -H "Version: v3"

Rate limits

The API is rate limited per account. When you exceed a limit you receive 429 Too Many Requests; back off and retry. Current limits are returned on every response via headers so you can throttle proactively:

Response header	Meaning
X-RateLimit-Max	Requests allowed in the current burst window
X-RateLimit-Remaining	Requests remaining in the current burst window
X-RateLimit-Interval-Milliseconds	Length of the burst window
X-RateLimit-Limit-Daily	Requests allowed per day
X-RateLimit-Daily-Remaining	Requests remaining today

Tip

Read the rate-limit headers and slow down before you hit 429. Batch where an endpoint supports it, cache values that rarely change (custom fields, pipelines, calendars), and prefer webhooks over polling for changes.

Browser (client-side) requests

Prefer calling the API from your server, not the browser. Tokens must never ship in client-side code, and cross-origin (CORS) support through the gateway may allow fewer headers than a server-to-server call. If you must call from the browser, validate that the exact headers you need are permitted for your origin first, and never expose a token to end users. See Token Safety.