Twilio Verify Getting Started: Account, Keys & First API Call

Getting started overview

Integrating Twilio Verify into your application requires a sequential setup process covering account creation, credential retrieval, and service configuration. This guide outlines the steps to get a basic verification flow operational, from signing up for a Twilio account to sending your initial verification request.

The core components for a functional integration are your Twilio Account SID, Auth Token, and a Verify Service SID. These credentials authenticate your API requests and define the verification logic and channels. Twilio provides extensive API documentation and language-specific SDKs to streamline this process.

Quick Reference Steps

Create an account and get keys

To begin using Twilio Verify, you must first create a Twilio account. The Twilio sign-up process typically involves providing an email, creating a password, and verifying your email address. New accounts often receive a trial balance or access to a free tier, which includes 10,000 free verifications per month for Verify.

Once your account is active, your primary API credentials — the Account SID and Auth Token — are accessible from your Twilio Console Dashboard. The Account SID uniquely identifies your Twilio account, while the Auth Token serves as your secret key for authenticating API requests. Keep your Auth Token confidential, similar to how you would manage a password, to prevent unauthorized access to your account and services.

Beyond these foundational credentials, Twilio Verify requires the creation of a "Verify Service." This service acts as a container for your verification settings, including custom message templates, allowed verification channels (e.g., SMS, email, voice), and code length. To create a new Verify Service:

1. Navigate to the Twilio Verify Services section in the console.
2. Click the "Create new Verify Service" button.
3. Provide a friendly name for your service (e.g., "My App Verification").
4. Configure any desired settings, such as custom messaging templates or enabled channels.
5. Save the service. Twilio will then display your unique Verify Service SID (e.g., VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx). This SID is crucial for all Verify API calls associated with this service.

It is recommended to store your Account SID, Auth Token, and Verify Service SID as environment variables in your development and production environments rather than hardcoding them directly into your application code. This practice enhances security and simplifies credential management, as outlined in security best practices by organizations like the Internet Engineering Task Force (IETF).

Your first request

After obtaining your Account SID, Auth Token, and Verify Service SID, you can initiate your first verification request. This involves two main steps: starting a verification and then checking the user-provided code. The following examples demonstrate how to send and check an SMS verification using curl and Node.js.

Example: Sending an SMS Verification (cURL)

To initiate a verification code delivery via SMS, send a POST request to the Verify API endpoint. Replace the placeholder values with your actual credentials and the recipient's phone number.

curl -X POST 'https://verify.twilio.com/v2/Services/VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/Verifications'
-u ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:your_auth_token \
-d 'To=+15558675310' \
-d 'Channel=sms'

A successful response will include a status of pending and details about the verification attempt.

Example: Checking an SMS Verification (cURL)

Once the user receives the code and provides it to your application, you must verify it against Twilio. Send a POST request to the verification check endpoint, including the user's phone number and the code they entered.

curl -X POST 'https://verify.twilio.com/v2/Services/VAxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/VerificationCheck'
-u ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:your_auth_token \
-d 'To=+15558675310' \
-d 'Code=123456'

A successful check will return a status of approved if the code is correct, or pending/canceled/failed otherwise.

Example: Sending an SMS Verification (Node.js using Twilio SDK)

Using the official Twilio Node.js SDK simplifies API interactions. First, install the SDK:

npm install twilio

Then, use the following code to send a verification:

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const verifyServiceSid = process.env.TWILIO_VERIFY_SERVICE_SID;

const client = require('twilio')(accountSid, authToken);

client.verify.v2.services(verifyServiceSid)
  .verifications
  .create({to: '+15558675310', channel: 'sms'})
  .then(verification => console.log(verification.sid));

Example: Checking an SMS Verification (Node.js using Twilio SDK)

const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const verifyServiceSid = process.env.TWILIO_VERIFY_SERVICE_SID;

const client = require('twilio')(accountSid, authToken);

client.verify.v2.services(verifyServiceSid)
  .verificationChecks
  .create({to: '+15558675310', code: '123456'})
  .then(verification_check => console.log(verification_check.status));

These examples provide a foundational understanding of how to interact with the Twilio Verify API. For other languages and channels, consult the Twilio Verify API reference.

Common next steps

After successfully sending and checking your first verification, consider these common next steps to enhance your integration:

• Implement other channels: Explore email verification, voice verification, or push authentication (TOTP/HOTP) to offer users more options and improve deliverability reliability.
• Customize messages: Configure custom SMS or email templates within your Verify Service to align with your brand voice and provide clearer instructions to users. This can be done through the Twilio Console.
• Error handling and retries: Implement robust error handling for API responses, distinguishing between network issues, invalid inputs, and rate limit errors. Design a retry mechanism that incorporates exponential backoff to manage transient failures effectively, a common practice in API integration best practices.
• Secure your credentials: Reinforce the use of environment variables for your Account SID, Auth Token, and Verify Service SID. Avoid committing sensitive information to version control systems like Git.
• Webhooks for status updates: Configure webhooks to receive real-time updates on verification statuses. This can be particularly useful for asynchronous channels or for logging purposes. Refer to the Twilio webhook documentation for setup details.
• Explore advanced features: Investigate features like Silent Network Auth for seamless mobile verification or the ability to override verification codes for testing environments.
• Monitor usage: Regularly check your Twilio usage dashboard to monitor verification attempts, successful verifications, and associated costs, especially if you anticipate exceeding the free tier.

Troubleshooting the first call

Encountering issues during your first API call is common. Here are some troubleshooting tips for Twilio Verify:

• Check your credentials: Double-check that your Account SID, Auth Token, and Verify Service SID are correct and haven't been mistyped. Ensure they are being passed correctly in your API request (e.g., in the Basic Auth header for cURL or through the SDK client).
• Verify phone number format: Ensure the To parameter (or equivalent in your SDK) uses the E.164 international format (e.g., +15558675310). Incorrect formatting is a frequent cause of failed verifications.
• Service SID validity: Confirm that the Verify Service SID you are using is active and correctly configured in your Twilio account.
• Channel availability: If you're attempting an SMS or voice verification, ensure your Twilio account has outbound messaging capabilities for the target country. For email, ensure your email integration is set up correctly within the Verify Service.
• Examine API response: Always inspect the full API response, including status codes and error messages. Twilio provides specific error codes and descriptions that can pinpoint the exact problem.
• Network connectivity: Ensure your development environment has outbound internet access to reach Twilio's API endpoints. Proxy settings or firewalls can sometimes block requests.
• Rate limits: While less common for a first call, be aware that Twilio APIs have rate limits. If you're testing rapidly, you might temporarily hit these limits. The API response will typically indicate a rate limit error if this occurs.
• Twilio Console logs: The Twilio Console's Monitor Logs section provides detailed records of all API requests and responses, including any errors. This is an invaluable resource for debugging.
• Trial account limitations: If you are on a trial account, certain restrictions might apply (e.g., sending messages only to verified phone numbers). Check the Twilio trial account limitations documentation.