Founding Programme: five places, three months of Growth. Applications close 24 November.Apply for a place

Help · Data and security

Connect your other software with the Developer API

Create, change and archive contacts, companies, deals, leads and tasks from your own systems with an API key, and have nineloops tell them when things change.

Nobody replaces every tool on day one. The Developer API lets nineloops sit beside the software you already run: your website form can create a lead, your billing system can open a task, and a webhook can tell your own systems when a deal is won.

Make a key

  1. Open Settings, then Connections, and choose Open on Your own software. Owners and admins see it, and it opens the Developer page.
  2. Choose New key, give it a name, and pick the access for each app: no access, read, or read and write. CRM and Tasks take writes. Finance, HR and Social are read only.
  3. Copy the key. It starts with pk_ and is shown once. Only a hash of it is stored, so a lost key is revoked and replaced, not recovered.

Read

The base URL is shown at the top of the Developer API page. Send the key in the Authorization header. You can read contacts, companies, deals, leads, tasks, invoices, employees and social_posts, a page at a time (limit up to 200, with offset), newest first. Add id to read one record, or external_id to find the record you created with your own id.

curl "$BASE_URL?resource=contacts&limit=50" \
  -H "Authorization: Bearer $NINELOOPS_KEY"

Create

POST a JSON body to the resource. The answer is 201 with the new record. Send an Idempotency-Key header and a retry of the same request within 24 hours returns the first answer instead of making a second record. external_id is optional on contacts, companies, deals and tasks: it stores your own id on the record, and a second create with the same external_id is refused with the id of the record that already has it.

curl -X POST "$BASE_URL?resource=contacts" \
  -H "Authorization: Bearer $NINELOOPS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-4711" \
  -d '{"full_name": "Amira Haddad", "emails": ["amira@example.com"], "source": "Website", "external_id": "crm-4711"}'
  • contacts: full_name (required), emails, phones, title, company_id, owner_id, lifecycle_stage, source, tags.
  • companies: name (required), domain, industry, tier, owner_id, parent_company_id, tags.
  • deals: title (required), company_id, primary_contact_id, pipeline_id, stage_key, status (open, won or lost), amount_cents, currency, expected_close, owner_id, next_step, loss_reason, source, tags. With no pipeline the deal goes into your default pipeline at its first stage, in your workspace currency.
  • leads: full_name (required), email, company_name, phone, source, owner_id.
  • tasks: title and space_id (both required), project_id, description, status_key, priority (none, low, medium, high or urgent), start_at, due_at, assignee_ids, tags. The space must be a shared space, not someone's personal one.

A field that is not on these lists is refused with a 400 that names it, so a typo never passes silently. Every id you send, such as company_id, owner_id or space_id, must belong to the same workspace, and an owner or assignee must be an active member. Your workspace's own rules apply to records made through the API: a duplicate rule set to block API entries refuses a copy, a deal that needs approval cannot be marked won before it is approved, and playbooks run on new records about a minute later. A record created without owner_id has no owner until someone takes it.

Change

PATCH the resource with the record id and only the fields you want to change. A task's space, project and assignees and a deal's pipeline are set when the record is created and are not changed through the API.

curl -X PATCH "$BASE_URL?resource=deals&id=$DEAL_ID" \
  -H "Authorization: Bearer $NINELOOPS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status": "won", "amount_cents": 1250000}'

Archive

The API never deletes anything. DELETE archives the record, which takes it out of the working lists and keeps its history. PATCH with {"archived": false} brings it back.

curl -X DELETE "$BASE_URL?resource=contacts&id=$CONTACT_ID" \
  -H "Authorization: Bearer $NINELOOPS_KEY"

Limits and errors

  • Each key may make 600 calls a minute, of which 120 may be writes. Every answer carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset. Past the limit the answer is 429 with Retry-After.
  • A request body is 64 kB at most.
  • 400 means the body is wrong and names the field. 401 means the key is missing, wrong or revoked. 403 means the key lacks the scope, or the app is not on your plan. 402 means the workspace is locked for billing, and it can still be read. 404 means there is no such record in this workspace. 409 and 422 mean one of your workspace's own rules refused the write, and the message says which.

Webhooks

On the same page, add a webhook: an https URL you own, and the events you want. The signing secret starts with whsec_ and is shown once. The events are contact.created, contact.updated, company.created, company.updated, deal.created, deal.updated, deal.won, deal.lost, task.created, task.completed, invoice.created and invoice.paid. They fire whoever made the change: a person, an import, an AI employee or the API.

  • Each delivery is a POST with a JSON body: id, type, workspace_id, at and data, which is the record. A very large record is sent as its id with truncated set to true, and you read the rest through the API.
  • Deliveries usually leave within a minute or two. Answer with any 2xx status within five seconds. Anything else is retried five times, after 1 minute, 5 minutes, 15 minutes, 1 hour and 4 hours.
  • A webhook that fails 15 deliveries in a row is switched off, and the Developer page shows what your endpoint last answered. Switch it back on from its menu once the endpoint is fixed.
  • Private tasks, confidential tasks and tasks in a personal space are never sent.
  • Events can arrive more than once or out of order. X-nineloops-Delivery is the same on every retry of one delivery, so you can ignore a repeat.

Check the signature

Every delivery carries X-nineloops-Timestamp (seconds) and X-nineloops-Signature-V1, which is the HMAC-SHA256 of the timestamp, a full stop and the raw body, keyed with your signing secret and written in hex. Compute the same value over the raw body exactly as it arrived, compare, and refuse a timestamp more than five minutes old so a captured delivery cannot be replayed. X-nineloops-Signature, the SHA-256 of the secret, a full stop and the body, is still sent for receivers built before the timestamp existed.

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody is the request body as a string, before any JSON parsing.
export function isFromNineloops(rawBody, headers, secret) {
  const timestamp = headers["x-nineloops-timestamp"];
  const signature = headers["x-nineloops-signature-v1"];
  if (!timestamp || !signature) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest("hex");
  const a = Buffer.from(expected);
  const b = Buffer.from(String(signature));
  return a.length === b.length && timingSafeEqual(a, b);
}

Start free.

Free for up to five people. Every paid plan includes every app. Browser, Mac and iPhone.