API reference

SMS.

Send a transactional SMS from your wallet and read its delivery status. Every request needs an API key in the Authorization header; the reference overview covers keys, errors and rate limits.

Send an SMS

POST/v1/smsSending or full access key

Send one transactional SMS. The message is charged to your wallet when it is queued and delivered by the route Notix has configured for the destination country. Delivery status arrives through the sms.sent, sms.delivered and sms.failed webhooks, or by reading the message back.

Pricing

One GSM-7 message is up to 160 characters; longer text is billed per 153 character segment. Text with characters outside GSM-7 is billed per 70 characters (67 when concatenated). SMS needs no paid plan: it is prepaid from your wallet.

Sender ID

senderId is optional. It defaults to your team's own approved sender ID for the destination country, or to the shared Notix sender ID when you have none. Only a sender ID approved for your team is accepted. See SMS and sender IDs.

Idempotency

Pass an Idempotency-Key header to make a retry safe. The same key and body returns the original message. The same key with a different body answers 409.

Errors

Status	Code	Meaning
400	`BAD_REQUEST`	The number is not valid E.164, the text is empty or over 1,600 characters, or the sender ID is not one you may use.
402	`INSUFFICIENT_BALANCE`	Your wallet cannot cover the message. Nothing was sent.
403	`FORBIDDEN`	SMS is not enabled for your team.
409	`NOT_UNIQUE`	The idempotency key was used with a different body.
422	`RISK_REFUSED`	Risk scoring refused the request.

Headers
Field	Type	About
`Idempotency-Key`	`string`	Makes the request safe to retry. Same key and same body returns the original message. Same key and a different body answers 409 NOT_UNIQUE.

Request body (JSON)
Field	Type	About
`to`required	`string`	The recipient phone number with its country code.
`text`required	`string`	The message. Up to 1600 characters. GSM-7 text is billed in 160 character segments (153 when concatenated); text with other characters in 70 (67). At most 1,600 characters.
`senderId`	`string`	A sender ID approved for this team. Defaults to the team's own approved sender ID for the country, or to the shared Notix sender ID when it has none. At most 11 characters.
`clientIp`	`string (ip)`	The IPv4 or IPv6 address the end user made the request from. Used by risk scoring. Notix stores only a keyed hash of it.

terminal

curl -X POST "https://app.usenotix.dev/api/v1/sms" \
  -H "Authorization: Bearer $NOTIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "to": "+2348012345678",
  "text": "Your order 4471 has shipped."
}'

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.sms.send(
  { to: "+2348012345678", text: "Your order 4471 has shipped." },
  { idempotencyKey: "order-4471-shipped" },
);

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

message, _ = notix.sms.send(
    {"to": "+2348012345678", "text": "Your order 4471 has shipped."},
    idempotency_key="order-4471-shipped",
)

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$message = $notix->sms->send(['to' => '+2348012345678', 'text' => 'Your order 4471 has shipped.'], 'order-4471-shipped');

Responses

201The message was charged to the wallet and queued for delivery.

201 response fields
Field	Type	About
`id`required	`string`
`to`required	`string`	Masked to the last four digits.
`status`required	`string`	One of `queued`, `sent`, `delivered`, `failed`, `rejected`.
`segments`required	`integer`
`charge`required	`object`
`charge.currency`required	`string`	One of `USD`, `NGN`, `KES`.
`charge.amount`required	`string`	Decimal string in the team's wallet currency.
`reason`required	`object`	Set when the status is failed or rejected. Plain language, never a provider code. Can be null.
`reason.code`required	`string`
`reason.message`required	`string`
`createdAt`required	`string`
`updatedAt`required	`string`

400Invalid input: the number, the text length or the sender ID.

402The team wallet cannot cover the message. Nothing was sent.

402 response fields
Field	Type	About
`error`required	`object`
`error.code`required	`string`	One of `INSUFFICIENT_BALANCE`.
`error.message`required	`string`

403SMS is not enabled for this team, or the environment refuses this destination.

409The Idempotency-Key was used with a different body, or a request with it is in progress.

422Risk scoring refused the request. Nothing was sent.

422 response fields
Field	Type	About
`error`required	`object`
`error.code`required	`string`	One of `RISK_REFUSED`.
`error.message`required	`string`
`risk`required	`object`
`risk.score`required	`number`
`risk.level`required	`string`	One of `LOW`, `MEDIUM`, `HIGH`.
`risk.reasons`required	`object[]`
`risk.reasons[].code`required	`string`
`risk.reasons[].detail`required	`string`

List SMS messages

GET/v1/smsFull access key

List the team's SMS messages, newest first, with a cursor for the next page. Filter by status and page with cursor and limit (default 50, max 100). Needs a full access key.

Status	Meaning
`queued`	Charged, waiting for the provider.
`sent`	Accepted by the network.
`delivered`	Confirmed delivered by the provider's delivery report.
`failed`	Not delivered after being sent. The charge stands.
`rejected`	Refused before delivery. The charge was returned.

Query parameters
Field	Type	About
`cursor`	`string`
`limit`	`integer`	Default `50`.
`status`	`string`	One of `queued`, `sent`, `delivered`, `failed`, `rejected`.

terminal

curl -X GET "https://app.usenotix.dev/api/v1/sms" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.sms.list({ limit: 20, status: "failed" });

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

page, _ = notix.sms.list(limit=20, status="failed")

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$page = $notix->sms->list(['limit' => 20, 'status' => 'failed']);

Responses

200The team's messages, newest first, with a cursor for the next page.

200 response fields
Field	Type	About
`data`required	`object[]`
`data[].id`required	`string`
`data[].to`required	`string`	Masked to the last four digits.
`data[].status`required	`string`	One of `queued`, `sent`, `delivered`, `failed`, `rejected`.
`data[].segments`required	`integer`
`data[].charge`required	`object`
`data[].charge.currency`required	`string`	One of `USD`, `NGN`, `KES`.
`data[].charge.amount`required	`string`	Decimal string in the team's wallet currency.
`data[].reason`required	`object`	Set when the status is failed or rejected. Plain language, never a provider code. Can be null.
`data[].reason.code`required	`string`
`data[].reason.message`required	`string`
`data[].createdAt`required	`string`
`data[].updatedAt`required	`string`
`nextCursor`required	`string`	Can be null.

400Invalid cursor, limit or status.

Get an SMS message

GET/v1/sms/{id}Full access key

Retrieve one SMS message by id, with its current delivery status and reason. Needs a full access key.

Status	Meaning
`queued`	Charged, waiting for the provider.
`sent`	Accepted by the network.
`delivered`	Confirmed delivered by the provider's delivery report.
`failed`	Not delivered after being sent. The charge stands.
`rejected`	Refused before delivery. The charge was returned.

Path parameters
Field	Type	About
`id`required	`string`

terminal

curl -X GET "https://app.usenotix.dev/api/v1/sms/<id>" \
  -H "Authorization: Bearer $NOTIX_API_KEY"

notix-js

import { Notix } from "notix-js";

const notix = new Notix(process.env.NOTIX_API_KEY);

const { data, error } = await notix.sms.get("sms_123");

notix-sdk

from notix import Notix

notix = Notix()  # reads NOTIX_API_KEY

message, _ = notix.sms.get("sms_123")

usenotix/notix-php

use Notix\Notix;

$notix = new Notix(getenv('NOTIX_API_KEY'));

$message = $notix->sms->get('sms_123');

Responses

200The message with its delivery status and reason.

200 response fields
Field	Type	About
`id`required	`string`
`to`required	`string`	Masked to the last four digits.
`status`required	`string`	One of `queued`, `sent`, `delivered`, `failed`, `rejected`.
`segments`required	`integer`
`charge`required	`object`
`charge.currency`required	`string`	One of `USD`, `NGN`, `KES`.
`charge.amount`required	`string`	Decimal string in the team's wallet currency.
`reason`required	`object`	Set when the status is failed or rejected. Plain language, never a provider code. Can be null.
`reason.code`required	`string`
`reason.message`required	`string`
`createdAt`required	`string`
`updatedAt`required	`string`

404No message with this id belongs to the team.