Messaging¶

The Message APIs allow you to send messages (SMS, WhatsApp, etc.) across a global network, with supporting methods for lookup and validation of mobile numbers.

Info

This page describes the API 3.2 routes. Use the Scalar API 3.2 reference for the generated request and response schemas.

Sending a Message¶

Send a message anywhere in the world.

URL: base/Message
Method: POST

{
  "source": "12345678901",
  "destination": "12345678901",
  "message": "message",
  "reply": true,
  "when": "2026-09-02T10:00:00Z",
  "window": [{ "from": "09:00", "to": "16:00", "days": "1,2,3,4,5"}],
  "lookup": true,
  "test": false,
  "timeout": 4320,
  "type": 0,
  "onBehalf": null,
  "surveyId": null
}

Parameters¶

Name	Type	Description
Source	Mandatory	The source of the message. This can be a short code, a long number or a branded value up to 11 characters long.
Destination	Mandatory	The destination of the message. This must be the full number prefixed with the country code and no leading zeros. This controls the destination of the message and helps with Windows.
Message	Mandatory	The text of the message to send, the formatting of which is dependent on the Type being targeted.
Reply	Mandatory	A boolean value indicating whether the message can be replied to or not. If this is true then the source may be replaced depending on destination value and the route the message has to take to get to its destination. Importantly, this flag allows you to get a reply through an appropriately configured web hook or callback.
When	Optional (Default: now)	A date and time indicating when the message should be sent. This allows the opportunity to submit a message to be sent at a later date.
Window	Optional (Default: any time)	An array of time windows that the message can be sent. This allows you to specify different time windows as to when the message can be sent. Each window follows these rules.
Lookup	Optional (Default: false)	A boolean value indicating whether a lookup on the destination number should be carried out before it is sent to see whether the number is a landline or mobile. If the number is a landline it will not be sent. This combines the lookup method and the send into one process for you.
Test	Optional (Default: false)	A boolean value that indicates whether the message should be sent or not. If set to true the message will not be sent, but the internal DIY Surveys Routing will be tested.
Timeout	Optional (Default: 4320)	A numeric value defining the number of minutes the DIY Surveys Platform will maintain a message to be replied to. The default is 3 days.
Type	Optional (Default: 0)	A numeric value indicating the type of message: 0 = Sms 1 = WhatsApp 2 = Facebook 3 = WhatsAppTemplate For more information please check here.
OnBehalf	Optional	Identifies the account or organization on whose behalf the message is sent, where configured.
SurveyId	Optional	Associates the message with a survey.
### Returns

{
    "MessageID": "MS1312312312323",
    "Status": "sent",
    "Carrier": "EE",
    "Reachable": true,
    "NumberType": "Mobile"
}

Return Values¶

Name	Description
MessageID	The DIY Surveys Message ID available for you to track the message in other methods and callbacks.
Status	The initial status of the send. This can be any one of the following values.
If a lookup is performed as part of the process the following return values will be included:

Name	Description
Carrier	The name of the carrier. This can be any valid string or the word `Unknown`.
Reachable	A boolean value indicating whether the number is reachable.
NumberType	A string indicating the type of number: `Mobile`, `Landline` or `Unknown`.
### HTTP Statuses

In addition to the standard responses the following HTTP statuses can be returned:

Status	Description
400	The destination number is invalid.
400	The destination and source cannot be the same.
400	The message length must be greater than zero.
400	There was a problem sending the message. Please refer to the status.

Sending Messages without a Callback¶

If you send a message without a callback, additional responses can be returned with an HTTP status of 400:

Landline detected¶

{
    "MessageID": "Unknown",
    "Status": "Reachable",
    "Carrier": "EE",
    "Reachable": true,
    "NumberType": "Landline"
}

Blocked number¶

{
    "MessageID": "Unknown",
    "Status": "Blocked",
    "Carrier": "EE",
    "Reachable": false,
    "NumberType": "Mobile"
}

Kill¶

Warning

The message-kill operation is not exposed by API 3.2. Existing integrations that use DELETE /api/v3.1/Message/Kill must not assume an equivalent 3.2 route.

Lookup¶

Lookup a number on the network to see whether it is reachable and whether it is a mobile number.

URL: base/Message/Lookup/{number}
Method: GET

Parameters¶

Name	Description
`number`	The number to look up, supplied in the URL path using E.164 digits only (for example, `441234567890`).

Returns¶

{
  "messageID": "MS1312312312323",
  "status": "Success",
  "carrier": "EE",
  "reachable": true,
  "numberType": "Mobile"
}

Return Parameters¶

Name	Description
`messageID`	The unique identifier for the lookup.
`status`	The result of the lookup.
`carrier`	The carrier associated with the number, where available.
`reachable`	Whether the number can be reached.
`numberType`	The number classification, such as `Mobile`, `Landline`, `VoIP`, or `Unknown`.

HTTP Statuses¶

In addition to the standard responses the following HTTP statuses can be returned:

Status	Description
400	There was a problem with the Lookup. Please check your request and try again.