> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otpbay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# IDs and formats

> Phone numbers, IDs, amounts, timestamps and metadata in the OTPBay API.

## Requests

Send request bodies as JSON with `Content-Type: application/json`, up to 1 MB. Unknown fields are rejected with `422 INVALID_REQUEST_BODY`, which catches typos such as `"too"` instead of `"to"`.

## Phone numbers

Pass phone numbers in international format, starting with `+` and the country code. OTPBay validates the number and normalizes it to [E.164](https://en.wikipedia.org/wiki/E.164), so these are all the same number:

```text theme={null}
+14155552671
+1 415 555 2671
+1 (415) 555-2671
```

Responses and webhooks always return the E.164 form, `+14155552671`. Numbers without a country code, or numbers that can't exist, are rejected with `422 INVALID_REQUEST_BODY`.

## IDs

Every object has a `sid`: a two-letter prefix followed by 24 hexadecimal characters.

| Prefix | Object        | Example                      |
| ------ | ------------- | ---------------------------- |
| `VE`   | Verification  | `VE6650c3a1b2c3d4e5f6a7b8c9` |
| `SM`   | SMS           | `SM6650c4b7c2d3e4f5a6b7c8d9` |
| `TG`   | Telegram code | `TG6650c52ad3e4f5a6b7c8d9e0` |

Store `sid` values as strings. Using a `sid` with the wrong endpoint — for example an `SM` ID with a verification endpoint — fails with `400 INVALID_MESSAGE_SID`.

## Amounts

Prices in responses and webhooks (`cost`, `fee`) are US dollar amounts as strings with two decimals, such as `"0.02"`. Parse them as decimals, not floats.

The project `balance` from [Get project](/api-reference/project/get) is a number in US dollars, such as `24.37`.

## Timestamps

Timestamps are ISO 8601 strings in UTC with milliseconds, such as `2026-09-26T10:15:01.873Z`. Timestamps that haven't happened yet, such as `approved_at` on a pending verification, are `null`.

## Metadata

Every send request accepts `metadata`: your own key-value data, such as a user or order ID. OTPBay stores it and returns it in responses and webhooks, so you can match them to your records.

```json theme={null}
{
  "to": "+14155552671",
  "metadata": {
    "user_id": "usr_1042",
    "attempt": 2,
    "signup": true
  }
}
```

* At most 32 keys.
* Keys are 1–64 characters.
* Values are strings (up to 512 characters), numbers or booleans. Nested objects and arrays aren't allowed.

<Warning>
  Don't put secrets or the one-time code in `metadata`. OTPBay stores it and sends it to your webhook URL.
</Warning>