Send and validate code

Before you start writing your integration code, read our getting started and setup guides.

What’s a session?

Plivo’s Verify API is designed around the concept of sessions. Each interaction with a user is a session. A session can have multiple attempts. Let’s say you send an OTP to a user at 10:00 a.m. with an expiry of 10 minutes. This activity initiates a session between you and your user that will expire at 10:10 a.m. You can send one or more requests to this user in this duration, and all the attempts will be considered part of the same session.

Plivo lets you choose the length of your sessions and numbers of attempts that you can make to one destination within a session. All requests within a session deliver the same OTP to the user.

Send 2FA code

Once you’ve set up an application, you can send OTPs to users with a simple API request, specifying the application to use, the intended destination number, and the channel that you want to use. Plivo will generate a code for you and send it to the specified destination using the specified channel. If your code is not delivered in the first SMS attempt, you can try sending another SMS or try voice as an alternate route using the same API and Plivo will attempt to deliver the same OTP.

You can also specify a URL for callbacks and Plivo will send you status updates on this URL.

Code

1
2
3
4
5
6
7
8
9
10
curl -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{ 
     "app_uuid":"<app_uuid>",
    "recipient": "<recipient>",
    "url":"<callback_url>",
    "channel":"sms",
    "method":"POST"
}' \
    https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/

Response

{
    "api_id": "3335cb16-d297-4e00-a5e6-66d2bb03b323",
    "message": "Session initiated",
    "session_uuid": "8e712097-8090-4644-81e7-8f4265d8354e"
}

Validate code

When your user enters the OTP you sent into a form for authentication, you can validate it using Verify’s validation API, which requires you to pass the session UUID and the OTP that you want to validate. You can attempt no more than 10 validations for a session, to stop brute-force hacking attacks.

Code

1
2
3
4
5
6
curl -i --user auth_id:auth_token \
    -H "Content-Type: application/json" \
    -d '{ 
    "OTP": "<otp>"
}' \
    https://api.plivo.com/v1/Account/{auth_id}/Verify/Session/{session_uuid}/

Response

{
    "api_id": "e7af31b5-a7cb-40d6-a3ab-122fdcc9f0fe",
    "message": "session validated successfully.",
}

Other features

You can also fetch details of your session or multiple sessions at once by using APIs. The same details are also available on the Plivo console.