Create a verify code

POST

/verify_codes

Initiates a verification process by creating a new verify code with a specified routing strategy.

Authorizations

token

Request Body^required

application/json

Verify code write payload. Creates a new verification code request with a multi-step routing strategy.

object

phone

required

Recipient phone number in international format (e.g. +491701234567).

string

>= 5 characters <= 30 characters

code

Custom verification code. If not provided, a random numeric code is generated automatically based on code_length.

string | null

>= 4 characters <= 8 characters

code_length

Length of the auto-generated verification code. Used only when code is not provided. Default: 4.

integer | null

default: 4 >= 4 <= 8

lang

Language for the default message template. Determines the language of the auto-generated SMS/Voice text when no custom template is provided. Not applicable for the telegram channel — Telegram always sends a system message in the language of the user’s Telegram app.

string

default: DE

Allowed values: EN DE FR IT ES PL NL RO PT CS HU SV DA FI SK HR TR RU BG UK

payload

Custom data that will be stored with the verification code and returned in webhook events. Useful for correlating verification requests with your internal systems.

string | null

<= 128 characters

is_code_deleted

If true, the verification code will be deleted from storage after it has been sent to the recipient. Default: false.

boolean | null

routing_strategy

required

Ordered list of delivery channels. Each step defines a channel to attempt. If a channel fails or times out, the next step is tried. At least one step is required. The sms channel can only be the last step. Duplicate channels are not allowed.

Array<object>

object

channel

required

Delivery channel for this step.

string

Allowed values: telegram voice sms

timeout_sec

Time in seconds to wait for a response from this channel before falling back to the next step. Only applicable for the telegram channel. If not set, a system default is used.

integer | null

default: 30 >= 30 <= 3600

sender_id

Sender identifier for SMS and Voice channels. For SMS, this is the sender phone number or alphanumeric ID displayed on the recipient’s device. Validated against your account’s allowed sender IDs.

string | null

template

Custom message template for sms or voice channels. Use {{code}} as a placeholder for the verification code. If not provided, a default translated template is used based on the lang field. For voice channel, the text is automatically wrapped in SSML <speak> tags. Ignored for telegram channel.

string | null

<= 70 characters

Examples

Verify code with multi-channel routing

Create a verification code with a 3-step routing strategy: Telegram, Voice, and SMS.

{
  "phone": "+491701234567",
  "code": "1234",
  "is_code_deleted": false,
  "payload": "yours payload here",
  "lang": "EN",
  "routing_strategy": [
    {
      "channel": "telegram",
      "timeout_sec": 30
    },
    {
      "channel": "voice",
      "sender_id": "LOX24",
      "template": "Your code is {{code}}"
    },
    {
      "channel": "sms",
      "sender_id": "LOX24",
      "template": "Your code is {{code}}"
    }
  ]
}

Verify code via Telegram

Send a verification code through a Telegram bot. The code will be delivered as a Telegram message to the user’s chat.

{
  "phone": "+491701234567",
  "lang": "EN",
  "routing_strategy": [
    {
      "channel": "telegram",
      "timeout_sec": 60
    }
  ]
}

Verify code via Voice call

Deliver a verification code through an automated voice call. The code is read aloud to the recipient using a text-to-speech template.

{
  "phone": "+491701234567",
  "code_length": 6,
  "lang": "EN",
  "routing_strategy": [
    {
      "channel": "voice",
      "sender_id": "LOX24",
      "template": "Your verification code is {{code}}"
    }
  ]
}

Responses

201

Verify code created and delivery process started

application/json

Verify code read response. Contains the full verification code request details including current status, delivery history, and cost information.

object

Unique identifier (UUID) of the verification code request.

string

user_id

ID of the user who created the verification code request.

integer

phone

Recipient phone number in international format.

string

code

The verification code value. If is_code_deleted was set and the task completed, the code will be absent.

string | null

code_length

Length of the verification code.

integer | null

lang

Language used for the message template.

string

Allowed values: EN DE FR IT ES PL NL RO PT CS HU SV DA FI SK HR TR RU BG UK

routing_strategy

Ordered list of delivery channels that were configured for this request.

Array<object>

object

channel

Delivery channel type.

string

Allowed values: telegram voice sms

timeout_sec

Timeout in seconds before falling back to the next step. Only applicable for the telegram channel.

integer | null

sender_id

Sender identifier used for this channel.

string | null

template

Custom message template used for this channel.

string | null

status

Current status of the verification code: 0 = New, 5 = In Progress, 10 = Success, 20 = Failed, 100 = Error.

integer

Allowed values: 0 5 10 20 100

delivered_channel

The channel that successfully delivered the verification code. Null if not yet delivered or if delivery failed.

string | null

Allowed values: telegram voice sms

cost

Total cost of the verification request in euro cents. Null until processing is complete.

integer | null

currency

Currency code for the cost.

string | null

payload

Custom payload data from the original request.

string | null

created_at

Unix timestamp of when the verification code was created.

integer

updated_at

Unix timestamp of the last update.

integer

history

Processing history for each channel attempt. One entry per routing step.

Array<object>

object

History entry UUID.

string

channel

Channel type for this attempt.

string

Allowed values: telegram voice sms

status

Status of this channel attempt: 0 = New, 5 = In Progress, 10 = Success, 20 = Failed, 100 = Error.

integer

processed_at

Unix timestamp of when this step was processed.

integer

external_id

External provider message ID.

string | null

is_code_deleted

Whether the verification code has been deleted from storage after being sent to the recipient.

boolean | null

Examples

multi_channel

Verify code response with multi-channel routing

Successful response after creating a verification code with a 3-step routing strategy. Telegram and voice channels failed, SMS succeeded.

{
  "id": "d7ad7539-fb8f-4dbb-a7f7-7c40babec969",
  "user_id": 12345,
  "phone": "+491701234567",
  "routing_strategy": [
    {
      "channel": "telegram",
      "timeout_sec": 30
    },
    {
      "channel": "voice",
      "sender_id": "LOX24",
      "template": "Your code is {{code}}"
    },
    {
      "channel": "sms",
      "sender_id": "LOX24",
      "template": "Your code is {{code}}"
    }
  ],
  "status": 10,
  "delivered_channel": "sms",
  "cost": 120,
  "currency": "EUR",
  "code": "1234",
  "code_length": 4,
  "payload": "yours payload here",
  "lang": "EN",
  "created_at": 1779903448,
  "updated_at": 1779903510,
  "history": [
    {
      "id": "bccaff09-59f2-11f1-a685-7c10c91d54a1",
      "channel": "telegram",
      "status": 20,
      "processed_at": 1779903478,
      "external_id": "tg_msg_001"
    },
    {
      "id": "bccaff09-59f2-11f1-a685-7c10c91d54a2",
      "channel": "voice",
      "status": 20,
      "processed_at": 1779903490,
      "external_id": "voice_msg_002"
    },
    {
      "id": "bccaff09-59f2-11f1-a685-7c10c91d54a3",
      "channel": "sms",
      "status": 10,
      "processed_at": 1779903510,
      "external_id": "sms_msg_003"
    }
  ],
  "is_code_deleted": false
}

400

Invalid input

401

Client ID or API key isn’t active or invalid!

402

There are not enough funds on your account!

403

Account isn’t activated. Please wait or contact to support!

422

The request was well-formed but was unable to be followed due to semantic errors

429

IP address was temporary blocked, because during short time from it was sent many request with invalid credentials. Please wait and try later.

Code Samples

#!/usr/bin/env bash
curl -X POST https://api.lox24.eu/verify_codes \
  -H 'Content-Type: application/json' \
  -H 'X-LOX24-AUTH-TOKEN: 1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx' \
  -d '{
    "phone": "+491701234567",
    "code": "1234",
    "is_code_deleted": false,
    "payload": "yours payload here",
    "lang": "EN",
    "routing_strategy": [
      {
        "channel": "telegram",
        "timeout_sec": 30
      },
      {
        "channel": "voice",
        "sender_id": "LOX24",
        "template": "Your code is {{code}}"
      },
      {
        "channel": "sms",
        "sender_id": "LOX24",
        "template": "Your code is {{code}}"
      }
    ]
  }'

using Newtonsoft.Json;
using System;
using System.IO;
using System.Net;
using System.Text;

namespace Lox24.Api
{
    class VerifyCodesClient
    {
        static void Main()
        {
            string key = "1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx";
            string url = "https://api.lox24.eu/verify_codes";

            var data = new {
                phone = "+491701234567",
                code = "1234",
                is_code_deleted = false,
                payload = "yours payload here",
                lang = "EN",
                routing_strategy = new[] {
                    new { channel = "telegram", timeout_sec = 30 },
                    new { channel = "voice", sender_id = "LOX24", template = "Your code is {{code}}" },
                    new { channel = "sms", sender_id = "LOX24", template = "Your code is {{code}}" }
                }
            };

            string postdata = JsonConvert.SerializeObject(data);

            Console.WriteLine("Post data: {0}", postdata);

            var httpWebRequest = (HttpWebRequest)WebRequest.Create(url);
            httpWebRequest.ReadWriteTimeout = 100000;
            httpWebRequest.ContentType = "application/json; charset=utf-8";
            httpWebRequest.Accept = "application/json";
            httpWebRequest.Method = "POST";
            httpWebRequest.KeepAlive = true;
            httpWebRequest.Headers.Add("X-LOX24-AUTH-TOKEN", key);
            httpWebRequest.Credentials = CredentialCache.DefaultNetworkCredentials;

            using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
            {
                streamWriter.Write(postdata);
                streamWriter.Flush();
                streamWriter.Close();
            }
            try
            {
                using (HttpWebResponse resp = (HttpWebResponse)httpWebRequest.GetResponse())
                {

                    if(resp.StatusCode == HttpStatusCode.Created) {
                        Console.WriteLine("Success:{0} {1}", (int)resp.StatusCode, "verify code resource created");
                    } else {
                        Console.WriteLine("Error: wrong response code {0} on create verify code", (int)resp.StatusCode);
                    }

                    Stream respStream = resp.GetResponseStream();
                    using (StreamReader sr = new StreamReader(respStream, Encoding.UTF8))
                    {
                        string responseText = sr.ReadToEnd();
                        Console.WriteLine("responseText : {0}", responseText);
                    }
                }

            }
            catch (System.Net.WebException ex)
            {
                var webResponse = ex.Response as System.Net.HttpWebResponse;
                Console.WriteLine("Error:{0}", webResponse.StatusCode);

                switch (webResponse.StatusCode)
                {
                    case HttpStatusCode.BadRequest:
                        Console.WriteLine("Error:400 Invalid input");
                        break;
                    case HttpStatusCode.Unauthorized:
                        Console.WriteLine("Error:401 Client ID or API key isn't active or invalid!");
                        break;
                    case HttpStatusCode.PaymentRequired:
                        Console.WriteLine("Error:402 There are not enough funds on your account!");
                        break;
                    case HttpStatusCode.Forbidden:
                        Console.WriteLine("Error:403 Account isn't activated. Please wait or contact to support!");
                        break;
                    case (HttpStatusCode)422:
                        Console.WriteLine("Error:422 Unprocessable entity");
                        break;
                    case HttpStatusCode.InternalServerError:
                    case HttpStatusCode.BadGateway:
                    case HttpStatusCode.ServiceUnavailable:
                    case HttpStatusCode.GatewayTimeout:
                        Console.WriteLine("System error! Please contact to LOX24 support!");
                        break;
                }
            }
        }
    }
}

package main

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "log"
  "net/http"
)

func main() {

  const Method = "POST"
  const URL = "https://api.lox24.eu/verify_codes"
  const Token = "1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx"

  routingStrategy := []map[string]interface{}{
    {"channel": "telegram", "timeout_sec": 30},
    {"channel": "voice", "sender_id": "LOX24", "template": "Your code is {{code}}"},
    {"channel": "sms", "sender_id": "LOX24", "template": "Your code is {{code}}"},
  }

  payload := map[string]interface{}{
    "phone":           "+491701234567",
    "code":            "1234",
    "is_code_deleted": false,
    "payload":         "yours payload here",
    "lang":            "EN",
    "routing_strategy": routingStrategy,
  }

  jsonPayload, _ := json.Marshal(payload)

  client := &http.Client{}

  req, err := http.NewRequest(Method, URL, bytes.NewBuffer(jsonPayload))
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Add("X-LOX24-AUTH-TOKEN", Token)
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  if err != nil {
    log.Fatal(err)
  }

  defer res.Body.Close()

  body, err := io.ReadAll(res.Body)
  if err != nil {
    log.Fatal(err)
  }

  switch res.StatusCode {
  case 201:
    fmt.Println(string(body))
  case 400:
    fmt.Println("Error: code = 400 - Invalid input")
  case 401:
    fmt.Println("Error: code = 401 - Client ID or API key isn't active or invalid!")
  case 402:
    fmt.Println("Error: code = 402 - There are not enough funds on your account!")
  case 403:
    fmt.Println("Error: code = 403 - Account isn't activated. Please wait or contact to support!")
  case 422:
    fmt.Println("Error: code = 422 - Unprocessable entity")
  default:
    fmt.Printf("Error: code = %d\n", res.StatusCode)
  }
}

package eu.lox24.doc.verify_codes;

import org.json.JSONArray;
import org.json.JSONObject;

import java.io.IOException;
import java.net.HttpURLConnection;
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.time.Duration;

public class PostVerifyCodesCollection {

    public static void main(String[] args) {

        var key = "1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx";
        var url = "https://api.lox24.eu/verify_codes";

        var routingStrategy = new JSONArray();
        routingStrategy.put(new JSONObject().put("channel", "telegram").put("timeout_sec", 30));
        routingStrategy.put(new JSONObject().put("channel", "voice").put("sender_id", "LOX24").put("template", "Your code is {{code}}"));
        routingStrategy.put(new JSONObject().put("channel", "sms").put("sender_id", "LOX24").put("template", "Your code is {{code}}"));

        var json = new JSONObject();
        json.put("phone", "+491701234567");
        json.put("code", "1234");
        json.put("is_code_deleted", false);
        json.put("payload", "yours payload here");
        json.put("lang", "EN");
        json.put("routing_strategy", routingStrategy);

        var postData = json.toString();

        System.out.println("Post data: " + postData);

        var httpRequest = HttpRequest.newBuilder(URI.create(url))
                .timeout(Duration.ofMillis(100000))
                .setHeader("Content-Type", "application/json; charset=utf-8")
                .setHeader("Accept", "application/json")
                .setHeader("X-LOX24-AUTH-TOKEN", key)
                .POST(HttpRequest.BodyPublishers.ofString(postData))
                .build();

        var client = HttpClient.newBuilder()
                .version(HttpClient.Version.HTTP_1_1)
                .build();

        try {
            var httpResponse = client.send(httpRequest, HttpResponse.BodyHandlers.ofString());

            if (httpResponse.statusCode() == HttpURLConnection.HTTP_CREATED) {
                System.out.println("Success:" + httpResponse.statusCode() + " " + "verify code resource created");
                System.out.println("Response text : \n" + httpResponse.body());

            } else {

                System.out.println("Error: wrong response code " + httpResponse.statusCode() + " on create verify code");

                switch (httpResponse.statusCode()) {

                    case HttpURLConnection.HTTP_BAD_REQUEST:
                        System.out.println("Error:400 Invalid input");
                        break;
                    case HttpURLConnection.HTTP_UNAUTHORIZED:
                        System.out.println("Error:401 Client ID or API key isn't active or invalid!");
                        break;
                    case HttpURLConnection.HTTP_PAYMENT_REQUIRED:
                        System.out.println("Error:402 There are not enough funds on your account!");
                        break;
                    case HttpURLConnection.HTTP_FORBIDDEN:
                        System.out.println("Error:403 Account isn't activated. Please wait or contact to support!");
                        break;
                    case 422:
                        System.out.println("Error:422 Unprocessable entity");
                        break;
                    case HttpURLConnection.HTTP_INTERNAL_ERROR:
                    case HttpURLConnection.HTTP_BAD_GATEWAY:
                    case HttpURLConnection.HTTP_UNAVAILABLE:
                    case HttpURLConnection.HTTP_GATEWAY_TIMEOUT:
                        System.out.println("System error! Please contact to LOX24 support!");
                        break;
                }

            }

        } catch (IOException | InterruptedException e) {
            e.printStackTrace();
        }
    }
}

/*
 * Post verify code
 */
const token = "1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx";

var postObj = {
    phone: '+491701234567',
    code: '1234',
    is_code_deleted: false,
    payload: 'yours payload here',
    lang: 'EN',
    routing_strategy: [
        {
            channel: 'telegram',
            timeout_sec: 30
        },
        {
            channel: 'voice',
            sender_id: 'LOX24',
            template: 'Your code is {{code}}'
        },
        {
            channel: 'sms',
            sender_id: 'LOX24',
            template: 'Your code is {{code}}'
        }
    ]
};

var postdata = JSON.stringify(postObj);

const https = require('https');
const options = {
    hostname: 'api.lox24.eu',
    path: '/verify_codes',
    method: 'POST',
    headers: {
        'Accept': 'application/json',
        'Content-Type': 'application/json',
        'Content-Length': postdata.length,
        'X-LOX24-AUTH-TOKEN': token
    }
}

const req = https.request(options, res => {
    if (res.statusCode == 201) {
        console.log("Success: code = 201 - verify code resource created");
        res.on('data', d => { process.stdout.write(d) })
    }
    else if (res.statusCode == 400) console.log("Error: code = 400 - Invalid input");
    else if (res.statusCode == 401) console.log("Error: code = 401 - Client ID or API key isn't active or invalid!");
    else if (res.statusCode == 402) console.log("Error: code = 402 - There are not enough funds on your account!");
    else if (res.statusCode == 403) console.log("Error: code = 403 - Account isn't activated. Please wait or contact to support!");
    else if (res.statusCode == 422) console.log("Error: code = 422 - Unprocessable entity");
})

req.on('error', error => {
    console.error(error)
})
req.write(postdata);
req.end();

<?php

$uri = 'https://api.lox24.eu/verify_codes';

$token = '1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx';

$body = [
    'phone' => '+491701234567',
    'code' => '1234',
    'is_code_deleted' => false,
    'payload' => 'yours payload here',
    'lang' => 'EN',
    'routing_strategy' => [
        [
            'channel' => 'telegram',
            'timeout_sec' => 30,
        ],
        [
            'channel' => 'voice',
            'sender_id' => 'LOX24',
            'template' => 'Your code is {{code}}',
        ],
        [
            'channel' => 'sms',
            'sender_id' => 'LOX24',
            'template' => 'Your code is {{code}}',
        ],
    ],
];

if(!$body = json_encode($body)) {
    die('JSON encoding error!');
}

$curl = curl_init();

curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_URL => $uri,
    CURLOPT_POSTFIELDS => $body,
    CURLOPT_HTTPHEADER => [
        "X-LOX24-AUTH-TOKEN: {$token}",
        'Accept: application/json',
        'Content-Type: application/json',
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
]);

$response = curl_exec($curl);
$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
curl_close($curl);

$data = json_decode($response, JSON_OBJECT_AS_ARRAY);

if(201 === $code) {
    echo 'Success: response data = ' . var_export($data, true);
} else {
    echo "Error: code = {$code}, data = " . var_export($data, true);
}

import json
import requests


token = "1234567:e3f3a759b6677959b6ebfcxxxxxxxxxx"

url = 'https://api.lox24.eu/verify_codes'


data = {
    'phone': "+491701234567",
    'code': "1234",
    'is_code_deleted': False,
    'payload': "yours payload here",
    'lang': "EN",
    'routing_strategy': [
        {
            'channel': "telegram",
            'timeout_sec': 30
        },
        {
            'channel': "voice",
            'sender_id': "LOX24",
            'template': "Your code is {{code}}"
        },
        {
            'channel': "sms",
            'sender_id': "LOX24",
            'template': "Your code is {{code}}"
        }
    ]
}

headers = {
    'Accept': 'application/json',
    'Content-Type': 'application/json',
    'X-LOX24-AUTH-TOKEN': token,
}

print("Post data : ", json.dumps(data, indent=4))

try:
    res = requests.post(url, headers=headers, json=data, timeout=100)
    if res.status_code != 201:
        print("Error: Wrong response code on create verify code")
        res.raise_for_status()
    else:
        print(f'Success: code = {res.status_code} - verify code resource created')
        print("Response: ", json.dumps(res.json(), indent=4))

except requests.HTTPError:
    if res.status_code == 400:
        print("Error:400 Invalid input")
    elif res.status_code == 401:
        print("Error: code = 401 - Client ID or API key isn't active or invalid!")
    elif res.status_code == 402:
        print("Error:402 There are not enough funds on your account!")
    elif res.status_code == 403:
        print("Error: code = 403 - Account isn't activated. Please wait or contact to support!")
    elif res.status_code == 422:
        print("Error:422 Unprocessable entity")
    elif res.status_code in (500, 502, 503, 504):
        print("System error! Please contact to LOX24 support!")
    else:
        print(f"Error: code {res.status_code}")
    print(json.dumps(res.json(), indent=4))

Create a verify code

Authorizations

Request Body required

Examples

Responses

201

Examples

400

401

402

403

422

429

Code Samples

Request Body^required