Test Credentials
Twilio provides you with a set of test credentials so you can exercise parts of the REST API without charging your account. You can find your credentials in the Auth Tokens page of your Console.
You use these credentials in the same way as your live credentials, with one restriction being that you cannot login to the Twilio CLI with your test credentials. However, when you authenticate with your test credentials, we will not charge your account, update the state of your account, or connect to real phone numbers. You can now pretend to buy a phone number, or send an SMS, without actually doing so.
To protect your production data, your test credentials can't interact with the data in your real account. For example, you can't use phone numbers from your real account as the 'From' number in requests made with your test credentials.
Supported Resources
Your test credentials can currently be used to interact with the following three resources:
- Buying phone numbers:
POST /2010-04-01/Accounts/{TestAccountSid}/IncomingPhoneNumbers
- Sending SMS messages:
POST /2010-04-01/Accounts/{TestAccountSid}/Messages
- Making calls:
POST /2010-04-01/Accounts/{TestAccountSid}/Calls
Requests to any other resource with test credentials will receive a 403 Forbidden
response. In the future, we may enable these resources for testing
as well.
A limitation of SMS messages and calls made using test credentials is that they will not trigger status callbacks. Learn more about status callbacks for SMS and status callbacks for Voice.
Magic Input
When you make an API request with your test credentials, Twilio will validate all input as though the request were made with your real credentials. However, there are some cases when a request's validity depends on the state of Twilio. For instance, if you are trying to buy a phone number and that phone number is no longer available, Twilio will return an error.
In order to write test cases that expect and handle errors which depend on
the state of Twilio, we provide magic inputs. For the case mentioned above,
there is a magic phone number +15005550000
which, if you pass it as the
'PhoneNumber' parameter in a POST to IncomingPhoneNumbers, will always return
an error saying the number is unavailable.
The full set of magic inputs is detailed below.
Test Buying A Number
If you'd like to test API requests to the phone numbers resource without actually provisioning a number for your account, you can use your test credentials.
You use these credentials in exactly the same way as your live credentials. However, when you authenticate with your test credentials, we will not charge your account or purchase a phone number for you. This way, you can pretend to buy a phone number without actually doing so.
Just POST to the normal phone number purchase API endpoint using your test credentials to authenticate and your TestAccountSid in the URL:
POST https://api.twilio.com/2010-04-01/Accounts/{TestAccountSid}/IncomingPhoneNumbers
Parameters
All of the existing phone number purchase parameters will work. In addition, we provide some specific values for certain parameters to help you generate success and failure cases.
PhoneNumber
Value | Description | Error Code |
---|---|---|
+15005550000 | This phone number is unavailable. | 21422 |
+15005550001 | This phone number is invalid. | 21421 |
+15005550006 | This phone number is valid and available. | No error |
AreaCode
Value | Description | Error Code |
---|---|---|
533 | This area code doesn't have any available phone numbers. | 21452 |
500 | This area code has an available number. | No error |
Example 1
Successfully provision a number. Purchase will always complete successfully if
you attempt to purchase the magic number +15005550006
. Any other parameters
you send with the request, such as a VoiceUrl
or a StatusCallback
, will be
included in the API response.
Example 2
Attempt to purchase an unavailable number. Trigger this by passing the magic
number +15005550000
.
Example 3: Attempt to buy invalid number
Just specify an invalid number as your input. Twilio will try to convert letters to numbers, but specifying a very short or very long string of either will fail.
Test Sending an SMS
If you'd like to test API requests to send SMS messages without charging your account or sending an SMS, you can use your test credentials.
Just POST to the normal SMS API endpoint using your test credentials to authenticate and your TestAccountSid in the URL:
POST https://api.twilio.com/2010-04-01/Accounts/{TestAccountSid}/Messages
Parameters
All of the existing outbound SMS
parameters will work, with the exception of MessagingServiceSid
. In addition,
we provide some specific values for certain parameters to help you generate
success and failure cases.
From
Your test credentials don't have access to any valid 'From' phone numbers on your real account. Therefore the only phone numbers you should use as 'From' numbers are the magic numbers listed here.
Value | Description | Error Code |
---|---|---|
+15005550001 | This phone number is invalid. | 21212 |
+15005550007 | This phone number is not owned by your account or is not SMS-capable. | 21606 |
+15005550008 | This number has an SMS message queue that is full. | 21611 |
+15005550006 | This number passes all validation. | No error |
All Others | This phone number is not owned by your account or is not SMS-capable. | 21606 |
To
Value | Description | Error Code |
---|---|---|
+15005550001 | This phone number is invalid. | 21211 |
+15005550002 | Twilio cannot route to this number. | 21612 |
+15005550003 | Your account doesn't have the international permissions necessary to SMS this number. | 21408 |
+15005550004 | This number is blocked for your account. | 21610 |
+15005550009 | This number is incapable of receiving SMS messages. | 21614 |
All Others | Any other phone number is validated normally. | Input-dependent |
Example 1
Successfully send an SMS. Trigger this by sending an SMS using the magic number
+15005550006
as the From
number, and a regular phone number for the To
number.
Example 2
Attempt to send a message to a non-mobile number. Trigger this by passing the
magic number +15005550009
as the To
number.
Example 3
Attempt to send a message with an empty SMS body. No need for magic numbers, the validation error will be raised normally.
Test Making a Call
If you'd like to test API requests to the outbound call endpoint without charging your account or making a call, you can use your test credentials. Note that since no call is made, Twilio will not make a request to the URL passed in the 'Url' parameter and no TwiML will be executed.
Just POST to the normal outbound call API endpoint using your test credentials to authenticate and your TestAccountSid in the URL:
POST https://api.twilio.com/2010-04-01/Accounts/{TestAccountSid}/Calls
Parameters
All of the existing outbound call parameters will work. In addition, we provide some specific values for certain parameters to help you generate success and failure cases.
From
Your test credentials don't have access to any valid 'From' phone numbers on your real account. Therefore the only phone number you should use as a 'From' number is the magic number listed here.
Value | Description | Error Code |
---|---|---|
+15005550001 | This phone number is invalid. | 21212 |
+15005550006 | This number is a valid From number for your account. |
No error |
All Others | The phone number is not verified for your account. | 21210 |
To
Value | Description | Error Code |
---|---|---|
+15005550001 | This phone number is invalid. | 21217 |
+15005550002 | Twilio cannot route to this number. | 21214 |
+15005550003 | Your account doesn't have the international permissions necessary to call this number. | 21215 |
+15005550004 | This number is blocked for your account. | 21216 |
All Others | Any other phone number is validated normally. | Input-dependent |
Example 1
Successfully enqueue an outgoing call. Use the magic number +15005550006
as
the From
number and any regular number as the To
number.
Example 2
Attempt to call an international number in a country without permissions turned
on. Trigger this by passing the magic number +15005550003
as the To
number.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.