Sender Names

Every SMS you send goes out from a Sender Name, and each Sender Name must be approved before you can send with it. You can manage the whole lifecycle programmatically: request a new Sender Name, check its approval status, and cancel a request you no longer need.

There are two kinds of sender:

• Alphanumeric Sender Names (e.g. AcmeCorp) — reviewed and approved by the divergent team, per country.
• UK mobile numbers (e.g. 07700900123) — approved automatically once you prove ownership of the number via an SMS verification code.

Note

These operations are currently REST-only — they aren’t yet exposed by the .NET or Node.js client libraries.

Requesting a Sender Name

POST

/sms/senders

Requests are idempotent: re-submitting a Sender Name you’ve already requested returns the existing senderNameId with created: false, and any newly listed countries are added to the existing request.

curl -X POST https://connect-api.divergent.cloud/sms/senders \
  -H "X-Api-Key: { API_KEY }" \
  --json '{
    "senderName": "AcmeCorp",
    "sampleContent": "Hi Jane, your order #1234 has shipped and will arrive tomorrow.",
    "countries": ["GBR", "IRL"]
  }'

Request Data

Headers

X-Api-Key

required

string

The API Key for your Workspace.

JSON Data

senderName

required

string

The Sender Name to register: 3 to 11 letters, digits or underscores, with no spaces. Alternatively a UK mobile number in 07 format (not +44), which triggers the number verification flow below.

sampleContent

required

string

format: 20–256 chars

Sample content representative of the messages you'll send from this Sender Name. Used during review.

countries

required

string[]

The countries to register this Sender Name in, as ISO 3166-1 alpha-3 codes (e.g. GBR, IRL, FRA). At least one is required.

apiVerify

boolean

UK mobile numbers only. When true, the verification SMS contains just the code, ready to be submitted back via the verify endpoint. When omitted, the recipient is instead asked to email the code to divergent support.

Response Data

JSON Data

senderNameId

string

The ID of the Sender Name request. Use it to cancel the request later.

created

boolean

False when this Sender Name was already registered for your Workspace, in which case the existing request is returned (and any new countries are added to it).

Responses

200 OK

The request was registered (or already existed). For UK mobile numbers, a verification code has been texted to the number.

---

400 Bad Request

Validation failed, or (for UK mobile numbers) you already have another number awaiting verification — finish or cancel that one first.

---

409 Conflict

UK mobile numbers only: this number was previously rejected. Contact support.

---

429 Too Many Requests

UK mobile numbers only: too many verification code requests. Try again later.

Verifying a UK Mobile Number

When you request a UK mobile number as a sender, an 8-character verification code is texted to that number. Submit it here to prove ownership — the sender is approved immediately on success.

POST

/sms/senders/verify

curl -X POST https://connect-api.divergent.cloud/sms/senders/verify \
  -H "X-Api-Key: { API_KEY }" \
  --json '{
    "sender": "07700900123",
    "code": "{ CODE }"
  }'

Request Data

Headers

X-Api-Key

required

string

The API Key for your Workspace.

JSON Data

sender

required

string

The mobile number awaiting verification, exactly as it was requested (07 format).

code

required

string

The 8-character code received by SMS. Case-insensitive; surrounding whitespace is ignored.

Responses

200 OK

The number is verified and the sender is now approved.

---

400 Bad Request

Invalid sender or code. For security, an unknown sender and a wrong code are deliberately indistinguishable.

---

429 Too Many Requests

Too many failed attempts — the sender is temporarily locked out. Try again later.

Tip

Need the code re-sent? Just re-submit the same request to POST /sms/senders — a fresh code is texted each time, within rate limits.

Checking Sender Status

GET

/sms/senders

Returns every sender in your Workspace — Sender Names alongside any virtual (inbound) numbers — with their approval state. There are no query parameters; filter client-side. A sender awaiting review or verification appears with isApproved: false.

curl https://connect-api.divergent.cloud/sms/senders \
  -H "X-Api-Key: { API_KEY }"

Request Data

Headers

X-Api-Key

required

string

The API Key for your Workspace.

Response Data

JSON Data

senders

array

Every sender registered to your Workspace.

id

string

The Sender Name ID.

name

string

The sender as it appears on messages — the Sender Name, or the phone number for virtual numbers.

isApproved

boolean

Whether the sender has been approved overall. False while a request is awaiting review or verification.

requiresNumberVerification

boolean

True for UK mobile number senders that are (or were) subject to SMS ownership verification.

type

string

format: SenderName | InboundNumber

The kind of sender.

countries

array

Per-country approval for Sender Names. Sending in a country relies on that country being approved. Empty for virtual numbers.

country

string

ISO 3166-1 alpha-3 country code.

isApproved

boolean

Whether the sender is approved for this country.

Example Response

{
  "senders": [
    {
      "id": "1042",
      "name": "AcmeCorp",
      "isApproved": true,
      "requiresNumberVerification": false,
      "type": "SenderName",
      "countries": [
        { "country": "GBR", "isApproved": true },
        { "country": "IRL", "isApproved": false }
      ]
    },
    {
      "id": "1043",
      "name": "07700900123",
      "isApproved": false,
      "requiresNumberVerification": true,
      "type": "SenderName",
      "countries": [
        { "country": "GBR", "isApproved": false }
      ]
    }
  ]
}

Note

Approval usually happens quickly during UK business hours. If a request stays pending for longer than expected, contact support — they can tell you if anything further is needed.

Cancelling a Request

Cancel a Sender Name request that’s still pending. You can cancel the whole request, or just specific countries that haven’t been approved yet. Approved countries can’t be cancelled through the API — contact support instead.

DELETE

/sms/senders/{id}

# Cancel the entire request
curl -X DELETE https://connect-api.divergent.cloud/sms/senders/{ SENDER_NAME_ID } \
  -H "X-Api-Key: { API_KEY }"

# Cancel only specific pending countries
curl -X DELETE "https://connect-api.divergent.cloud/sms/senders/{ SENDER_NAME_ID }?countries=IRL&countries=FRA" \
  -H "X-Api-Key: { API_KEY }"

Request Data

Headers

X-Api-Key

required

string

The API Key for your Workspace.

Query Parameters

countries

string[]

Pending countries to cancel, as ISO 3166-1 alpha-3 codes. May also be supplied as a JSON body. If omitted, the whole request is cancelled.

Responses

200 OK

The request (or the specified countries) was cancelled.

---

400 Bad Request

A specified country isn’t part of the request or is already approved, or the sender has already been used to send messages.

---

404 Not Found

No Sender Name with that ID exists in your Workspace.

---

409 Conflict

The request was updated concurrently. Refresh and try again.