# Toll-Free
## What is a Toll-Free number?
Toll-free SMS numbers are 10-digit numbers with an 800 “area code” as the leading digits (example: 800-780-8000).
Text-enabled toll-free numbers allow you to send messages at decent messaging speeds without adding extra fees.
All accounts at Mobile Text Alerts include a dedicated toll-free number for free.
### Toll-free Verification
Toll-free numbers must be verified, this reduces the risk of filtering your message traffic. This is a mandatory industry-wide process that whitelists your text messaging traffic.
When you first create your account, you will need to enter your Brand Registration information. This includes your company's contact information, expected messaging use case and messages, and a Privacy Policy for compliance. After submitting this information, MTA will submit your Toll-Free number to carriers for approval.
You can call the [`/dedicated-numbers`](#dedicated-numbers) endpoint of the API to see the status of your toll-free number(s) with the [`tollFreeVerificationStatus`](#verification-status) field..
10DLC vs Toll-Free vs Short Code
### **Pros for using a toll-free number**
* The registration process for toll-free numbers is free.
* Toll-free numbers usually allow for higher messaging speeds than 10DLCs (1,200 messages per minute as opposed to 150 messages per minute).
* Toll-free number registration doesn’t require an EIN/tax ID, so sole proprietors and very small businesses may have an easier time getting registered.
* Toll-free numbers have no daily limits, unlike 10DLCs which have a daily limit of around 2,000.
### **Cons for using a toll-free number**
* Toll-free numbers generally have much slower messaging speeds than short codes (though they are faster than 10DLCs).
* Toll-free numbers may not seem as personable (and therefore not get as much engagement) as 10DLC’s because the “area code” is a generic 800 number.
* Toll-free numbers aren’t as convenient as dedicated short codes, because they are longer numbers.
### Toll-free throughput and limits
Toll-free numbers will give you significantly higher throughput than 10DLC’s, at **1,200 text messages per minute**.
Unlike 10DLCs, toll-free numbers have no daily limits.
### Summary
Mobile Text Alerts generally recommends toll-free numbers over 10DLCs because registration for toll-free numbers is always free, and they have faster messaging speeds. But they do sacrifice the benefit of a personal area code, businesses with a more robust budget may want to consider a dedicated short code.
## **Get a toll-free number for sending messages**
A dedicated toll-free number is included for free with any Mobile Text Alerts subscription. You can get started in seconds to test it out for yourself and for your business today.
Make sure to submit the **Brand Registration** form that appears at the top of the main dashboard page when you log in to your account.
## View your Numbers with the API
Just as you can view your numbers on the [platform dashboard](https://platform.mobile-text-alerts.com/dedicated-numbers), you can view all numbers on your account by calling the [`/dedicated-numbers`](#get-dedicated-numbers) endpoint of the API. This will list data name, type, status, and more.
### Verification Status
This endpoint will return the verification status of your toll-free number(s) with `tollFreeVerificationStatus` this is an `ENUM` value (0-5) that corresponds with the following statuses:
* `0` - Not Submitted
* `1` - Verification Form Complete
* `2` - Submitted for Review by Carriers
* `3` - Approved by Carrier
* `4` - Denied by Carrier
* `5` - Submission Failure Reported by Carrier
#### Example request
```bash
curl --location 'https://api.mobile-text-alerts.com/v3/dedicated-numbers' \
--header 'Authorization: Bearer 3068eebf-7611-5458-830e-65tf055a0b95'
```
#### Example response
```json
{"data":
{"rows":
[{"name":"Main Phone Number",
"created":"2025-01-27T15:26:48.000Z",
"longcodeId":10721,"number":"8332298025",
"tollFree":1,
"isShortcode":0,
"branded":0,
"pending":1,
"verified":0,
"countryCode":"US",
"users":{},
"type":"Toll-Free",
"status":"Basic",
"deliveryRate":0,
"tollFreeVerificationStatus":0,
"tollFreeVerificationSubmissionDate":"2025-03-25T18:21:23.276Z"
}],
"page":0,"pageSize":25,"total":1
}
}
```
## GET /dedicated-numbers
> List Dedicated Numbers
```json
{"openapi":"3.0.0","info":{"title":"Mobile Text Alerts API","version":"8.0.0"},"servers":[{"url":"https://api.mobile-text-alerts.com/v3"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"apiKey"}},"schemas":{"ListDedicatedNumbers.Response":{"allOf":[{"$ref":"#/components/schemas/IApiResponsePaginated"},{"type":"object","properties":{"data":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/IApiLongcodeJoin"}},"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"}},"required":["rows","page","pageSize","total"]}},"required":["data"]}]},"IApiResponsePaginated":{"allOf":[{"$ref":"#/components/schemas/IApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"rows":{"type":"array","items":{}},"page":{"type":"number"},"pageSize":{"type":"number"},"total":{"type":"number"}},"required":["rows","page","pageSize","total"],"description":"PaginationData"}},"required":["data"]}]},"IApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"},"data":{}},"required":[]},"IApiLongcodeJoin":{"type":"object","properties":{"name":{"type":"string"},"created":{"type":"string"},"longcodeId":{"type":"number"},"number":{"type":"string"},"tollFree":{"type":"number"},"isShortcode":{"type":"number"},"branded":{"type":"number"},"pending":{"type":"number"},"verified":{"type":"number"},"countryCode":{"type":"string"},"users":{"type":"object","additionalProperties":{"type":"string"}},"type":{"type":"string"},"status":{"$ref":"#/components/schemas/DedicatedNumberStatus"},"deliveryRate":{"type":"number"},"tollFreeVerificationStatus":{"allOf":[{"$ref":"#/components/schemas/TollFreeVerificationStatus"},{"$ref":"#/components/schemas/NullReference"}]},"tollFreeVerificationSubmissionDate":{"type":"string","nullable":true}},"required":["name","created","longcodeId","number","tollFree","isShortcode","branded","pending","verified","countryCode","users"]},"DedicatedNumberStatus":{"type":"string","enum":["Basic","Pending Carrier Approval","Carrier Approved","Undefined"]},"TollFreeVerificationStatus":{"format":"int32","type":"number","enum":[1,2,3,4,5]},"NullReference":{"title":"Null Reference","description":"Used when a reference can be null","enum":[null]}},"responses":{"BadRequestError":{"description":"BadRequestError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[400]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["bad_request_error"]},"name":{"type":"string","enum":["MTABadRequestError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"UnauthorizedError":{"description":"UnauthorizedError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[401]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["unauthorized_error"]},"name":{"type":"string","enum":["MTAUnauthorizedError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"ForbiddenError":{"description":"ForbiddenError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[403]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["forbidden_error"]},"name":{"type":"string","enum":["MTAForbiddenError"]},"requestId":{"type":"string","format":"uuid"},"reason":{}}}}}},"InternalServerError":{"description":"InternalServerError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[500]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["internal_server_error"]},"name":{"type":"string","enum":["MTAInternalServerError"]},"requestId":{"type":"string","format":"uuid"}}}}}}}},"paths":{"/dedicated-numbers":{"get":{"tags":["Dedicated Numbers"],"summary":"List Dedicated Numbers","operationId":"dedicated_numbers_list_dedicated_numbers","responses":{"200":{"description":"Success","headers":{"RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"Retry-After":{"description":"The number of seconds to wait before retrying the request","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"The maximum number of requests that the consumer is permitted to make per window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"The number of requests remaining in the current rate limit window","schema":{"type":"integer"}},"X-RateLimit-Reset":{"description":"The remaining window before the rate limit resets in milliseconds","schema":{"type":"integer"}},"X-Request-ID":{"description":"A unique identifier for the request","schema":{"type":"string","format":"uuid"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListDedicatedNumbers.Response"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}},"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"number"}},{"name":"pageSize","in":"query","required":false,"schema":{"type":"number"}},{"name":"sortBy","in":"query","required":false,"schema":{"type":"string"}},{"name":"sortDirection","in":"query","required":false,"schema":{"type":"string","enum":["asc","desc","ASC","DESC"]}},{"name":"order","in":"query","required":false,"schema":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"string","enum":["asc","desc","ASC","DESC"]}]},"minItems":2,"maxItems":2,"description":"The first item in the array must be the first item type and the second must be the second item type."}},{"name":"query","in":"query","required":false,"schema":{"type":"string"}},{"name":"filters","in":"query","required":false,"schema":{"type":"object","properties":{"isTollfree":{"type":"boolean"},"userId":{"type":"number"},"pending":{"type":"boolean"}},"required":[]}}]}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developers.mobile-text-alerts.com/messaging-routes/toll-free.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
