Skip to main content

​
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, so these are all the same number:
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. 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 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.
  • 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.
Don’t put secrets or the one-time code in metadata. OTPBay stores it and sends it to your webhook URL.