Programmable communications, one base URL.

Authentication #

ByondAPI uses two distinct credential types depending on which plane you're calling.

Data plane — X-API-Key

Verify and Lookup are data-plane endpoints. Authenticate them with a hashed API key sent in the X-API-Key header. A key is two parts joined by a dot — a public prefix and a secret:

X-API-Key: pk_live_8fa2.s3cr3t_9c1d4f7b2a6e0h8j

Key management — Authorization: Bearer

Creating, listing and revoking keys is a management-plane action performed by a signed-in console session. Those calls carry a short-lived session JWT in the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

From zero to verified #

Mint a key in the console, then start your first verification. Email and WhatsApp deliver today.

export BYONDAPI_KEY="pk_live_8fa2.s3cr3t_9c1d4f7b2a6e0h8j"

# start an email OTP — one POST, any channel
curl -X POST __BASE__/verify/start \
  -H "X-API-Key: $BYONDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "recipient": "[email protected]",
    "brand": "Acme",
    "code_length": 6
  }'

const res = await fetch("__BASE__/verify/start", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.BYONDAPI_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    channel: "email",
    recipient: "[email protected]",
    brand: "Acme",
    code_length: 6
  })
});
const { verification_id } = await res.json();

# confirm the 6-digit code
curl -X POST __BASE__/verify/check \
  -H "X-API-Key: $BYONDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_id": "vrf_3kZ9c1d4f7b21bQ",
    "code": "084213"
  }'

const res = await fetch("__BASE__/verify/check", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.BYONDAPI_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    verification_id: "vrf_3kZ9c1d4f7b21bQ",
    code: "084213"
  })
});
const { status } = await res.json(); // "approved"

Start a verification #

Generate and deliver a one-time code over the chosen channel. ByondAPI owns the code, the TTL and the retry/lockout logic — you never store a secret or run a timer.

Request body

Request

curl -X POST __BASE__/verify/start \
  -H "X-API-Key: $BYONDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "email",
    "recipient": "[email protected]",
    "brand": "Acme",
    "code_length": 6,
    "ttl_seconds": 300
  }'

const res = await fetch("__BASE__/verify/start", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.BYONDAPI_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    channel: "email",
    recipient: "[email protected]",
    brand: "Acme",
    code_length: 6,
    ttl_seconds: 300
  })
});
const data = await res.json();
console.log(data.verification_id, data.status);

{
  "verification_id": "vrf_3kZ9c1d4f7b21bQ",
  "channel": "email",
  "status": "pending",
  "expires_at": "2026-06-15T09:42:00Z"
}

Response fields

• verification_id — opaque handle you pass to /verify/check.
• channel — the channel the code was sent on (echoes the request).
• status — pending when delivery is in flight; channel_unavailable when the channel isn't serving yet.
• expires_at — RFC 3339 UTC timestamp after which the code is rejected.

Status values

Check a code #

Submit the code your user entered against the verification you started. ByondAPI compares, counts attempts, and locks after too many failures.

Request body

Request

curl -X POST __BASE__/verify/check \
  -H "X-API-Key: $BYONDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verification_id": "vrf_3kZ9c1d4f7b21bQ",
    "code": "084213"
  }'

const res = await fetch("__BASE__/verify/check", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.BYONDAPI_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    verification_id: "vrf_3kZ9c1d4f7b21bQ",
    code: "084213"
  })
});
const { status } = await res.json();
if (status === "approved") {
  // user is verified
}

{
  "verification_id": "vrf_3kZ9c1d4f7b21bQ",
  "status": "approved"
}

Status values

Number lookup #

Validate and normalize any phone number to E.164, with country, national format and line type. Clean your list before you spend on delivery.

Query parameters

Request

# validate & normalize a number
curl "__BASE__/lookup?number=+6591234567&country=SG" \
  -H "X-API-Key: $BYONDAPI_KEY"

const params = new URLSearchParams({
  number: "+6591234567",
  country: "SG"
});
const res = await fetch("__BASE__/lookup?" + params, {
  headers: { "X-API-Key": process.env.BYONDAPI_KEY }
});
const data = await res.json();
console.log(data.valid, data.line_type);

{
  "input": "+6591234567",
  "number_e164": "+6591234567",
  "valid": true,
  "possible": true,
  "country_code": "SG",
  "country": "Singapore",
  "national_format": "9123 4567",
  "line_type": "mobile",
  "source": "offline"
}

Response fields

• input — the raw value you sent, echoed back.
• number_e164 — canonical E.164 form, or null if unparseable.
• valid — boolean; the number is a real, dialable number for its region.
• possible — boolean; the digit count is plausible even if not provably valid.
• country_code — ISO 3166-1 alpha-2 region (e.g. SG).
• country — human-readable country name.
• national_format — locally formatted display string.
• line_type — mobile, fixed_line, voip, toll_free or unknown.
• source — always "offline" today (computed from an offline number-plan dataset).

Create an API key #

Mint a scoped, hashed key for your backend. This is a management-plane call — authenticate with a session Bearer token, not an API key.

Request body

Request

# mint a scoped key (session-authed)
curl -X POST __BASE__/api-keys \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend",
    "scopes": ["verify", "lookup"]
  }'

const res = await fetch("__BASE__/api-keys", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + jwt,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "prod-backend",
    scopes: ["verify", "lookup"]
  })
});
const data = await res.json();
// data.key is shown ONCE — store it now
console.log(data.key);

{
  "id": "key_7b2a6e0h8j",
  "name": "prod-backend",
  "key_prefix": "pk_live_8fa2",
  "scopes": ["verify", "lookup"],
  "created_at": "2026-06-15T09:40:00Z",
  "key": "pk_live_8fa2.s3cr3t_9c1d4f7b2a6e0h8j"
}

Scopes

Scopes constrain what a key can call. The data plane enforces them with a require_scope check on each request:

• NULL scopes — a key created without scopes is unrestricted and may call every data-plane endpoint.
• "verify" — permits /verify/start and /verify/check.
• "lookup" — permits /lookup.
• "*" — wildcard that grants every scope explicitly.

List API keys #

Enumerate the keys on your account. Secrets are never returned — only the safe key_prefix and metadata.

Request

curl __BASE__/api-keys \
  -H "Authorization: Bearer $JWT"

const res = await fetch("__BASE__/api-keys", {
  headers: { "Authorization": "Bearer " + jwt }
});
const { keys } = await res.json();

{
  "keys": [
    {
      "id": "key_7b2a6e0h8j",
      "name": "prod-backend",
      "key_prefix": "pk_live_8fa2",
      "scopes": ["verify", "lookup"],
      "created_at": "2026-06-15T09:40:00Z",
      "last_used_at": "2026-06-15T11:02:14Z"
    },
    {
      "id": "key_1f3d9a2c4e",
      "name": "marketing-lookup",
      "key_prefix": "pk_live_2c4e",
      "scopes": ["lookup"],
      "created_at": "2026-06-10T08:15:00Z",
      "last_used_at": null
    }
  ]
}

Revoke an API key #

Permanently revoke a key by its id. Revocation takes effect immediately — in-flight requests using that key start failing with 401.

Path parameter

Request

curl -X DELETE __BASE__/api-keys/key_7b2a6e0h8j \
  -H "Authorization: Bearer $JWT"

const res = await fetch("__BASE__/api-keys/key_7b2a6e0h8j", {
  method: "DELETE",
  headers: { "Authorization": "Bearer " + jwt }
});
const { revoked } = await res.json();

{
  "id": "key_7b2a6e0h8j",
  "revoked": true
}

Errors #

ByondAPI uses conventional HTTP status codes. 2xx means success; 4xx means the request was rejected and includes a machine-readable JSON body:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or revoked."
  }
}

Example bodies

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or revoked."
  }
}

{
  "error": {
    "code": "insufficient_scope",
    "message": "This key is not authorized for the 'verify' scope.",
    "required_scope": "verify"
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "One or more fields are invalid.",
    "fields": {
      "channel": "must be one of: sms, voice, whatsapp, email",
      "code_length": "must be between 4 and 10"
    }
  }
}

{
  "error": {
    "code": "rate_limited",
    "message": "Too many verifications for this recipient. Try again later.",
    "retry_after": 60
  }
}