# Short Code ## What is a dedicated short code? A dedicated short code is a 5 or 6-digit phone number for sending and receiving messages that is exclusively owned by a single brand or organization (example: 52001). Dedicated short codes have the best throughput (rate of messages sent per second) and are the most convenient for users (since they are short, they are easy to remember and type into a phone). Dedicated short codes support sending hundreds or thousands of messages at once, with high deliverability rates.

10DLC vs Toll-Free vs Short Code

### **Pros for using a dedicated short code** * Dedicated short codes have a much higher SMS throughput volume (starting as high as 350 messages per second or 21,000 messages per minute). So messages will go out faster than with 10-digit numbers. * Dedicated short codes are convenient for your audience because they are typically 5-6 digits. ### **Cons for using a dedicated short code** * Registration is required to use a short code in any capacity. * Dedicated short codes are the most costly SMS marketing option, with a one-time $2,500 provisioning fee and a $600/month leasing fee (premium and vanity codes may cost more). * Setup time is significantly longer than other options, as it can take anywhere from 3 weeks to 4 months to get final approval from the mobile carriers. ### Short code throughput and limits Short code numbers give you the highest throughput by far, at as much as **21,000 text messages per minute**. Unlike 10DLCs, short code numbers have no daily limits. ### Summary Dedicated short codes cost significantly more than other messaging options. We recommend them for businesses with a larger budget and high send volume. ## Short Code Type Options There are three types of dedicated short codes. You can lease one of these options or migrate an existing dedicated short code through Mobile Text Alerts.

Three types of short code options

### **Premium short code** Premium short codes allow spelling out a brand name or a significant word using a mobile phone’s dial pad. These codes create memorable customization, but may be pricier than other options. *Examples: 827438 for “Target” or 262966 for “Amazon.”* ### **Vanity short code** Vanity short codes are numbers that you can select from a list of available codes. With this option you can choose a code that is easy for your customers to remember. Depending on the options available, you may even be able to select a code that fits your brand without paying the full price of leasing a premium short code. ### **Random short code** Random short codes are short numbers that are randomly assigned. The benefit of choosing a random short code is that you receive all the same short code features for a lower cost than a premium or vanity short code. ## **Get a dedicated short code for sending messages** If you’d like to lease a dedicated short code for your business, you can [contact us](https://mobile-text-alerts.com/contact). ## View your Numbers and Short Codes with the API ### List the short codes on your account You can view all the short codes assigned to your account by calling the [Get shortcodes endpoint](https://developers.mobile-text-alerts.com/api-reference/shortcodes#get-shortcodes). #### Example request ```bash curl --location 'https://api.mobile-text-alerts.com/v3/shortcodes' \ --header 'Authorization: Bearer 89fa747a-e01b-5940-99c2-4e96fa996258' ``` #### Example response ```json { "data": { "shortcodes": ["99999", "11111"] } } ``` ## GET /shortcodes > List Short Codes ```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":{"ListShortcodes.Response":{"allOf":[{"$ref":"#/components/schemas/IApiResponse"},{"type":"object","properties":{"data":{"type":"object","properties":{"shortcodes":{}},"required":["shortcodes"]}},"required":["data"]}]},"IApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"},"data":{}},"required":[]}},"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":{"/shortcodes":{"get":{"tags":["Shortcodes"],"summary":"List Short Codes","operationId":"shortcodes_list_shortcodes","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/ListShortcodes.Response"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}} ``` ### List all numbers on your account 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) API endpoint. This returns the name, type, status, and more. #### Example request ```bash curl --location 'https://api.mobile-text-alerts.com/v3/dedicated-numbers' \ --header 'Authorization: Bearer 89fa747a-e01b-5940-99c2-4e96fa996258' ``` #### 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/short-code.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.