Skip to main content
This page is the contract for what you can rely on in Nedzo API responses, and how we evolve those responses over time. It applies to every /v1/* endpoint.

​
Allow-listed responses

Every public response is built from an explicit allow-list of documented fields. A response contains the fields shown in that endpoint’s reference page — and nothing else. Concretely, this means:
  • Internal fields are never returned. We do not expose identifiers for our sub-processors or infrastructure (telephony, voice, LLM, RAG/knowledge-base, email, payment, and verification providers), internal feature flags, internal tokens or secrets, or our region-specific provider identifiers. These are implementation details that can change at any time without notice.
  • What you see is the whole contract. If a field is not documented on the endpoint’s reference page, do not depend on it — even if you observe it in a response during a transition. Treat undocumented fields as absent.
  • New fields may be added. We may add new documented fields to a response at any time. Write clients that ignore unknown fields rather than rejecting them.
Because internal provider identifiers are never exposed, you can build on the Nedzo API without coupling to the specific vendors we use behind the scenes. We can change providers — including using different processors per region for data-residency reasons — without breaking your integration.

​
Field stability

​
Deprecation & removal

Removing or renaming a documented field, or removing an endpoint, is a breaking change. We follow a fixed process:
  1. Pre-announcement in the changelog and to affected integrations.
  2. A deprecation window of at least 60 days during which the field or endpoint keeps working unchanged.
  3. Removal only after the sunset date passes.
During the window, every affected response carries standard HTTP headers so you can detect deprecations programmatically:
  • Deprecation (per the IETF deprecation-header draft) — when the deprecation took effect.
  • Sunset (RFC 8594) — the date on or after which the field/endpoint will be removed.
  • Link; rel="deprecation" — the changelog entry with migration guidance.
We recommend logging any response that carries a Sunset header so deprecations surface during your normal monitoring.

​
How we enforce this

The allow-list is enforced in code, not by review alone: every /v1/* response is serialized through a central allow-list, and a CI gate fails any build that introduces an internal-only field name into a public response, re-opens a response schema to arbitrary fields, or bypasses the allow-list serializer. This is why you can trust that the documented fields are exhaustive.