# Pipeline Stages Manage the stages within a pipeline. Each stage has a type, order, and optional confidence score. ## List pipeline stages > Returns pipeline stages. Filter by pipeline using \`{"pipelineId": "\"}\` or by workspace using \`{"workspaceId": "\"}\`.\ > \ > Stages are returned in \`order\` ascending by default, which reflects their position in the pipeline.\ > \ > \### Stage types\ > \ > \| Type | Description |\ > \|------|-------------|\ > \| \`lead\` | Entry stage for new leads |\ > \| \`in-progress\` | Active sales stages |\ > \| \`won\` | Terminal stage — deal closed successfully |\ > \| \`lost\` | Terminal stage — deal lost |\ > \| \`null\` | Unclassified stage |\ > \ > \> \*\*Tip:\*\* Always retrieve stages before creating or updating deals so you can resolve stage names to their UUIDs.
````json {"openapi":"3.0.3","info":{"title":"Zero API","version":"1.9.5"},"tags":[{"name":"Pipeline Stages","description":"Manage the stages within a pipeline. Each stage has a type, order, and optional confidence score."}],"servers":[{"url":"https://api.zero.inc","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"All API requests require a Bearer token in the Authorization header. Contact the Zero team to obtain your API token."}},"parameters":{"fields":{"name":"fields","in":"query","description":"Comma-separated list of fields to return. Defaults to all fields.","schema":{"type":"string"}},"where":{"name":"where","in":"query","description":"JSON-encoded filter object. All top-level conditions are combined with AND logic. Use `$or` for OR logic.\n\nThe available operators depend on the **data type** of the field you are filtering on.\n\n---\n\n## String fields\nFields like `name`, `domain`, `description`, `linkedin`, `source`, `externalId`, `location`.\n\n| Operator | Description | Example |\n|----------|-------------|---------|\n| *(exact)* | Exact match | `{\"name\": \"Linear\"}` |\n| `$eq` | Explicit exact match | `{\"name\": {\"$eq\": \"Linear\"}}` |\n| `$not` | Not equal | `{\"source\": {\"$not\": \"import\"}}` |\n| `$in` | Matches any value in array | `{\"domain\": {\"$in\": [\"linear.app\", \"granola.so\"]}}` |\n| `$notIn` | Matches none of the values | `{\"source\": {\"$notIn\": [\"import\", \"api\"]}}` |\n| `$contains` | Case-insensitive word-boundary substring match | `{\"name\": {\"$contains\": \"YC\"}}` |\n| `$notContains` | Does not contain | `{\"name\": {\"$notContains\": \"Test\"}}` |\n| `$containsAny` | Contains any of the given strings | `{\"name\": {\"$containsAny\": [\"YC\", \"Techstars\"]}}` |\n| `$startsWith` | Starts with prefix | `{\"domain\": {\"$startsWith\": \"app.\"}}` |\n| `$endsWith` | Ends with suffix | `{\"email\": {\"$endsWith\": \"@zero.inc\"}}` |\n| `$exists` | Field is present and truthy | `{\"linkedin\": {\"$exists\": true}}` |\n| `$notExists` | Field is absent, null, or empty | `{\"linkedin\": {\"$notExists\": true}}` |\n\n---\n\n## Number fields\nFields like `value`, `confidence`.\n\n| Operator | Description | Example |\n|----------|-------------|---------|\n| *(exact)* | Exact match | `{\"value\": 5000}` |\n| `$eq` | Explicit exact match | `{\"value\": {\"$eq\": 5000}}` |\n| `$not` | Not equal | `{\"value\": {\"$not\": 0}}` |\n| `$gt` | Greater than | `{\"value\": {\"$gt\": 10000}}` |\n| `$gte` | Greater than or equal | `{\"value\": {\"$gte\": 5000}}` |\n| `$lt` | Less than | `{\"value\": {\"$lt\": 10000}}` |\n| `$lte` | Less than or equal | `{\"value\": {\"$lte\": 50000}}` |\n| `$in` | Matches any value in array | `{\"confidence\": {\"$in\": [0.25, 0.5, 0.75]}}` |\n| `$notIn` | Matches none of the values | `{\"confidence\": {\"$notIn\": [0, 1]}}` |\n| `$exists` | Field is present and truthy | `{\"value\": {\"$exists\": true}}` |\n| `$notExists` | Field is absent, null, or zero | `{\"value\": {\"$notExists\": true}}` |\n\nMultiple operators can be combined on one field:\n```json\n{\"value\": {\"$gte\": 5000, \"$lt\": 10000}}\n```\n\n---\n\n## Date fields\nFields like `closeDate`, `startDate`, `endDate`, `createdAt`, `updatedAt`.\n\nValues can be ISO 8601 strings (`\"2026-01-01\"`, `\"2026-01-01T00:00:00Z\"`) or **relative time macros**.\n\n**Relative time macros:** `+Nd` / `-Nd` (days), `+Nw` / `-Nw` (weeks), `+Nm` / `-Nm` (months), `+Ny` / `-Ny` (years), `+Nh` / `-Nh` (hours), `+Ns` / `-Ns` (seconds), `now()`.\n\n| Operator | Description | Example |\n|----------|-------------|---------|\n| `$gte` | On or after | `{\"closeDate\": {\"$gte\": \"2026-01-01\"}}` |\n| `$lte` | On or before | `{\"closeDate\": {\"$lte\": \"2026-03-31\"}}` |\n| `$gt` | After | `{\"createdAt\": {\"$gt\": \"2026-01-01T00:00:00Z\"}}` |\n| `$lt` | Before | `{\"createdAt\": {\"$lt\": \"now()\"}}` |\n| `$date` | Exact date match (compares date portion only) | `{\"closeDate\": {\"$date\": \"2026-01-15\"}}` |\n| `$exists` | Field is present and truthy | `{\"closeDate\": {\"$exists\": true}}` |\n| `$notExists` | Field is absent or null | `{\"closeDate\": {\"$notExists\": true}}` |\n\nDate range example:\n```json\n{\"closeDate\": {\"$gte\": \"2026-01-01\", \"$lte\": \"2026-03-31\"}}\n```\nRelative date example (closing in next 30 days):\n```json\n{\"closeDate\": {\"$gte\": \"now()\", \"$lte\": \"+30d\"}}\n```\n\n---\n\n## Array fields\nFields like `listIds`, `ownerIds`, `contactIds`.\n\n| Operator | Description | Example |\n|----------|-------------|---------|\n| `$includes` | Array contains the given value (use this — bare exact match is not supported) | `{\"listIds\": {\"$includes\": \"\"}}` |\n| `$notIncludes` | Array does not contain the given value | `{\"ownerIds\": {\"$notIncludes\": \"\"}}` |\n| `$overlaps` | Array contains at least one of the given values | `{\"ownerIds\": {\"$overlaps\": [\"\", \"\"]}}` |\n| `$notOverlaps` | Array contains none of the given values | `{\"listIds\": {\"$notOverlaps\": [\"\", \"\"]}}` |\n| `$all` | Array contains all of the given values | `{\"listIds\": {\"$all\": [\"\", \"\"]}}` |\n| `$length` | Filter by array length (supports nested operators) | `{\"contactIds\": {\"$length\": {\"$gte\": 2}}}` |\n| `$exists` | Field is present and non-empty | `{\"ownerIds\": {\"$exists\": true}}` |\n| `$notExists` | Field is absent or empty | `{\"ownerIds\": {\"$notExists\": true}}` |\n\n---\n\n## UUID / ID fields\nFields like `id`, `workspaceId`, `companyId`, `stage`.\n\n| Operator | Description | Example |\n|----------|-------------|---------|\n| *(exact)* | Exact match | `{\"stage\": \"\"}` |\n| `$in` | Matches any value in array | `{\"stage\": {\"$in\": [\"\", \"\"]}}` |\n| `$notIn` | Matches none of the values | `{\"stage\": {\"$notIn\": [\"\"]}}` |\n| `$not` | Not equal | `{\"stage\": {\"$not\": \"\"}}` |\n\n---\n\n## Boolean fields\nFields like `archived`.\n\n| Operator | Description | Example |\n|----------|-------------|---------|\n| *(exact)* | Exact match | `{\"archived\": false}` |\n| `$not` | Not equal | `{\"archived\": {\"$not\": true}}` |\n\n---\n\n## Logical operators\nThese work across all data types.\n\n`$or` — matches if **any** sub-condition is true:\n```json\n{\n \"workspaceId\": \"\",\n \"$or\": [\n {\"ownerIds\": {\"$overlaps\": [\"\", \"\"]}},\n {\"closeDate\": {\"$gte\": \"2026-01-01\"}}\n ]\n}\n```\n\n`$and` — matches if **all** sub-conditions are true (useful when you need multiple conditions on the same field):\n```json\n{\n \"$and\": [\n {\"name\": {\"$contains\": \"Enterprise\"}},\n {\"name\": {\"$notContains\": \"Test\"}}\n ]\n}\n```\n\n---\n\n## Dot-notation (relation filtering)\nUse dot-syntax to filter records based on properties of related objects:\n```json\n{\"company.name\": \"Linear\"}\n{\"company.domain\": {\"$in\": [\"linear.app\", \"granola.so\"]}}\n{\"company.location.city\": \"San Francisco\"}\n{\"companyProfile.categories\": {\"$overlaps\": [\"Sales\", \"Marketing\"]}}\n```\nAll operators available for the target field's data type can be used with dot-notation.\n\n---\n\n## Custom property filtering\nCustom properties are stored in the `custom` object on records, keyed by UUID. Use `GET /api/columns` to discover the available custom property IDs, types, and options for a workspace.\n\nFilter on custom properties using `custom.` with operators appropriate for the column's type.\n\n> **Note:** For `select` and `multiselect` columns, option values are UUIDs (the `key` field from the column's `options` array). Use the UUID, not the human-readable name.\n\n```json\n// Text custom property\n{\"custom.54e1ca7d-69c3-4b77-8266-8085b5834116\": {\"$contains\": \"enterprise\"}}\n\n// Select custom property (use the option key UUID)\n{\"custom.a1b2c3d4-e5f6-7890-abcd-ef1234567890\": \"3e839b5c-b311-4887-b2da-727d2d75cdd6\"}\n\n// Multi-select custom property (use option key UUIDs)\n{\"custom.b2c3d4e5-f6a7-8901-bcde-f12345678901\": {\"$overlaps\": [\"a1b1c1d1-e1f1-1111-aaaa-111111111111\", \"b2b2c2d2-e2f2-2222-bbbb-222222222222\"]}}\n\n// Currency/number custom property\n{\"custom.c3d4e5f6-a7b8-9012-cdef-123456789012\": {\"$gte\": 100000}}\n\n// Date custom property\n{\"custom.d4e5f6a7-b8c9-0123-defa-234567890123\": {\"$gte\": \"2026-01-01\"}}\n\n// Boolean custom property\n{\"custom.e5f6a7b8-c9d0-1234-efab-345678901234\": true}\n\n// Check if custom property has a value\n{\"custom.f6a7b8c9-d0e1-2345-fabc-456789012345\": {\"$exists\": true}}\n```\n\n---\n\n## Complex example\nAll top-level keys are ANDed together:\n```json\n{\n \"name\": {\"$contains\": \"Zero\"},\n \"location.city\": \"Helsinki\",\n \"location.country\": {\"$in\": [\"United Kingdom\", \"Germany\", \"Sweden\"]},\n \"value\": {\"$gte\": 10000},\n \"closeDate\": {\"$gte\": \"2026-01-01\", \"$lte\": \"2026-03-31\"},\n \"ownerIds\": {\"$includes\": \"\"},\n \"stage\": {\"$in\": [\"\", \"\"]},\n \"lastActivity\": {\"$exists\": true},\n \"companyProfile.categories\": {\"$overlaps\": [\"Sales\", \"Marketing\"]},\n \"custom.54e1ca7d-69c3-4b77-8266-8085b5834116\": {\"$contains\": \"enterprise\"}\n}\n```\n","schema":{"type":"string"}},"limit":{"name":"limit","in":"query","description":"Maximum number of records to return","schema":{"type":"integer","default":100}},"offset":{"name":"offset","in":"query","description":"Pagination offset","schema":{"type":"integer","default":0}},"orderBy":{"name":"orderBy","in":"query","description":"JSON string for sort order","schema":{"type":"string"}}},"schemas":{"PipelineStage":{"type":"object","description":"A stage within a pipeline. Deals move through stages as they progress.","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"pipelineId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"description":"Semantic type of the stage.\n- `lead` — entry stage\n- `in-progress` — active stage\n- `won` — terminal success stage\n- `lost` — terminal loss stage\n- `null` — unclassified\n","enum":["lead","in-progress","won","lost",null]},"confidence":{"type":"string","nullable":true,"description":"Win probability for deals in this stage (0.0–1.0). Only meaningful when `confidenceEnabled` is true on the pipeline."},"icon":{"type":"string","nullable":true},"color":{"type":"string","nullable":true,"description":"Hex color code"},"order":{"type":"integer","description":"Display order within the pipeline (ascending)"},"archived":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"responses":{"Unauthorized":{"description":"Authentication failed or token is invalid/expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"paths":{"/api/pipelineStages":{"get":{"tags":["Pipeline Stages"],"summary":"List pipeline stages","description":"Returns pipeline stages. Filter by pipeline using `{\"pipelineId\": \"\"}` or by workspace using `{\"workspaceId\": \"\"}`.\n\nStages are returned in `order` ascending by default, which reflects their position in the pipeline.\n\n### Stage types\n\n| Type | Description |\n|------|-------------|\n| `lead` | Entry stage for new leads |\n| `in-progress` | Active sales stages |\n| `won` | Terminal stage — deal closed successfully |\n| `lost` | Terminal stage — deal lost |\n| `null` | Unclassified stage |\n\n> **Tip:** Always retrieve stages before creating or updating deals so you can resolve stage names to their UUIDs.\n","operationId":"listPipelineStages","parameters":[{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/where"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"},{"$ref":"#/components/parameters/orderBy"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PipelineStage"}},"total":{"type":"integer"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```` ## Create a pipeline stage > Create a new stage within an existing pipeline. ```json {"openapi":"3.0.3","info":{"title":"Zero API","version":"1.9.5"},"tags":[{"name":"Pipeline Stages","description":"Manage the stages within a pipeline. Each stage has a type, order, and optional confidence score."}],"servers":[{"url":"https://api.zero.inc","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"All API requests require a Bearer token in the Authorization header. Contact the Zero team to obtain your API token."}},"schemas":{"PipelineStageCreate":{"type":"object","required":["workspaceId","pipelineId","name"],"properties":{"workspaceId":{"type":"string","format":"uuid"},"pipelineId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"enum":["lead","in-progress","won","lost"]},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Win probability (0.0–1.0)"},"icon":{"type":"string"},"color":{"type":"string"},"order":{"type":"integer"}}},"PipelineStage":{"type":"object","description":"A stage within a pipeline. Deals move through stages as they progress.","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"pipelineId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"description":"Semantic type of the stage.\n- `lead` — entry stage\n- `in-progress` — active stage\n- `won` — terminal success stage\n- `lost` — terminal loss stage\n- `null` — unclassified\n","enum":["lead","in-progress","won","lost",null]},"confidence":{"type":"string","nullable":true,"description":"Win probability for deals in this stage (0.0–1.0). Only meaningful when `confidenceEnabled` is true on the pipeline."},"icon":{"type":"string","nullable":true},"color":{"type":"string","nullable":true,"description":"Hex color code"},"order":{"type":"integer","description":"Display order within the pipeline (ascending)"},"archived":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"responses":{"Unauthorized":{"description":"Authentication failed or token is invalid/expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"paths":{"/api/pipelineStages":{"post":{"tags":["Pipeline Stages"],"summary":"Create a pipeline stage","description":"Create a new stage within an existing pipeline.","operationId":"createPipelineStage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineStageCreate"}}}},"responses":{"200":{"description":"Pipeline stage created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PipelineStage"},"sideEffects":{"type":"array","items":{}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Get a pipeline stage > Retrieve a single pipeline stage by ID. ```json {"openapi":"3.0.3","info":{"title":"Zero API","version":"1.9.5"},"tags":[{"name":"Pipeline Stages","description":"Manage the stages within a pipeline. Each stage has a type, order, and optional confidence score."}],"servers":[{"url":"https://api.zero.inc","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"All API requests require a Bearer token in the Authorization header. Contact the Zero team to obtain your API token."}},"schemas":{"PipelineStage":{"type":"object","description":"A stage within a pipeline. Deals move through stages as they progress.","properties":{"id":{"type":"string","format":"uuid"},"workspaceId":{"type":"string","format":"uuid"},"pipelineId":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"description":"Semantic type of the stage.\n- `lead` — entry stage\n- `in-progress` — active stage\n- `won` — terminal success stage\n- `lost` — terminal loss stage\n- `null` — unclassified\n","enum":["lead","in-progress","won","lost",null]},"confidence":{"type":"string","nullable":true,"description":"Win probability for deals in this stage (0.0–1.0). Only meaningful when `confidenceEnabled` is true on the pipeline."},"icon":{"type":"string","nullable":true},"color":{"type":"string","nullable":true,"description":"Hex color code"},"order":{"type":"integer","description":"Display order within the pipeline (ascending)"},"archived":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}}},"responses":{"Unauthorized":{"description":"Authentication failed or token is invalid/expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"paths":{"/api/pipelineStages/{stageId}":{"get":{"tags":["Pipeline Stages"],"summary":"Get a pipeline stage","description":"Retrieve a single pipeline stage by ID.","operationId":"getPipelineStage","parameters":[{"name":"stageId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PipelineStage"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Delete a pipeline stage > Permanently delete a pipeline stage. Returns \`{"data": 1}\` on success, \`{"data": 0}\` if not found.\ > \ > \> \*\*Warning:\*\* Deleting a stage will affect all deals currently assigned to it.
```json {"openapi":"3.0.3","info":{"title":"Zero API","version":"1.9.5"},"tags":[{"name":"Pipeline Stages","description":"Manage the stages within a pipeline. Each stage has a type, order, and optional confidence score."}],"servers":[{"url":"https://api.zero.inc","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"All API requests require a Bearer token in the Authorization header. Contact the Zero team to obtain your API token."}},"responses":{"Unauthorized":{"description":"Authentication failed or token is invalid/expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"paths":{"/api/pipelineStages/{stageId}":{"delete":{"tags":["Pipeline Stages"],"summary":"Delete a pipeline stage","description":"Permanently delete a pipeline stage. Returns `{\"data\": 1}` on success, `{\"data\": 0}` if not found.\n\n> **Warning:** Deleting a stage will affect all deals currently assigned to it.\n","operationId":"deletePipelineStage","parameters":[{"name":"stageId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Deletion result","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"integer","description":"`1` if deleted, `0` if not found"},"sideEffects":{"type":"array","items":{}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ``` ## Update a pipeline stage > Update an existing pipeline stage. Returns only the changed fields. ```json {"openapi":"3.0.3","info":{"title":"Zero API","version":"1.9.5"},"tags":[{"name":"Pipeline Stages","description":"Manage the stages within a pipeline. Each stage has a type, order, and optional confidence score."}],"servers":[{"url":"https://api.zero.inc","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"All API requests require a Bearer token in the Authorization header. Contact the Zero team to obtain your API token."}},"schemas":{"PipelineStageUpdate":{"type":"object","properties":{"name":{"type":"string"},"description":{"type":"string","nullable":true},"type":{"type":"string","nullable":true,"enum":["lead","in-progress","won","lost"]},"confidence":{"type":"number","minimum":0,"maximum":1},"icon":{"type":"string"},"color":{"type":"string"},"order":{"type":"integer"}}}},"responses":{"Unauthorized":{"description":"Authentication failed or token is invalid/expired","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"}}}}}}}},"paths":{"/api/pipelineStages/{stageId}":{"patch":{"tags":["Pipeline Stages"],"summary":"Update a pipeline stage","description":"Update an existing pipeline stage. Returns only the changed fields.","operationId":"updatePipelineStage","parameters":[{"name":"stageId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PipelineStageUpdate"}}}},"responses":{"200":{"description":"Stage updated. Only changed fields are returned in `data`.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object"},"sideEffects":{"type":"array","items":{}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}} ```