Cookie

Cookie consent

We use some essential cookies to make this website work. We'd like to set additional cookies to help us measure your experience when you view and interact with the website.

Cookie policy

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

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

Path and body parameters

ParameterDescriptionExample
apikeyYour API keyPCW45-12345-12345-1234X
toThe 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
fromThe URL-encoded sender name; the name must use GSM7 characters only and have a length between 3 and 11 charactersExample.com
messageThe 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 messageHello from [from]. Your security code is [otp]. It will expire in [expiry] minutes. Do not share this code.
otplengthThe 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 106
expiryThe expiry time of the OTP in minutes; the default time is 5 but when supplied, the time must be an integer between 2 and 305

Querystring parameters

ParameterDescriptionExample
formatSets the format of the response, xml or json (default unless "application/xml" header is detected)format=json
identifierSpecifies 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 clientsidentifier=websiteA

Example request and response

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

FieldDescriptionExample
idAn ID for the OTP which must be supplied in requests to the otp/verify endpointOTP45-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:

  1. 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.
  2. 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.
  3. 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.