Developer integration guide
Use the configuration API to obtain today’s receiving details, then accept customer OTP messages at your HTTPS callback.
Quick start
- Create an account and copy the API key from the Dashboard.
- Add a public HTTPS callback URL and select its HTTP method. POST is recommended.
- Call the configuration API once a day and securely store the returned linked number and secure code for further processing. Unnecessary API calls are not allowed.
- Create an OTP in your application and ask the customer to send
SECURE_CODE-OTPto the linked number. Example in HTML<a href="sms:LINKED_PHONE_NUMBER?body=SECURE_CODE-OTP">Send OTP via SMS toLINKED_PHONE_NUMBER</a> - At your callback, validate
phoneandmessageagainst the pending OTP in your database.
1. Configuration API
This endpoint returns the current receiving number and secure code assigned to the authenticated account. It does not search for an SMS and requires no JSON request body.
- Endpoint
https://auth.electrocompsystem.com/api/v1/verifications- Method
POST- Authorization
Bearer YOUR_API_KEY- Request body
- None
- Successful limit
- 1 call every 5 minutes
- Recommended time
- Once daily, at a time convenient for your application
curl --request POST 'https://auth.electrocompsystem.com/api/v1/verifications' \
+ --header 'Authorization: Bearer YOUR_API_KEY' \
+ --header 'Accept: application/json'HTTP 200 response
{
"status": "success",
"result": "success",
"limit": {
"count": 1,
"minute": 5,
"last_call": "2026-09-23 14:20:00"
},
"linked_phone_number": "9432310298",
"secure_code": "A7K2Q9"
}HTTP 429 response
{
"status": "error",
"result": "limit reached",
"limit": {
"count": 1,
"minute": 5,
"last_call": "2026-09-23 14:20:00"
}
} last_call is returned in Indian Standard Time. Store the API response securely for further processing using the linked number and secure code. Unnecessary API calls are not allowed.
2. Build the customer’s SMS
Create the OTP in your own backend. Join the current secure code, one hyphen and the OTP:
A7K2Q9-T855PR A7K2Q9=secure code
- = first separator
T855PR=your OTP/message
Display both the exact SMS text and the returned linked phone number to the customer. Everything after the first hyphen is forwarded as message or OTP.
3. Receive the callback
When ECS Authenticator receives a valid SMS for your secure code, it call back the HTTPS URL saved in your Dashboard. The request uses application/x-www-form-urlencoded.
| Field | Type | Description |
|---|---|---|
phone | String | Sender phone number received from the system |
message | String | Everything after the first hyphen; normally your OTP |
Example POST body
phone=9876543210&message=T855PRReturn any HTTP status from 200 to 299 after accepting the request. Other statuses, connection errors or timeouts are logged as failed. ECS Authenticator does not follow redirects.
<?php
declare(strict_types=1);
date_default_timezone_set('Asia/Kolkata');
header('Content-Type: application/json; charset=utf-8');
$phone = preg_replace('/\D+/', '', (string) ($_POST['phone'] ?? ''));
$message = trim((string) ($_POST['message'] ?? ''));
if (strlen($phone) === 12 && str_starts_with($phone, '91')) {
$phone = substr($phone, 2);
}
if (
!preg_match('/^[6-9][0-9]{9}$/', $phone) ||
!preg_match('/^([A-Za-z0-9]{6})/', $message, $match)
) {
http_response_code(400);
echo json_encode([
'status' => 'error',
'message' => 'Invalid phone number or OTP.'
]);
exit;
}
$data = [
'status' => 'success',
'message' => 'Callback received and logged.',
'received_at' => date('Y-m-d H:i:s'),
'phone' => '+91' . $phone,
'otp' => $match[1]
];
$logged = file_put_contents(
__DIR__ . '/callback.log',
json_encode($data, JSON_UNESCAPED_SLASHES) . PHP_EOL,
FILE_APPEND | LOCK_EX
);
if ($logged === false) {
http_response_code(500);
$data['status'] = 'error';
$data['message'] = 'Could not write callback log.';
}
echo json_encode(
$data,
JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES
);Configuration API examples
<?php
declare(strict_types=1);
header('Content-Type: application/json; charset=utf-8');
header('Cache-Control: no-store');
$apiUrl = 'https://auth.electrocompsystem.com/api/v1/verifications';
$apiKey = 'YOUR_API_KEY';
try {
if ($apiKey === '' || $apiKey === 'YOUR_API_KEY') {
throw new RuntimeException('API key is not configured.');
}
$ch = curl_init($apiUrl);
if ($ch === false) {
throw new RuntimeException('Could not initialize cURL.');
}
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $apiKey,
'Accept: application/json',
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 15,
]);
$body = curl_exec($ch);
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$curlError = curl_error($ch);
curl_close($ch);
if ($body === false) {
throw new RuntimeException('API connection failed: ' . $curlError);
}
$data = json_decode($body, true, 512, JSON_THROW_ON_ERROR);
if ($statusCode === 200 && ($data['status'] ?? '') === 'success') {
$linkedNumber = (string) ($data['linked_phone_number'] ?? '');
$secureCode = (string) ($data['secure_code'] ?? '');
// Store $linkedNumber and $secureCode securely if required.
}
http_response_code($statusCode >= 100 ? $statusCode : 200);
echo json_encode(
$data,
JSON_PRETTY_PRINT |
JSON_UNESCAPED_SLASHES |
JSON_UNESCAPED_UNICODE
);
} catch (Throwable $error) {
http_response_code(500);
echo json_encode([
'status' => 'error',
'message' => $error->getMessage(),
], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
}import json
import requests
API_URL = "https://auth.electrocompsystem.com/api/v1/verifications"
API_KEY = "YOUR_API_KEY"
try:
if not API_KEY or API_KEY == "YOUR_API_KEY":
raise ValueError("API key is not configured.")
response = requests.post(
API_URL,
headers={
"Authorization": f"Bearer {API_KEY}",
"Accept": "application/json",
},
timeout=15,
)
response.raise_for_status()
data = response.json()
if data.get("status") == "success":
linked_number = data.get("linked_phone_number", "")
secure_code = data.get("secure_code", "")
# Store linked_number and secure_code securely if required.
print(json.dumps(data, indent=4, ensure_ascii=False))
except requests.RequestException as error:
print(json.dumps({
"status": "error",
"message": f"API request failed: {error}"
}, indent=4))
except (ValueError, json.JSONDecodeError) as error:
print(json.dumps({
"status": "error",
"message": str(error)
}, indent=4))const apiUrl = 'https://auth.electrocompsystem.com/api/v1/verifications';
const apiKey = 'YOUR_API_KEY';
async function fetchVerification() {
try {
if (!apiKey || apiKey === 'YOUR_API_KEY') {
throw new Error('API key is not configured.');
}
const response = await fetch(apiUrl, {
method: 'POST',
headers: {
'Authorization': `Bearer ${apiKey}`,
'Accept': 'application/json'
},
signal: AbortSignal.timeout(15000)
});
const responseText = await response.text();
let data;
try {
data = JSON.parse(responseText);
} catch {
throw new Error(
`API returned an invalid JSON response (HTTP ${response.status}).`
);
}
if (
response.status === 200 &&
data.status === 'success'
) {
const linkedNumber = String(data.linked_phone_number ?? '');
const secureCode = String(data.secure_code ?? '');
// Store linkedNumber and secureCode securely if required.
}
console.log(JSON.stringify(data, null, 2));
if (!response.ok) {
process.exitCode = 1;
}
} catch (error) {
const message =
error instanceof Error ? error.message : 'Unknown error occurred.';
console.error(JSON.stringify({
status: 'error',
message: message
}, null, 2));
process.exitCode = 1;
}
}
fetchVerification();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 Main {
private static final String API_URL =
"https://auth.electrocompsystem.com/api/v1/verifications";
private static final String API_KEY = "YOUR_API_KEY";
public static void main(String[] args) {
try {
if (API_KEY.isBlank() || "YOUR_API_KEY".equals(API_KEY)) {
throw new IllegalStateException(
"API key is not configured."
);
}
HttpClient client = HttpClient.newBuilder()
.connectTimeout(Duration.ofSeconds(10))
.build();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(API_URL))
.timeout(Duration.ofSeconds(15))
.header("Authorization", "Bearer " + API_KEY)
.header("Accept", "application/json")
.POST(HttpRequest.BodyPublishers.noBody())
.build();
HttpResponse<String> response = client.send(
request,
HttpResponse.BodyHandlers.ofString()
);
int statusCode = response.statusCode();
String responseBody = response.body();
/*
* For production use, parse responseBody with a JSON library
* such as Jackson, Gson or org.json.
*
* When statusCode is 200 and status is "success", read:
* linked_phone_number
* secure_code
*/
System.out.println(responseBody);
if (statusCode < 200 || statusCode >= 300) {
System.exit(1);
}
} catch (InterruptedException error) {
Thread.currentThread().interrupt();
System.err.println(
"{\"status\":\"error\",\"message\":\"Request interrupted.\"}"
);
System.exit(1);
} catch (Exception error) {
String message = escapeJson(error.getMessage());
System.err.println(
"{\"status\":\"error\",\"message\":\"" + message + "\"}"
);
System.exit(1);
}
}
private static String escapeJson(String value) {
if (value == null) {
return "Unknown error occurred.";
}
return value
.replace("\\", "\\\\")
.replace("\"", "\\\"")
.replace("\r", "\\r")
.replace("\n", "\\n");
}
}HTTP responses and recovery
| Status | Meaning | What to do |
|---|---|---|
200 | Current values returned | Store them securely for the day. |
401 | Missing, malformed or inactive API key | Check the Bearer header or rotate the key in the Dashboard. |
429 | Cooldown is active or another request is running | Do not retry immediately; use cached values and wait for the configured interval. |
5xx | Temporary server problem | Keep the last known values and retry later with controlled backoff. |
Production security checklist
- Keep the API key in server-side secrets; never embed it in browser JavaScript or a distributed mobile app.
- Use a callback URL containing a long, random, unguessable path segment and accept requests only over HTTPS.
- Because the current callback contains no signature header, never trust the callback alone. Match the phone and OTP against a pending server-side record.
- Store OTPs as one-way hashes, give them a short expiry, limit attempts and mark them used in one atomic database operation.
- Normalise Indian phone numbers before comparison and allow only the formats your application expects.
- Return a 2xx response quickly; perform slow secondary work after recording the request.
- Do not log API keys, full OTPs or unnecessary personal data.