> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vlenseg.com/llms.txt.
> For full documentation content, see https://docs.vlenseg.com/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vlenseg.com/_mcp/server.

# API Conventions

This page documents conventions that apply to every Vlens endpoint — request format, response envelope, pagination, dates, and IDs.

***

## Base URL

```
https://api.vlenseg.com
```

All endpoints are relative to this URL. Tenants are isolated, so a non-production tenant can serve as a development environment.

***

## Headers

Every request requires:

| Header          | Required                      | Description                          |
| --------------- | ----------------------------- | ------------------------------------ |
| `ApiKey`        | Always                        | Tenant API key                       |
| `Authorization` | Most endpoints                | `Bearer <token>` — admin or user JWT |
| `Content-Type`  | `POST` / `PUT`                | Always `application/json`            |
| `TenancyName`   | `/api/credentials/Login` only | Your tenant name                     |

***

## Response envelope

Every response — success or error — uses the same shape:

```json
{
  "data": { ... },
  "error_code": null,
  "error_message": null,
  "error_descriptions": null
}
```

* On **success**, `data` contains the result and `error_code` is `null`
* On **error**, `data` is `null` and `error_code` / `error_message` describe the failure

Errors 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`.

### Paginated responses

List endpoints add `totalCount` and `returnedCount`:

```json
{
  "data": [ ... ],
  "totalCount": 247,
  "returnedCount": 20,
  "error_code": null
}
```

***

## Pagination

List endpoints accept these query parameters:

| Parameter        | Type    | Description                        |
| ---------------- | ------- | ---------------------------------- |
| `skipCount`      | integer | Number of records to skip (offset) |
| `MaxResultCount` | integer | Maximum records to return          |

**Example — fetch page 3 of 20:**

```bash
curl "https://api.vlenseg.com/api/BusinessRequest/CurrentList?skipCount=40&MaxResultCount=20" \
  -H "ApiKey: YOUR_API_KEY" \
  -H "Authorization: Bearer USER_TOKEN"
```

Use `totalCount` from the response to compute total pages: `Math.ceil(totalCount / MaxResultCount)`.

***

## IDs

| Resource            | Format         |
| ------------------- | -------------- |
| User ID             | 64-bit integer |
| Transaction ID      | UUID           |
| Business request ID | UUID           |
| OTP request ID      | UUID           |
| Refresh token       | JWT            |

UUIDs are lowercase with hyphens: `81f404b3-d7dc-4f08-b4fe-934853c86282`.

***

## Dates and times

Dates use **ISO 8601** in **UTC**:

```
2025-01-15T10:30:00Z
```

`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.

***

## Phone numbers

E.164 format with country code:

```
+201234567890
```

Egyptian numbers begin with `+20`.

***

## Geolocation

`geoLocation` fields use decimal latitude/longitude:

```json
{
  "latitude": 30.0444,
  "longitude": 31.2357
}
```

Required for contract creation and signing — Vlens uses the value to detect cross-region account movement (≥80 km triggers a liveness re-validation requirement).

***

## Multi-tenancy

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.