Authentication

The NearSync public API lives at https://api.nearsync.tech. It is a curated, almost entirely read-only REST surface over your organization's Finance and CRM data, authenticated with an API key — not a user login. The single exception is lead intake, which lets your own tools send leads in. Every request is scoped to the organization that owns the key; a key can only ever read its own org's data.

Looking for the internal action API?

The {type: ...} action-dispatch calls the apps make internally are documented under Internal / Platform Reference. That surface is not a public contract and is not covered here.

Base URL

https://api.nearsync.tech/v1

All endpoints are versioned under /v1 and respond with JSON.

API keys

Keys look like ns_live_<id>_<secret> (or ns_test_… for test keys). Pass the key as a bearer token on every request:

curl https://api.nearsync.tech/v1/invoices?limit=10 \
  -H "Authorization: Bearer ns_live_d727wYWUohl8..."

Creating a key

1. In the admin dashboard, open System → API Keys (requires the api_access capability on your plan).
2. Click Create key, give it a name, and select the scopes it should carry.
3. The full key is shown once, at creation time. Copy it then — it is stored only as a hash and cannot be retrieved again. If you lose it, revoke it and mint a new one.

Revoking a key takes effect immediately: the next request with it returns 401.

Scopes

Each key carries a fixed set of scopes. An endpoint returns 403 if the key is missing the scope it requires. Today's scopes:

Scope	Grants
invoices:read	Read /v1/invoices, /v1/invoices/{id}
payments:read	Read /v1/payments
subscriptions:read	Read /v1/subscriptions
contacts:read	Read /v1/contacts, /v1/contacts/{id}
companies:read	Read /v1/companies
deals:read	Read /v1/deals
analytics:read	Read the metrics and insight endpoints
leads:write	Write. Create leads via POST /v1/leads — nothing else

leads:write is the only write scope on the API. A key holding it can create leads and can read nothing at all; reads require their own scopes.

Grant a key only the scopes it needs. The per-endpoint requirement is listed on each operation page in the API Reference.

Organization isolation

The key resolves to exactly one organization. Server-side, every query is filtered by that org id before it runs — the key has no way to widen its own scope or reach another tenant's data. This is enforced below the API layer, not by request parameters.

Pagination

List endpoints return at most 100 rows per page (default 50) and use an opaque cursor:

{
  "data": [ /* … */ ],
  "has_more": true,
  "next_cursor": "50"
}

Pass next_cursor back as the cursor query parameter to fetch the next page; next_cursor is null on the last page. Use limit (1–100) to size pages.

Errors

Errors are JSON and carry a request_id you can quote in support requests:

Status	Meaning
401	Missing, malformed, or revoked API key.
403	The key lacks the scope this endpoint requires (the response names the missing scope).
404	No such resource in the key's organization — or the path isn't an exposed /v1 resource.
429	Per-minute rate limit or monthly quota exceeded. See Rate Limits & Quota.

{ "error": "insufficient scope", "required": "payments:read", "request_id": "35ab5dc9-…" }

When you receive a 401, the key itself is the problem — re-check or rotate it; do not retry unchanged.