Skip to main content
The Vobiz REST API is versioned in the URL path. The current version is v1, and every request carries it:
The version lives entirely in the path, so an integration pinned to /api/v1 keeps talking to v1 until you change the URL yourself. Pinning is the only version control you need - the URL you deploy is the contract you get.

​
Compatibility contract

Vobiz ships changes to v1 continuously. Anything on the additive list can appear in v1 at any time, without notice, so build your client to tolerate it. Anything on the breaking list goes through the deprecation lifecycle instead.

​
Additive changes

​
Breaking changes

Ignore unknown response fields. Parse responses leniently: read the keys you need and skip the ones you do not recognise. Clients that reject unexpected keys - strict schema validators, generated models with “additional properties” turned off, exhaustive switch statements over enum values - break on additive changes that are safe by design.

​
Deprecation lifecycle

A breaking change to v1 moves through four stages.
1

Announced

The change is documented. The affected field or endpoint keeps working exactly as before, and the docs name the replacement.
2

Deprecated

The resource is marked deprecated in the OpenAPI specification and, where it applies to a whole endpoint, responses carry a Deprecation header. Behaviour is unchanged - the marker is a signal to migrate.
3

Sunset

A removal date is set and published in the Sunset header alongside Deprecation. The resource still works up to that date.
4

Removed

The field or endpoint is gone. Requests that depend on it fail - see Error Handling for the response shape.
Vobiz keeps a deprecated endpoint available for a minimum of [N] months between the sunset announcement and removal, so you have a defined window to migrate.

​
Deprecation and Sunset headers

When an endpoint enters the deprecation lifecycle, Vobiz signals it with two standard HTTP response headers. They use different formats - do not parse them the same way.
In the example above, @1751327999 is Mon, 30 Jun 2025 23:59:59 GMT and the sunset follows a year later. A Deprecation value in the future means the endpoint is scheduled for deprecation and is not deprecated yet. Treat both headers as advisory metadata: log them, alert on them, and keep processing the response body normally. No v1 endpoint carries a sunset date today.
Every v1 response goes through the same auth path regardless of deprecation state. See Authentication for the required headers.

​
Currently deprecated

Three request properties on POST /api/v1/Account/{auth_id}/trunks are marked deprecated in the OpenAPI specification. They still work; new integrations should use the replacements. credential_uuid attaches an existing SIP credential (username, password, realm) by UUID, and ipacl_uuid attaches an existing IP access-control list. Create those resources first, then pass their UUIDs. See Create a Trunk, SIP credentials, and IP access control lists.

​
Staying current

  • Generate your client from the OpenAPI specification and regenerate it periodically - deprecated: true markers surface as deprecation warnings in most generators.
  • Keep response parsing lenient so additive changes land without a deploy.
  • Watch for Deprecation and Sunset headers in your HTTP client middleware and surface them in your logs.
  • Check the Vobiz status page for live service availability.