otp/send

Postcoder one-time password (OTP) verification provides authentication via SMS. It consists of two types of request: a send request to send an OTP within a text message to a user's UK mobile phone number, and a verify request that you can use to check the OTP provided by the user.

This is the send endpoint. It sends the OTP and returns an ID to use with the otp/verify endpoint.

OTP verification: Enable access on your API key using the Features page or by contacting us.

Request URL and body

POST https://ws.postcoder.com/pcw/{apikey}/otp/send
{
    "to": "{to}",
    "from": "{from}",
    "message": "{message}",
    "otplength": {otplength},
    "expiry": {expiry}
}

Path and body parameters

Parameter	Description	Example
`apikey`	Your API key	`PCW45-12345-12345-1234X`
`to`	The URL-encoded UK mobile phone number that you wish to send the OTP to; the number must start with 07 or the international dialling code for the United Kingdom (e.g. +44 or 0044)	`07500123456`
`from`	The URL-encoded sender name; the name must use GSM7 characters only and have a length between 3 and 11 characters	`Example.com`
`message`	The URL-encoded message to send to the mobile phone; when supplied, the message must contain the `[otp]` tag to specify the position of the OTP, use GSM7 characters only and have a maximum length of 140 characters. Optionally, the message may contain the `[from]` and `[expiry]` tags if you wish to pre-fill these values in the message	`Hello from [from]. Your security code is [otp]. It will expire in [expiry] minutes. Do not share this code.`
`otplength`	The number of characters to use for the OTP; the default number is 6 but when supplied, the number must be an integer between 2 and 10	`6`
`expiry`	The expiry time of the OTP in minutes; the default time is 5 but when supplied, the time must be an integer between 2 and 30	`5`

Querystring parameters

Parameter	Description	Example
`format`	Sets the format of the response, xml or json (default unless "application/xml" header is detected)	`format=json`
`identifier`	Specifies your own meaningful identifier for the request such as "websiteA" or "client123"; you can view usage for each identifier on the Identifier Usage page, which may be helpful when using your API key across multiple websites, apps or clients	`identifier=websiteA`

Example request and response

POST https://ws.postcoder.com/pcw/PCW45-12345-12345-1234X/otp/send?format=json
{
    "to": "07500123456",
    "from": "Example.com",
    "message": "Hello from [from]. Your security code is [otp]. It will expire in [expiry] minutes. Do not share this code.",
    "otplength": 6,
    "expiry": 5
}

HTTP response body

{
    "id": "OTP45-12345-12345-1234X"
}

Text message content

Hello from Example.com. Your security code is 532132. It will expire in 5 minutes. Do not share this code.

Response fields

Field	Description	Example
`id`	An ID for the OTP which must be supplied in requests to the otp/verify endpoint	OTP45-12345-12345-1234X

SMS pumping fraud

SMS traffic pumping is where fraudsters take advantage of a mobile phone number input field to receive a one-time passcode (OTP) via SMS. This could be on a signup or login form, or other type of form. Their aim is to send text messages to a range of numbers controlled by a specific mobile network operator and receive a share of the generated revenue.

SMS pumping: This type of fraud can lead to higher than expected Postcoder usage for you.

We recommend the following steps to help guard against SMS pumping:

Protect your API key
Postcoder provides enhanced security options for your API key. Set your API key to accept requests only from trusted IP addresses or choose rate-limited access with a very low threshold.
Protect your forms
Use a CAPTCHA on your forms to prevent bots from accessing or submitting them. This will help to ensure that only humans can trigger your requests to Postcoder.
Investigate unusual activity on your forms
Monitor the number of signups, incomplete logins or form submissions on your website, especially those which send OTPs via SMS. Investigate unusual activity.

Integration advice

URL encode all special characters (including /) in your request parameters with %xx encoding
Verify your request was successful by checking for an HTTP status code of 200; see all HTTP status codes with descriptions
No need to remove spaces, dashes, brackets or other non-numeric characters from the mobile phone number
To help mobile phones automatically recognise the OTP, use the keyword "code", "passcode" or "password" in the message with no spaces after the OTP. For example, "Hello from Example.com. Your security code is 532132. It will expire in 5 minutes. Do not share this code."
To reduce the risk of people taking advantage of your OTP workflow, review and follow our advice on SMS pumping fraud
When using your API key across multiple websites, apps or clients, set the identifier querystring parameter to a meaningful value such as "websiteA" or "client123"; you'll then be able to view these identifiers and the number of requests made by each one on the Identifier Usage page

Credit cost

Each request costs 3.7 credits.

Buy a credit pack or set up a monthly plan to use with all Postcoder endpoints.