Create and dispatch a PIN

curl --request POST \
  --url https://api.onexaura.com/v1/pins \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination": "+919876543210",
  "templateId": "tpl_abc123",
  "channels": [
    "sms"
  ],
  "referenceId": "order_1234",
  "templateParams": {
    "1": "Jane Doe",
    "2": "ORD-1234"
  }
}
'

import requests

url = "https://api.onexaura.com/v1/pins"

payload = {
    "destination": "+919876543210",
    "templateId": "tpl_abc123",
    "channels": ["sms"],
    "referenceId": "order_1234",
    "templateParams": {
        "1": "Jane Doe",
        "2": "ORD-1234"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    destination: '+919876543210',
    templateId: 'tpl_abc123',
    channels: ['sms'],
    referenceId: 'order_1234',
    templateParams: {'1': 'Jane Doe', '2': 'ORD-1234'}
  })
};

fetch('https://api.onexaura.com/v1/pins', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.onexaura.com/v1/pins",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'destination' => '+919876543210',
    'templateId' => 'tpl_abc123',
    'channels' => [
        'sms'
    ],
    'referenceId' => 'order_1234',
    'templateParams' => [
        '1' => 'Jane Doe',
        '2' => 'ORD-1234'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.onexaura.com/v1/pins"

	payload := strings.NewReader("{\n  \"destination\": \"+919876543210\",\n  \"templateId\": \"tpl_abc123\",\n  \"channels\": [\n    \"sms\"\n  ],\n  \"referenceId\": \"order_1234\",\n  \"templateParams\": {\n    \"1\": \"Jane Doe\",\n    \"2\": \"ORD-1234\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.onexaura.com/v1/pins")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"destination\": \"+919876543210\",\n  \"templateId\": \"tpl_abc123\",\n  \"channels\": [\n    \"sms\"\n  ],\n  \"referenceId\": \"order_1234\",\n  \"templateParams\": {\n    \"1\": \"Jane Doe\",\n    \"2\": \"ORD-1234\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.onexaura.com/v1/pins")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"destination\": \"+919876543210\",\n  \"templateId\": \"tpl_abc123\",\n  \"channels\": [\n    \"sms\"\n  ],\n  \"referenceId\": \"order_1234\",\n  \"templateParams\": {\n    \"1\": \"Jane Doe\",\n    \"2\": \"ORD-1234\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "pinId": "pin_x9k2m1qz",
  "status": "PENDING",
  "expiresAt": "2026-08-04T10:22:03.221Z",
  "attemptsRemaining": 3,
  "channels": [
    {
      "channel": "sms",
      "status": "accepted",
      "providerMessageId": "<string>",
      "errorCode": "<string>",
      "errorMessage": "<string>"
    }
  ]
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

POST

pins

Create and dispatch a PIN

curl --request POST \
  --url https://api.onexaura.com/v1/pins \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "destination": "+919876543210",
  "templateId": "tpl_abc123",
  "channels": [
    "sms"
  ],
  "referenceId": "order_1234",
  "templateParams": {
    "1": "Jane Doe",
    "2": "ORD-1234"
  }
}
'

import requests

url = "https://api.onexaura.com/v1/pins"

payload = {
    "destination": "+919876543210",
    "templateId": "tpl_abc123",
    "channels": ["sms"],
    "referenceId": "order_1234",
    "templateParams": {
        "1": "Jane Doe",
        "2": "ORD-1234"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    destination: '+919876543210',
    templateId: 'tpl_abc123',
    channels: ['sms'],
    referenceId: 'order_1234',
    templateParams: {'1': 'Jane Doe', '2': 'ORD-1234'}
  })
};

fetch('https://api.onexaura.com/v1/pins', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.onexaura.com/v1/pins",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'destination' => '+919876543210',
    'templateId' => 'tpl_abc123',
    'channels' => [
        'sms'
    ],
    'referenceId' => 'order_1234',
    'templateParams' => [
        '1' => 'Jane Doe',
        '2' => 'ORD-1234'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.onexaura.com/v1/pins"

	payload := strings.NewReader("{\n  \"destination\": \"+919876543210\",\n  \"templateId\": \"tpl_abc123\",\n  \"channels\": [\n    \"sms\"\n  ],\n  \"referenceId\": \"order_1234\",\n  \"templateParams\": {\n    \"1\": \"Jane Doe\",\n    \"2\": \"ORD-1234\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.onexaura.com/v1/pins")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"destination\": \"+919876543210\",\n  \"templateId\": \"tpl_abc123\",\n  \"channels\": [\n    \"sms\"\n  ],\n  \"referenceId\": \"order_1234\",\n  \"templateParams\": {\n    \"1\": \"Jane Doe\",\n    \"2\": \"ORD-1234\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.onexaura.com/v1/pins")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"destination\": \"+919876543210\",\n  \"templateId\": \"tpl_abc123\",\n  \"channels\": [\n    \"sms\"\n  ],\n  \"referenceId\": \"order_1234\",\n  \"templateParams\": {\n    \"1\": \"Jane Doe\",\n    \"2\": \"ORD-1234\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "pinId": "pin_x9k2m1qz",
  "status": "PENDING",
  "expiresAt": "2026-08-04T10:22:03.221Z",
  "attemptsRemaining": 3,
  "channels": [
    {
      "channel": "sms",
      "status": "accepted",
      "providerMessageId": "<string>",
      "errorCode": "<string>",
      "errorMessage": "<string>"
    }
  ]
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

{
  "error": {
    "code": "pin_expired",
    "message": "<string>",
    "requestId": "req_9f3a2c",
    "details": {}
  }
}

This is the call that starts a verification. OneXtel generates the PIN, substitutes it into the template’s content for each channel you asked for, and dispatches to all of them in parallel — then returns a pinId and what each channel did. Hold on to the pinId. It is what you verify against, and what you resend on. The code itself is never returned to you and never stored in the clear.

Omit channels to send on the template’s default channel. Pass it to override — every channel you name must already have a channel account configured on that template, or the call fails with channel_not_configured.

Partial success

A 201 means at least one channel accepted the message, not all of them. Read channels[] to see which:

Response — SMS accepted, WhatsApp rejected

{
  "pinId": "pin_x9k2m1qz",
  "status": "PENDING",
  "expiresAt": "2026-08-04T10:22:03.221Z",
  "attemptsRemaining": 3,
  "channels": [
    { "channel": "sms", "status": "accepted", "providerMessageId": "3f9a1c02" },
    { "channel": "whatsapp", "status": "rejected", "errorCode": "131047", "errorMessage": "Re-engagement message" }
  ]
}

Only when every requested channel is rejected do you get 502 dispatch_failed. So do not retry on a 201 — the user has a code.

Always send the Idempotency-Key header on this call. Without it, a network timeout you retry will dispatch a second PIN and invalidate the first, and the user will be typing a code that no longer verifies. See Idempotency.

Authorizations

Authorization

string

header

required

An API key from the OneXtel portal, Developers → API Keys, sent as Authorization: Bearer <key>.

Headers

Idempotency-Key

string

Protects a send/resend against duplicate dispatch on retry. Replaying the same key + body within 24h returns the original response verbatim; the same key with a different body is rejected (idempotency_key_reuse); a concurrent request with the same key still in flight is rejected (idempotency_in_progress).

Body

application/json

destination

string

required

Destination, exactly as the active provider expects it — never reformatted.

Required string length: 1 - 64

Example:

"+919876543210"

templateId

string

required

The template to send under.

Minimum string length: 1

Example:

"tpl_abc123"

channels

enum<string>[]

Channels to dispatch on. Omit to use the template's default channel.

Minimum array length: 1

Available options:

sms,

whatsapp,

email

Example:

["sms"]

referenceId

string

Optional caller-supplied correlation id, searchable in Verifications.

Required string length: 1 - 200

Example:

"order_1234"

templateParams

object

Per-send override for a WhatsApp template's non-OTP placeholders, by position. Omitted positions fall back to the template's stored default.

Show child attributes

Example:

{ "1": "Jane Doe", "2": "ORD-1234" }

Response

At least one channel accepted the message.

pinId

string

Example:

"pin_x9k2m1qz"

status

enum<string>

Available options:

PENDING,

VERIFIED,

EXPIRED,

BLOCKED

Example:

"PENDING"

expiresAt

string<date-time>

Example:

"2026-08-04T10:22:03.221Z"

attemptsRemaining

integer

Example:

3

channels

object[]

Show child attributes

WhatsApp

RCS

SMS (India)

SMS (International)

OmniChannel

Verify

Create and dispatch a PIN

Partial success

Authorizations

Headers

Body

Response

​Partial success

Authorizations

Headers

Body

Response

Partial success