The REST API

NeoKivo's public API at /v1 lets any script or platform read deals and create records. Every endpoint, real request/response examples, and how errors look.

Updated 2026-07-06

The /v1 API is a small, stable surface for reading deals and creating deals or contacts from outside NeoKivo. It's the same API Zapier calls under the hood, so anything Zapier can trigger on or create, a script can too.

Base URL and auth

Setting	Value
Base URL	https://api.neokivo.com/v1 — the documented, canonical host
Auth header	Authorization: Bearer nk_live_...
Content type	application/json for POST bodies

Create a key on the API keys page. A key acts as its creator: it sees only the deals they can see, and can only do what their workspace role allows. See that page for the fail-closed rule when a key's creator leaves the workspace.

Endpoints

Method & path	Purpose
GET /v1/me	Connection test — returns the workspace id and name
GET /v1/deals	List recent deals, newest first, up to 100. Optional ?since=<ISO 8601> returns only deals created after that time
GET /v1/events/stage-changes	List recent stage-change events, newest first, up to 100
GET /v1/actions/due	List open next actions due today or earlier — deal-anchored or contact-anchored ("keep warm") — oldest-due first, up to 100
POST /v1/deals	Create a deal. Also the generic entry point other integrations use to create deals
POST /v1/contacts	Create a contact

Every list and create is scoped to what the key's creator can see and do. A deal private to someone else never appears, even in /v1/deals.

Examples

List deals

bash

curl https://api.neokivo.com/v1/deals \
  -H "Authorization: Bearer nk_live_YOUR_KEY"

json

{
  "deals": [
    {
      "id": "deal_9f2a",
      "title": "Northwind annual renewal",
      "valueCents": 480000,
      "status": "open",
      "source": "referral",
      "stageName": "Negotiation",
      "contactName": "Dana Reyes",
      "companyName": "Northwind Supply",
      "createdAt": "2026-06-20T09:12:00.000Z"
    }
  ]
}

The list response omits expectedCloseDate — it's a lighter shape than the single-deal response below.

Create a deal

You send names, not ids: the stage is matched by name (or the first stage, if omitted), the company is found or created, and the contact is matched by email or created from the name you give.

bash

curl -X POST https://api.neokivo.com/v1/deals \
  -H "Authorization: Bearer nk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Northwind annual renewal",
    "valueCents": 480000,
    "stageName": "Negotiation",
    "contactName": "Dana Reyes",
    "contactEmail": "dana@northwind.example",
    "companyName": "Northwind Supply",
    "expectedCloseDate": "2026-08-01"
  }'

json

{
  "deal": {
    "id": "deal_9f2a",
    "title": "Northwind annual renewal",
    "valueCents": 480000,
    "status": "open",
    "source": null,
    "stageName": "Negotiation",
    "contactName": "Dana Reyes",
    "companyName": "Northwind Supply",
    "expectedCloseDate": "2026-08-01",
    "createdAt": "2026-06-20T09:12:00.000Z"
  }
}

201 Created.

Create a contact

bash

curl -X POST https://api.neokivo.com/v1/contacts \
  -H "Authorization: Bearer nk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dana Reyes",
    "email": "dana@northwind.example",
    "phone": "+1 555 0142",
    "title": "VP Operations",
    "companyName": "Northwind Supply",
    "note": "Prefers async updates"
  }'

json

{
  "contact": {
    "id": "contact_4b1e",
    "name": "Dana Reyes",
    "email": "dana@northwind.example",
    "phone": "+1 555 0142",
    "title": "VP Operations",
    "companyId": "company_2c7f",
    "createdAt": "2026-06-20T09:12:00.000Z"
  }
}

201 Created. note is saved on the contact but not echoed back in the response.

Rate limits

There's no published per-key request quota. api.neokivo.com carries standard edge-level abuse protection, not an application-level counter you need to design around.

Errors

Every error is JSON with an error string; some also carry a code. HTTP status tells you what kind of problem it is.

Status	Meaning
400	Bad input — invalid JSON, or a field failed validation (e.g. "title: String must contain at least 1 character(s)")
401	Missing, malformed, or unrecognized API key
403	The key's creator can't do this (role permission), or the creator is gone — see API keys
402	Write blocked: the workspace is read-only (trial ended). Body includes "code": "UPGRADE_REQUIRED". Reads still work
404	Unknown /v1 path
500	Unexpected server error

json

{ "error": "Stage \"Discovery\" not found" }

A validation error from POST /v1/deals with an unknown stage name.

Spotted something out of date? Email hello@neokivo.com.