Toome AI Developer API Documentation

Introduction

Toome Developer API is a REST API that lets any external system integrate with the Toome platform. You can use it to send WhatsApp notifications, receive orders from external stores, and manage customer data in the CRM — all authenticated through a secure Bearer Token issued to each registered application.

New here? Follow this order

The sidebar is laid out as the same path most integrations follow, start to finish:

Authentication

The API uses the OAuth2 Client Credentials flow, the pattern designed for server-to-server connections where no end user is involved in the authentication process. Steps to get started:

1. Register a new application from the Developer Portal to get your client_id and client_secret.
2. Send a POST /api/v1/token request with these credentials to obtain an access_token.
3. Attach the access token to every subsequent request in the header: Authorization: Bearer {token}.

Sandbox

Every application gets a second, separate credential pair — sandbox_client_id / sandbox_client_secret — visible right below your live keys wherever they're shown (the "App created" screen, and the app's Credentials tab). Use them exactly like the live pair with POST /token; the response comes back with "sandbox": true.

What a sandbox token gets you:

• Same endpoints, same scopes. There's no separate /sandbox/v1/... path — every endpoint documented on this page works with a sandbox token exactly like it does live. The environment is determined entirely by which credential pair minted the token.
• A completely isolated fake account. A sandbox token reads and writes a private test tenant that only your app can see — its own customers, products, services, categories, orders, bookings, and WhatsApp templates. Nothing you create there is visible to, or shared with, your real account, and nothing in your real account leaks into it.
• A pre-connected fake WhatsApp number. GET /whatsapp-accounts already shows one — no connect flow needed (and POST /whatsapp/connect-link is disabled in sandbox, since connecting a real number to a fake account wouldn't make sense).
• Zero real WhatsApp messages, ever. POST /notify, order/booking notifications, and template submissions all respond exactly like the real thing (a fake but valid-looking message_id, instant template approval that fires a genuine template.approved webhook, and so on) — but nothing is ever sent to Meta, and no credits are ever charged.
• Every response says so. A response from a sandbox-tokened request always includes "sandbox": true, so it's never ambiguous which environment you're looking at.

Sandbox data is capped at 500 rows per resource type (customers, products, etc.) to keep things tidy — past that, writes return 429 SANDBOX_LIMIT_REACHED. Clear it any time from the app's Credentials tab with Reset Sandbox Data; this only wipes your test data, not the sandbox account itself or its keys.

Scopes

Each application is granted a specific set of scopes when it's created. No request can exceed the scopes assigned to it.

Error Codes

The API returns standard HTTP status codes along with a JSON body containing error details.

POST /token

Issue an access token using the application's credentials. This token is used in the Authorization header for all subsequent API requests.

Request Body

curl -X POST https://toome.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "client_id": "tm_xxxxxxxxxxxxxxxx",
    "client_secret": "your_secret_here"
  }'

$response = Http::post('https://toome.cloud/api/v1/token', [
    'client_id'     => 'tm_xxxxxxxxxxxxxxxx',
    'client_secret' => 'your_secret_here',
]);
$token = $response->json('access_token');

import requests
res = requests.post('https://toome.cloud/api/v1/token', json={
    'client_id': 'tm_xxxxxxxxxxxxxxxx',
    'client_secret': 'your_secret_here'
})
token = res.json()['access_token']

GET /test-connection

Verify that an access token is valid and inspect the scopes granted to the application. Useful for diagnostics and confirming a successful integration before launch.

curl https://toome.cloud/api/v1/test-connection \
  -H "Authorization: Bearer {your_token}"

GET /whatsapp-accounts

List the active WhatsApp numbers connected to your account. Requires the notify scope.

{
  "success": true,
  "count": 1,
  "data": [
    { "id": 6, "phone_display": "+20 101 234 5678", "verified_name": "My Store", "is_primary": true, "status": "connected" }
  ]
}

PATCH /whatsapp-accounts/{id}/ai

Turn Toome's automatic AI replies on or off for a specific WhatsApp number connected to your account. Requires the whatsapp.manage scope.

Request Parameters

POST /whatsapp/connect-link

Generate a one-time, 30-minute link that walks your end customer through connecting their own WhatsApp Business number to Toome (Meta's Embedded Signup flow) — no Toome login required to open it. Send this link to whoever needs to connect a number; each call issues a fresh token. Requires the whatsapp.manage scope.

Request Parameters

curl -X POST https://toome.cloud/api/v1/whatsapp/connect-link \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{ "label": "Ahmed'"'"'s store" }'

GET /templates

Retrieve all Meta-approved message templates available on your account. A template message can only be sent once it appears in this list with an approved status.

{
  "success": true,
  "count": 2,
  "data": [
    {
      "id": 5,
      "name": "order_confirmed",
      "language": "en",
      "category": "UTILITY",
      "body": "Hi 1, your order #2 has been confirmed ✅",
      "variables_count": 2
    }
  ]
}

POST /templates

Submit a new WhatsApp message template to Meta for review. This is the same review process as creating a template from the Toome dashboard — it does not go live immediately. Poll GET /templates/{id} for its approval status, and once it's APPROVED you can use its name in POST /notify. Requires the whatsapp.manage scope.

Request Parameters

curl -X POST https://toome.cloud/api/v1/templates \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "order_shipped",
    "category": "UTILITY",
    "language": "en",
    "body": "Hi 1, your order #2 is on its way!",
    "sender_account_id": 6
  }'

GET /templates/{id}

Check a single template's review status by its id (returned from POST /templates) — unlike GET /templates, this returns it regardless of status, so you can poll it right after submitting until it's no longer PENDING.

DELETE /templates/{id}

Remove a template from your Toome account. Requires the whatsapp.manage scope.

POST /notify

Send a WhatsApp template message to any phone number — even with no prior conversation with the user. Use it for transactional notifications like order confirmations, appointment reminders, and shipping alerts. Requires the notify scope.

Request Parameters

curl -X POST https://toome.cloud/api/v1/notify \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "201012345678",
    "template_name": "order_confirmed",
    "variables": ["Ahmed", "#1042", "150 EGP"]
  }'

Http::withToken($token)->post('/api/v1/notify', [
    'phone'         => '201012345678',
    'template_name' => 'order_confirmed',
    'variables'     => ['Ahmed', '#1042', '150 EGP'],
]);

requests.post('/api/v1/notify',
    headers={'Authorization': f'Bearer {token}'},
    json={
        'phone': '201012345678',
        'template_name': 'order_confirmed',
        'variables': ['Ahmed', '#1042', '150 EGP']
    }
)

POST /notifications/order

Send a ready-made WhatsApp notification for a specific order status using Toome's Meta-approved templates. No prior conversation with the customer is required — the message always gets through. Consumes credits from your balance on every successful send. Requires the send_notifications scope plus the Order Notifications feature enabled by the admin.

Request Parameters

Available status values

curl -X POST https://toome.cloud/api/v1/notifications/order \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone":         "201012345678",
    "status":        "order_confirmed",
    "tracking":      "ORD-1042",
    "customer_name": "Ahmed Ali",
    "store_name":    "My Store",
    "total":         "350 EGP"
  }'

Http::withToken($token)->post('https://toome.cloud/api/v1/notifications/order', [
    'phone'         => $order->customer_phone,
    'status'        => 'order_confirmed',
    'tracking'      => $order->reference,
    'customer_name' => $order->customer_name,
    'store_name'    => 'My Store',
    'total'         => $order->total . ' EGP',
]);

requests.post('https://toome.cloud/api/v1/notifications/order',
    headers={'Authorization': f'Bearer {token}'},
    json={
        'phone':         '201012345678',
        'status':        'out_for_delivery',
        'tracking':      'ORD-1042',
        'customer_name': 'Ahmed Ali',
    }
)

{
  "success": true,
  "message_id": "wamid.HBgM...",
  "status_sent": "order_confirmed",
  "charged_cents": 15,
  "balance_after_cents": 285
}

Shared by both Products and Services — the same category can hold either, or both, depending on type. Optional: category_id is nullable everywhere it's used.

GET /categories

List your categories. Filter with ?type=product or ?type=service to get only categories usable by that catalog (categories with type: "both" or no type always match). Requires the categories.read scope.

{
  "success": true,
  "data": [
    { "id": 3, "parent_id": null, "name": "العناية بالبشرة", "name_en": "Skin Care", "slug": "skin-care", "type": "both", "description": null, "is_active": true }
  ],
  "meta": { "total": 1, "per_page": 50, "current_page": 1, "last_page": 1 }
}

POST /categories

Create a category, optionally nested under an existing one via parent_id. Requires the categories.write scope.

Request Parameters

PATCH /categories/{id}

Every field optional, same as POST /categories. Requires the categories.write scope.

DELETE /categories/{id}

Requires the categories.write scope.

GET /products

Retrieve the product catalog with text search, category filtering, and pagination support. Requires the products.read scope.

{
  "success": true,
  "data": [
    { "id": 12, "name": "White T-Shirt", "price": 175, "stock": 40, "sku": "TS-WHT", "is_active": true }
  ],
  "meta": { "total": 1, "per_page": 20, "current_page": 1, "last_page": 1 }
}

POST /products

Create a single product, or update it if a product with the same sku already exists for your account. Requires the products.write scope.

Request Parameters

curl -X POST https://toome.cloud/api/v1/products \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "White T-Shirt",
    "price": 175,
    "stock": 40,
    "sku": "TS-WHT"
  }'

POST /products/sync

Bulk upsert up to 500 products in a single call — ideal for a full catalog sync from an external store. Matching is done by sku: existing SKUs are updated, new ones are created. Requires the products.write scope.

Request Parameters

curl -X POST https://toome.cloud/api/v1/products/sync \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "products": [
      {"name": "White T-Shirt", "sku": "TS-WHT", "price": 175, "stock": 40},
      {"name": "Black T-Shirt", "sku": "TS-BLK", "price": 175, "stock": 25}
    ]
  }'

DELETE /products/{id}

Permanently delete a product from your catalog. Requires the products.write scope.

For appointment-based businesses (clinics, salons, real estate, consultants...) instead of physical products. Each service has its own working hours, appointment duration, and can require booking.

GET /services

List your service catalog. Requires the services.read scope.

{
  "success": true,
  "data": [
    { "id": 7, "name": "استشارة أولى", "name_en": "Initial Consultation", "price": 200, "has_price": true, "duration_minutes": 30, "requires_booking": true, "is_active": true, "category_id": null }
  ],
  "meta": { "total": 1, "per_page": 20, "current_page": 1, "last_page": 1 }
}

POST /services

Create a new service. Requires the services.write scope. Unlike products, there's no SKU-based upsert — use PATCH /services/{id} to update one you already created.

Request Parameters

PATCH /services/{id}

Update a service — every field is optional, only what you send gets changed. Requires the services.write scope. Same parameters as POST /services.

DELETE /services/{id}

Requires the services.write scope.

GET /services/{id}/availability

Check open appointment slots for a service on a given date, before calling POST /bookings. Requires the services.read scope.

{
  "success": true,
  "date": "2026-10-01",
  "is_working_day": true,
  "slots": [
    { "start": "09:00", "end": "09:30", "available": true },
    { "start": "09:30", "end": "10:00", "available": false },
    { "start": "10:00", "end": "10:30", "available": true }
  ]
}

POST /orders

Receive an order from your external system and save it in Toome, with the option to notify the customer via WhatsApp at the same time. Requires the orders.write scope.

Request Parameters

curl -X POST https://toome.cloud/api/v1/orders \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "order_ref": "ORD-1042",
    "customer_phone": "201012345678",
    "customer_name": "Ahmed Ali",
    "total": 350.00,
    "currency": "EGP",
    "items": [
      {"name": "White T-Shirt", "qty": 2, "price": 175}
    ],
    "notify_template": "order_confirmed",
    "notify_variables": ["Ahmed", "ORD-1042"]
  }'

Http::withToken($token)->post('/api/v1/orders', [
    'order_ref'        => 'ORD-1042',
    'customer_phone'   => '201012345678',
    'total'            => 350.00,
    'notify_template'  => 'order_confirmed',
    'notify_variables' => ['Ahmed', 'ORD-1042'],
]);

  Idempotent by order_ref: if you call this endpoint again with an order_ref you already sent for this tenant (for example after a network timeout retry), no duplicate order is created and no second notification is sent — you get back 200 with the existing order and "idempotent": true instead of 201.

GET /orders

Retrieve the list of external orders stored in Toome, with pagination support. Requires the orders.read scope.

Real appointments on the calendar for the services from Step 5 — check availability first, then book.

POST /bookings

Book a real, confirmed appointment for a customer. It appears on the account's calendar immediately and the owner gets notified, same as a booking made through the dashboard. Requires the bookings.write scope.

Request Parameters

GET /bookings

List bookings, newest appointment first. Filterable by status, service_id, and date (YYYY-MM-DD). Requires the bookings.read scope.

{
  "success": true,
  "data": [
    { "id": 51, "order_code": "APP-7K2Q9X", "service_id": 7, "service_name": "استشارة أولى", "customer_name": "Ahmed Ali", "customer_phone": "201099998877", "status": "confirmed", "total_amount": 200, "appointment_at": "2026-10-01 09:00:00", "appointment_end_at": "2026-10-01 09:30:00" }
  ],
  "meta": { "total": 1, "per_page": 20, "current_page": 1, "last_page": 1 }
}

POST /customers

Add a new customer to Toome's CRM, or update their data if a customer with the same phone number already exists. Requires the customers.write scope.

Request Parameters

curl -X POST https://toome.cloud/api/v1/customers \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "201012345678",
    "name": "Ahmed Ali",
    "email": "ahmed@example.com",
    "source": "shopify",
    "status": "customer"
  }'

GET /customer-fields

List the account's custom customer fields (keys, labels, types and select options) so you know what to send in fields. Sensitive fields are never listed and are never returned or accepted by the API. Requires the customers.read scope.

GET /customers

Retrieve the customer list with text search, status filtering, and pagination support. Requires the customers.read scope.

Every customer includes a fields object with its non-sensitive custom field values (typed: numbers, booleans, arrays). Add ?include=records to also get each customer's non-sensitive repeating records (visits-style entries, pets, etc.) as records: [{ "id", "type", "date", "data": {…} }]. Sensitive fields and sensitive record types are never included.

Direct-database store integration — connects Toome to your store's own database so it can read/sync products directly. New integrations should prefer the External Items API (pass site_type below) rather than exposing direct database credentials.

POST /integrations/store/connect

Connect (or update) the external store linked to your application. Calling it again updates the existing connection instead of creating a duplicate.

Request Parameters

{
  "success": true,
  "store_id": "st_...",
  "app_id": "tm_...",
  "tenant_id": 42,
  "widget_key": "...",
  "platform": "custom",
  "items_api_token": "only present the first time, when site_type is used — store it now"
}

POST /integrations/store/test-connection

Test the direct database connection saved via /connect. Only relevant for the legacy direct-DB mode.

POST /integrations/store/sync

Not implemented yet. This endpoint currently returns 501 NOT_IMPLEMENTED. To push your catalog use POST /products/sync, or connect an External Items API (site_type on /integrations/store/connect).

DELETE /integrations/store/disconnect

Disconnect the store linked to your application. The connection record is kept but marked inactive.

GET /integrations/store/status

Check whether a store is connected and inspect its sync state.

{
  "success": true,
  "connected": true,
  "store": {
    "store_id": "st_...", "store_name": "My Store", "platform": "custom",
    "site_type": "shopify", "widget_key": "...",
    "items_api_connected": true, "last_sync_at": "2026-09-11T20:00:00+00:00", "synced_count": 4
  }
}

These endpoints require no additional scope — any authenticated application can call them.

GET /tenant/profile

Retrieve basic profile information for the tenant your app belongs to.

GET /tenant/subscription

Retrieve the tenant's active plan, limits, and current usage.

{
  "success": true,
  "subscription": {
    "plan_name": "Pro", "plan_code": "pro", "status": "active", "billing_cycle": "monthly",
    "started_at": "2026-01-10T09:00:00+00:00", "expires_at": "2026-10-10T09:00:00+00:00", "is_trial": false,
    "limits": { "conversations_per_month": 3000, "agents": 3, "apps": 2 },
    "usage": { "conversations_this_month": 812, "agents_used": 2, "apps_used": 1 }
  }
}

GET /tenant/credits

Retrieve your developer credits (OTP / AI / WhatsApp balances) plus the tenant wallet balance and its 10 most recent transactions. whatsapp_balance_cents is in cents (100 = 1 USD); each WhatsApp message sent from Toome's number costs 15 cents.

{
  "success": true,
  "developer_credits": {
    "otp_balance": 50, "ai_balance": 100, "whatsapp_balance_cents": 300,
    "otp_total_used": 0, "ai_total_used": 0, "whatsapp_total_used_cents": 0
  },
  "credits": {
    "balance": 49.5, "currency": "EGP", "last_topped_up_at": "2026-09-01T12:00:00+00:00",
    "recent_transactions": [
      { "type": "deduct", "amount": -0.5, "description": "notify: order_confirmed", "created_at": "2026-09-11T19:00:00+00:00" }
    ]
  }
}

GET /tenant/summary

A single call combining /tenant/profile, /tenant/subscription, /tenant/credits, and your app's own details — handy for a dashboard home screen.

GET /apps/{app_id}

Retrieve your own application's details. app_id must match the client_id of the token used to authenticate — you can only read your own app.

{
  "success": true,
  "app": {
    "id": "tm_xxxxxxxxxxxxxxxx", "name": "My App", "description": "...", "status": "approved",
    "is_active": true, "scopes": ["notify","orders.write"], "webhook_url": "https://...",
    "created_at": "2026-01-10T09:00:00+00:00", "features": {...}
  }
}

PATCH /apps/{app_id}/features

Toggle optional feature flags on your own application. Enabling a feature that requires a higher plan than the tenant currently has is rejected per-feature (reported in blocked) rather than failing the whole request. Some features (currently order_notifications) can only be disabled from the API — enabling them requires Toome admin approval and is always reported in blocked. The otp feature is enabled by default on new apps and is billed per message from your OTP credits.

Request Parameters

Overview

Instead of polling GET /customers, you can register a callback_url in your app's settings (Webhook tab) and Toome will push events to it in real time as they happen — including customers your AI agent captures on its own during a conversation (for example, a visitor who chats with your floating widget and shares their name and phone number naturally — Toome creates/updates a real customer record for them and fires this webhook automatically, with no extra code on your side).

Configure this from Developer Platform → your app → Webhook tab: set your callback_url, tick the events you want to receive, and copy your webhook_secret (auto-generated the first time you open that tab). A "Send test event" button is available there to confirm your endpoint is reachable before going live.

Available Events

  All events listed above are live today. Tick the ones you need in Developer Platform → your app → Webhook tab.

Example payload for the booking events (booking.confirmed, booking.cancelled, booking.completed, booking.no_show):

Example payload for the template events (template.approved, template.rejected):

Verifying the Signature

Every request carries an X-Toome-Signature header: sha256=<hmac>, an HMAC-SHA256 of the raw JSON body using your webhook_secret. Verify it before trusting the payload:

// In your webhook route handler
$payload   = $request->getContent();
$expected  = 'sha256=' . hash_hmac('sha256', $payload, $webhookSecret);
$signature = $request->header('X-Toome-Signature');

// constant-time compare, never ===
if (!hash_equals($expected, $signature)) {
    abort(401);
}

$event = $request->header('X-Toome-Event'); // e.g. "customer.created"
$data  = $request->json()->all();

Example payload for customer.created / customer.updated:

If you configured customer_fields_out in the Scopes tab, only those fields (plus id) are included in data. data also carries a fields object with the customer's non-sensitive custom fields (opt in with the "Custom customer fields" checkbox); sensitive fields are never sent. Delivery retries up to 3 times with backoff if your endpoint doesn't return a 2xx response.

🔐 One-Time Password (OTP) verification service

Toome Auth is a standalone service for sending verification codes (OTP) over WhatsApp — and soon SMS. It lets developers add a secure verification layer to any app or website in a few simple steps. The service supports two integration paths:

This section covers Type B (the standalone app). If you're using Type A, see the Authentication section and make sure the otp scope is enabled.

Toome Auth OTP Authentication

Every request on this path must include two HTTP headers: one carrying your application's API key, and the other its shared App Secret to verify your identity.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxx
X-App-Secret: your_app_secret_here

You can find your API Key and App Secret in the Developer Portal → OTP Apps → View Keys. The application must be in active status (after being reviewed and approved by the admin team).

POST /api/auth/v1/otp/send

Send an OTP verification code to a phone number over WhatsApp. Returns a unique request_id used in the following steps.

POST /api/auth/v1/otp/send
Authorization: Bearer sk_live_xxxx
X-App-Secret: your_secret

{
  "phone":   "201012345678",
  "channel": "whatsapp",
  "locale":  "en",
  "metadata": { "order_id": "ORD-789" }
}

{
  "success":                true,
  "request_id":              "req_01JXXXXXXXXXXXXXXXXXXX",
  "channel":                 "whatsapp",
  "phone":                   "+201012345678",
  "expires_in":               600,
  "expires_at":               "2026-06-12T14:05:00Z",
  "verification_method":      "whatsapp_deeplink",
  "deep_link_url":            "https://wa.me/9687xxxxxxx?text=TOOME-VERIFY%3Areq_01JXXX...",
  "fallback_after_seconds":   25
}

$res = Http::withHeaders([
    'Authorization' => 'Bearer ' . $apiKey,
    'X-App-Secret'  => $appSecret,
])->post('https://toome.cloud/api/auth/v1/otp/send', [
    'phone'  => $user->phone,
    'locale' => 'en',
]);
$requestId = $res->json('request_id');
$deepLink  = $res->json('deep_link_url'); // show this as a "Verify via WhatsApp" button in your UI

The fields verification_method, deep_link_url, and fallback_after_seconds are only returned when channel = whatsapp. The sms channel doesn't have a free path yet (only the base fields are returned).

POST /api/auth/v1/otp/verify

Verify the code entered by the user. On success, the code is invalidated immediately and can't be reused. The request returns success: true along with any metadata attached at send time (including verified_via set to template). This route is only for the paid fallback case — if you're using free WhatsApp verification, watch GET /otp/status/{request_id} instead.

{
  "request_id": "req_01JXXXXXXXXXXXXXXXXXXX",
  "code":       "482917"
}

// success
{
  "success":  true,
  "phone":    "201012345678",
  "metadata": { "order_id": "ORD-789", "verified_via": "template" },
  "verified_at": "2026-06-12T14:03:22Z"
}

// wrong code
{
  "success":    false,
  "error_code": "INVALID_CODE",
  "attempts_remaining": 2
}

$res = Http::withHeaders([
    'Authorization' => 'Bearer ' . $apiKey,
    'X-App-Secret'  => $appSecret,
])->post('https://toome.cloud/api/auth/v1/otp/verify', [
    'request_id' => $requestId,
    'code'       => $userInput,
]);
if ($res->json('success')) {
    // Verified — continue user registration or grant access
}

POST /api/auth/v1/otp/resend

Resend an OTP code to the same number using the original request_id. The cooldown period between sends (60 seconds by default) must elapse before this request is accepted.

{
  "request_id": "req_01JXXXXXXXXXXXXXXXXXXX"
}

If this is called before the cooldown period ends, the server returns the error COOLDOWN_ACTIVE along with a retry_after field indicating the remaining seconds.

GET /api/auth/v1/otp/status/{request_id}

Poll the current status of an OTP request — its primary use is the free WhatsApp verification path: the user won't type a code in your UI, so there's nothing to call /otp/verify with. Call this endpoint every 2-3 seconds after showing the user the deep_link_url, until status becomes verified.

GET /api/auth/v1/otp/status/req_01JXXXXXXXXXXXXXXXXXXX
Authorization: Bearer sk_live_xxxx
X-App-Secret: your_secret

// still waiting for the user's reply on WhatsApp
{ "success": true, "found": true, "status": "pending", "verified_via": null }

// verified for free via a WhatsApp reply
{ "success": true, "found": true, "status": "verified", "verified_via": "webhook" }

// verified via the template code (after calling /otp/verify)
{ "success": true, "found": true, "status": "verified", "verified_via": "template" }

// expired or not found
{ "success": false, "found": false, "status": "not_found" }

DELETE /api/auth/v1/otp/{request_id}

Cancel an OTP request and invalidate its associated code immediately. Use it when the user verifies through an alternate method, backs out of the flow, or their session ends before verification completes.

DELETE /api/auth/v1/otp/req_01JXXXXXXXXXXXXXXXXXXX

GET /api/auth/v1/otp/logs

Retrieve a historical log of OTP requests, with filtering by phone number and status, plus pagination support. Useful for review and auditing purposes.

GET /api/auth/v1/otp/logs?status=verified&per_page=20&page=1

{
  "data": [
    {
      "request_id": "req_01JXXX",
      "phone":      "201012345678",
      "channel":    "whatsapp",
      "status":     "verified",
      "created_at": "2026-06-12T14:00:00Z"
    }
  ],
  "meta": { "total": 148, "per_page": 20, "current_page": 1 }
}

Available values for filtering by the status field: pending (pending) | verified (verified) | expired (expired) | cancelled (cancelled) | failed (send failed)

GET /api/auth/v1/apps/stats

Retrieve OTP app performance statistics for the last 30 days, broken down by channel.

{
  "total_sent":     1420,
  "total_verified": 1184,
  "verify_rate":    "83.4%",
  "today":          47,
  "by_channel": {
    "whatsapp": { "sent": 1400, "verified": 1170 },
    "sms":      { "sent": 20,   "verified": 14   }
  }
}

Test Phones

This feature lets you register up to 10 phone numbers with fixed verification codes for testing purposes. When an OTP is sent to any of these numbers:

• No actual WhatsApp message is sent.
• No credits or tokens are consumed.
• The fixed code you pre-configured, stored in Redis, is returned.
• The feature works in both Live and Sandbox modes.

You can manage these numbers from the Developer Portal → OTP Apps → View App → Test Phones section. The response includes a test_phone: true field for every request to a test number.

OTP Error Codes

The OTP API returns a specific text error_code to make handling different error cases easier programmatically.

E-commerce store integration

When a new order arrives from a Shopify webhook, forward it to Toome to save it and instantly notify the customer via WhatsApp:

// Shopify webhook handler
$order = $request->json()->all();

Http::withToken($token)->post('https://toome.cloud/api/v1/orders', [
    'order_ref'        => $order['order_number'],
    'customer_phone'   => $order['phone'],
    'customer_name'    => $order['customer']['first_name'],
    'total'            => $order['total_price'],
    'notify_template'  => 'order_confirmed',
    'notify_variables' => [$order['customer']['first_name'], $order['order_number']],
]);

Booking confirmations

Right after a booking is confirmed in your system, send the notification template directly to the customer without needing any prior conversation:

Http::withToken($token)->post('https://toome.cloud/api/v1/notify', [
    'phone'         => $booking->customer_phone,
    'template_name' => 'booking_confirmed',
    'variables'     => [
        $booking->customer_name,
        $booking->service_name,
        $booking->date->format('Y-m-d H:i'),
    ],
]);

Automatic customer import

When a user completes registration on your site, add them to Toome's CRM automatically so the AI engine can start engaging with them right away:

// After a user completes registration on your site
Http::withToken($token)->post('https://toome.cloud/api/v1/customers', [
    'phone'  => $user->phone,
    'name'   => $user->name,
    'email'  => $user->email,
    'source' => 'website_registration',
    'status' => 'lead',
]);

Need help?

Integration questions, API keys, app approval status or webhook issues — email developers@toome.cloud and include your app_id so we can find your application quickly.