Versioning & Deprecation

Where the version lives

The version is a path segment, and it is the only place it appears:

https://api.zelnum.com/api/v1

There is one live version. Its identity in the OpenAPI document is 1.0.0; the path segment v1 is what you target. Response bodies deliberately do not repeat a version, so there is no second field to keep in sync.

How changes are classified

Class	Examples	Effect on you
Additive	A new endpoint, a new optional request field, a new response field, a new product in the catalog	None. No version bump, no action.
Behavioural	A new value inside an existing enum such as error_code or billing_status; a changed default	Usually none, but it can break exhaustive matching.
Breaking	Removing or renaming a field, changing a type, changing what a status means, requiring a new header	Requires a new version.
Contract	The documentation was wrong about what the API does	None — but see below.

Tolerate unknown enum values

Additive changes include new members of existing enums. A client that switches exhaustively over status, error_code or billing_status and throws on an unrecognised value will break on a change that was, by policy, non-breaking.

Treat an unknown value as a distinct-but-valid case: log it, and fall back to the generic handling for that class of outcome. The safest default for an unknown error_code is the one this documentation gives internal_error — the outcome is uncertain, so retry with the same Idempotency-Key.

When the documentation changes

Documentation is corrected in place when the API’s behaviour was misdescribed. That is a documentation change, not a contract change: the API did not move, the description did. Because a correction is exactly the event you cannot see in a changelog entry of the form “nothing changed”, corrections are listed explicitly in the changelog.

If a correction changes something you had built against, it appears there as a note rather than a silent edit.

Deprecation policy

When an operation is deprecated it is marked deprecated: true in the OpenAPI document, and this site documents the replacement. The operation keeps working for the notice period, and the notice period is stated where the deprecation is announced.

A deprecation is never the same release as its replacement’s introduction. Both are live at once, so you can migrate on your own schedule rather than during an incident.

The one current deprecation

POST /v1/realtime/detect is retained for pre-release clients and is marked deprecated in the contract. New integrations should use the series-specific endpoints.

It is a rename, not a redesign — the request body and the response are the same shape:

	Legacy	Current
Endpoint	POST /v1/realtime/detect	POST /v1/realtime/check/phone or POST /v1/realtime/check/email
Series	Implied by the products you send	Explicit in the path, and it must match them
Products field	products (alias)	product_ids
Idempotency-Key	Required	Required

Migrating is a two-line change:

# Before
curl -X POST "https://api.zelnum.com/api/v1/realtime/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","products":[47]}'

# After — the series moves into the path and the field is renamed
curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","product_ids":[47]}'

Sending both product_ids and products in one request is rejected as 400 invalid_realtime_request, so the two must not be mixed during a staged rollout.

No sunset date is published

The contract marks the endpoint deprecated but does not yet carry a removal date, so this documentation cannot state one. Migrate now — the change is a path and a field name, and there is no behaviour to re-test.

Next

• OpenAPI — the machine-readable contract, including the deprecated flag
• Changelog — what changed, and when