Introduction

This page covers the mechanics you need before writing any request: the base URL, authentication, how to filter and page through results, and the difference between deleting and archiving.

The Zero API is currently in beta. Contact the Zero team to request access.

Base URL

All API requests should be made to:

https://api.zero.inc

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer <your-api-token>

Create a key in Settings → Connections → API keys: under Personal API keys, Generate API key, then a name and an expiry. Copy it when it appears — you will not see it again. The same page shows the Workspace ID you pass as workspaceId.

Quick Start

Two requests to get oriented:

1

Get your workspace ID

Everything else needs a workspace ID, so fetch yours first:

curl -X GET "https://api.zero.inc/api/workspaces?fields=id,name" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

2

Use the workspace ID in requests

Then pass it along:

curl -X GET "https://api.zero.inc/api/companies?workspaceId=WORKSPACE_UUID&limit=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Query Parameters

All GET endpoints support the following query parameters for filtering and pagination:

Parameter	Type	Default	Description
fields	string	* (all)	Comma-separated list of fields to return
where	JSON string	—	Filter conditions
limit	number	100	Maximum records to return
offset	number	0	Pagination offset
orderBy	JSON string	—	Sort order, e.g. {"name":"asc"}
groupBy	string	—	Comma-separated list of fields to group by

Selecting Fields

Ask only for the fields you need:

curl "https://api.zero.inc/api/contacts?fields=id,name,email,title"

Including Related Data

Dot notation in fields pulls in related objects: name one field (company.name) or use .* for the whole thing (quotes.*). To-one relations come back as an object, to-many as an array.

# Get contacts with their company information
curl "https://api.zero.inc/api/contacts?fields=id,name,email,company.name,company.domain"

# Get deals with company and contacts
curl "https://api.zero.inc/api/deals?fields=id,name,value,company.name,contacts.name"

Filtering with where

where takes a JSON string:

curl 'https://api.zero.inc/api/companies?where={"workspaceId":"your-workspace-uuid"}'

Top-level conditions are combined with AND; use $or for OR. Which operators apply depends on the field type — $eq, $not, $in, $contains, $startsWith, $exists for text, $gt / $gte / $lt / $lte for numbers and dates, $includes for array fields. Date filters also accept relative macros such as -7d or now(). The API Reference lists the full set for each field type.

Sorting with orderBy

Sort with orderBy:

curl 'https://api.zero.inc/api/deals?orderBy={"value":"desc"}'

Response Format

Every endpoint returns the same shape:

{
  "data": [...],
  "total": 42
}

For a single record — create, update — data is the record itself:

{
  "data": {
    "id": "uuid",
    "name": "Acme Inc"
  }
}

Deleting Records

Deleting comes in two flavours, and archiving is almost always the one you want:

# Soft delete (archive) - record can be recovered
curl -X DELETE "https://api.zero.inc/api/companies/COMPANY_UUID?archive=true" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# Hard delete - permanent removal
curl -X DELETE "https://api.zero.inc/api/companies/COMPANY_UUID" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Archived records keep their history and can be restored by setting archived back to false. A hard delete cannot be undone.