API
Conventions
Formats for identifiers, dates, errors and limits across Voxlera's HTTP interfaces.
These conventions already apply to the public endpoints behind the website embeds, and the Voxlera API will follow them. Where a detail may still change before the API launches, it is marked.
Requests and responses
- Request and response bodies are JSON (
Content-Type: application/json), UTF-8. - Field names are camelCase, e.g.
firstName,preferredBand. - Unknown or invalid input is rejected, never silently corrected.
Identifiers
Resources are identified by UUIDs, e.g. 3f2c9a8e-1b7d-4c55-9e0a-6d2f1c0b7a14. Treat them as opaque strings: don’t parse them or rely on their ordering.
Embed tokens are a different thing: long, random, URL-safe strings that identify one clinic’s form. They are not resource IDs.
Dates and times
- Timestamps are ISO 8601 in UTC, e.g.
2026-09-27T08:30:00.000Z. - Where a value is a local wall-clock time (a clinic’s opening hours, a consultation time band), it is documented as such and paired with an IANA time zone name such as
Europe/Istanbul.
Phone numbers
Phone numbers are in E.164 format: a +, the country code, then the number, with no spaces or punctuation — e.g. +905321234567. Anything else is rejected.
Languages and countries
- Languages are two-letter ISO 639-1 codes:
en,tr,ru,de, … - Countries are two-letter ISO 3166-1 alpha-2 codes:
TR,DE,GB, …
Errors
Errors use standard HTTP status codes with a JSON body.
| Status | Meaning |
|---|---|
400 | The request is invalid. The body explains why. |
401 / 403 | Missing or insufficient credentials. |
404 | The resource or token doesn’t exist, or you can’t see it. |
429 | Too many requests. Wait and retry. |
5xx | Something went wrong on our side. Retry with backoff. |
A validation failure looks like this — issues lists each problem with the path to the field:
{
"message": "Validation failed",
"issues": [
{
"code": "invalid_string",
"path": ["phone"],
"message": "Invalid"
}
]
}
Other errors carry at least a human-readable message:
{ "statusCode": 404, "message": "Unknown consulting form token", "error": "Not Found" }
Note
Some errors also include a machine-readable code (for example validation_failed). The API will make code present on every error; until then, rely on the HTTP status and treat message as text for people, not for your code to parse.
Rate limits
Public endpoints are rate-limited per client and per clinic. When you exceed a limit you get 429 Too Many Requests. There are currently no rate-limit headers, so back off for at least a minute before retrying. The API’s limits and headers will be documented here when it launches.
Versioning
The public embed endpoints are not versioned and are not a supported integration point. The API will be versioned from its first release, so that changes which could break an integration only ship in a new version.