API integration quickstart

Before you start

The current API reference ships inside your account after signup; there is deliberately no public docs URL on this site. Want the reference before committing? Contact us and we will walk you through the live endpoints.

• An sms-ocean account, created through signup.
• DLT verification complete, with the header and template you will send with approved — see DLT registration and Sender ID and template setup.
• Your API credentials for the Authorization header — the key your account issues; the example below uses a sample key, not real credentials.
• A verified number to send to for your first test — the onboarding sequence ends with a first verified send for exactly this purpose.

The send call

This is the same safe example published on the homepage — a sample key and a masked number, not real credentials:

# safe example — sample key, masked number (not real credentials)
POST /api/v1/messages
Authorization: Bearer SMS-SAMPLE-KEY

{ "to": "+91XXXXXXXXXX",
  "sender": "SMPLID",
  "template": "order_shipped_v3" }

→ 202 Accepted
{ "messageId": "msg_sample_001", "status": "queued" }

Reading it: the Authorization header carries your account's bearer key; the body names the recipient, the approved header (sender) and the registered template. A successful call is answered with 202 Accepted, a message id and the message's initial status.

Reading the response

The messageId is your handle for everything that happens next — it identifies this one message in the portal and in your own records. The initial status (queued in the example) is the message's state at acceptance; per-message delivery status flows back as carriers confirm, which is the subject of Delivery reports and statuses.

Treat the id as durable: log it against the business event that triggered the send (the order, the appointment, the login attempt). When a colleague asks about a specific message weeks later, the id is the join between your application's records and the portal's audit.

Handling failures in your integration

Throughput is a conversation, not a guess: ask for a volume and throughput check for your expected send rate during signup or through support, and size your queueing to the confirmed figures.

• Non-success HTTP responses mean the request was not accepted — log the response body, not just the code, because it says why.
• A 202 with a message id means the message was accepted; anything about delivery comes later, per message, as carriers confirm.
• Retry on transport errors with backoff; do not blind-retry an accepted send, or you will pay for duplicates.
• Validate recipient number format before calling — rejected-at-validation is the cheapest failure class to prevent.

API or dashboard for your first sends?

They are the same platform behind two surfaces. The dashboard is where campaigns are scheduled and where reporting is read; the API is how application events — an OTP at login, an order confirmation — become messages without a human in the loop. A first integration usually proves itself with a single triggered event: wire one real action to one template, send to a verified number, and follow the message id through to its delivery status.

Frequently asked questions

Next step

Create your account and start the workflow this guide covers — where a step is managed by our team rather than self-serve, we say so during signup. Prefer to talk first? Contact us and we will walk through it with you.