POST
/
authentication
curl --request POST \
  --url https://api.ding.live/v1/authentication \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '{
  "customer_uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "phone_number": "+1234567890",
  "ip": "127.0.0.1",
  "device_id": "<string>",
  "device_type": "IOS",
  "app_version": "<string>",
  "sender_id": "<string>",
  "callback_url": "<string>",
  "app_realm": "<string>",
  "os_version": "<string>",
  "device_model": "<string>",
  "is_returning_user": true,
  "template_id": "<string>",
  "correlation_id": "<string>",
  "locale": "en-US"
}'
{
  "authentication_uuid": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "status": "pending",
  "created_at": "2023-11-07T05:31:56Z",
  "expires_at": "2023-11-07T05:31:56Z"
}

The V1 API is deprecated. Technical support will end by October 2025 and will be removed by April 2026. No new features nor functionality will be added to the V1 API. Please use the V2 Verify API instead. For more information refer to the V2 Migration Guide.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
customer_uuid
string
required

Your customer UUID, which can be found in the API settings in the dashboard.

​
phone_number
string
required

An E.164 formatted phone number to send the OTP to.

Example:

"+1234567890"

​
ip
string

The IP address of the user's device.

​
device_id
string

Unique identifier for the user's device. For Android, this corresponds to the ANDROID_ID and for iOS, this corresponds to the identifierForVendor.

​
device_type
enum<string>

The type of device the user is using.

Available options:
IOS,
ANDROID,
WEB
​
app_version
string

The version of your application.

​
sender_id
string

The Sender ID to use when sending the message.

​
callback_url
string

A webhook URL to which delivery statuses will be sent.

​
app_realm
string

The Android SMS Retriever API hash code that identifies your app. This allows you to automatically retrieve and fill the OTP code on Android devices.

​
os_version
string

The version of the user's device operating system.

​
device_model
string

The model of the user's device.

​
is_returning_user
boolean

This signal should do more than just confirm if a user is returning to your app; it should provide a higher level of trust, indicating that the user is genuine.

​
template_id
string

The template id associated with the message content variant to be sent.

​
correlation_id
string

A unique, user-defined identifier that will be included in webhook events

​
locale
string

A BCP-47 locale indicating the language the SMS should be sent to; if this is not set, the SMS will be sent to the language specified by the country code of the message. If we don't support the language set, the message will be sent in US English (en-US).

Example:

"en-US"

Response

200
application/json
OK

A successful response to an authentication creation request.

​
authentication_uuid
string

A unique identifier for the authentication that you can use on the /check and /retry endpoints.

​
status
enum<string>

The status of the authentication. Possible values are:

  • pending - The OTP code is being sent.
  • rate_limited - This user is rate-limited and cannot receive another code.
  • spam_detected - This attempt is flagged as spam. Go to the dashboard for more details.
Available options:
pending,
rate_limited,
spam_detected
​
created_at
string
​
expires_at
string

The time at which the authentication expires and can no longer be checked or retried.