API Conventions
Common patterns used across every Vlens endpoint
This page documents conventions that apply to every Vlens endpoint — request format, response envelope, pagination, dates, and IDs.
All endpoints are relative to this URL. Tenants are isolated, so a non-production tenant can serve as a development environment.
Every request requires:
Every response — success or error — uses the same shape:
data contains the result and error_code is nulldata is null and error_code / error_message describe the failureErrors are signalled in the envelope, not the HTTP status. Always inspect error_code before treating a response as successful — it may be set even when the HTTP status is 200.
List endpoints add totalCount and returnedCount:
List endpoints accept these query parameters:
Example — fetch page 3 of 20:
Use totalCount from the response to compute total pages: Math.ceil(totalCount / MaxResultCount).
UUIDs are lowercase with hyphens: 81f404b3-d7dc-4f08-b4fe-934853c86282.
Dates use ISO 8601 in UTC:
userDeviceUtcTime fields should reflect the user’s device clock in UTC — not local time. This value is used together with geoLocation for the contract-activation location check.
E.164 format with country code:
Egyptian numbers begin with +20.
geoLocation fields use decimal latitude/longitude:
Required for contract creation and signing — Vlens uses the value to detect cross-region account movement (≥80 km triggers a liveness re-validation requirement).
The Vlens platform is multi-tenant. Your ApiKey and admin credentials are scoped to a single tenant — they cannot access data from another tenant.
When using /api/credentials/Login, pass your tenant name in both the request body (tenancyName) and as the TenancyName header.