> For the complete documentation index, see [llms.txt](https://developers.mobile-text-alerts.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.mobile-text-alerts.com/getting-started/add-a-subscriber.md). # Add a Subscriber Learn how to use the Mobile Text Alerts API to add a subscriber to your account The Mobile Text Alerts API allows you to view, add, edit, and remove subscribers from your account just like you can from the [platform dashboard page](https://platform.mobile-text-alerts.com/subscribers/manage). This page will guide you through adding a subscriber with the API. {% hint style="info" %} Already have a contact list? You can [import contacts in bulk](https://mobile-text-alerts.com/articles/importing-contacts#import-phone-numbers-android-iphone-google) via a spreadsheet or integration instead of adding them individually through the API. {% endhint %} ## Add a Subscriber with the Mobile Text Alerts API Subscribers can be added via the API with a `POST` request to the `/subscribers` endpoint. A phone number (`number`) or email address (`email`) is required. If you add a phone number or email of a subscriber that already exists on the account, this will update the existing subscriber with any changes. {% hint style="info" %} It is recommended to submit the `number` field as type `string` in E.164 format . See [Phone Number Format Guide](/tutorials/phone-number-format-guide.md) to learn more. {% endhint %} ### Example request to add a subscriber Below you can see example `POST` requests to the [`/subscribers`](/api-reference/subscribers.md#post-subscribers) endpoint to add a new subscriber: {% tabs %} {% tab title="cURL" %} ```bash curl --location --request POST 'https://api.mobile-text-alerts.com/v3/subscribers' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "firstName": "FirstName", "lastName": "LastName", "number": "+13175551111", "email": "example@mobile-text-alerts.com" }' ``` {% endtab %} {% tab title="Node.js" %} Requirements: Node.js `18+` (native `fetch`) and an `MTA_API_KEY` environment variable. ```js async function main() { const response = await fetch('https://api.mobile-text-alerts.com/v3/subscribers', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.MTA_API_KEY}`, 'Content-Type': 'application/json' }, body: JSON.stringify({ firstName: 'Sarah', lastName: 'Johnson', number: '+13175551111', email: 'sarah@example.com', groupIds: [123, 456], subscriberFields: { '2000': 'January 1st, 2000', '2001': 'Premium' } }) }); const data = await response.json(); console.log(data); } main().catch((err) => { console.error('Request failed:', err); process.exitCode = 1; }); ``` {% endtab %} {% tab title="Python" %} Requirements: `pip install requests` and an `MTA_API_KEY` environment variable. ```python import requests import os response = requests.post( 'https://api.mobile-text-alerts.com/v3/subscribers', headers={ 'Authorization': f'Bearer {os.getenv("MTA_API_KEY")}', 'Content-Type': 'application/json' }, json={ 'firstName': 'Sarah', 'lastName': 'Johnson', 'number': '+13175551111', 'email': 'sarah@example.com', 'groupIds': [123, 456], 'subscriberFields': { '2000': 'January 1st, 2000', '2001': 'Premium' } } ) print(response.json()) ``` {% endtab %} {% endtabs %} *To view all possible request parameters see:* [Manage Subscribers](/tutorials/manage-subscribers.md#create-subscriber-api-endpoint) #### Example Response If valid, a response will be returned with the message: `"Subscriber created successfully."` ```json //Example successful response { "message":"Subscriber created successfully.", "data": { "id":109021633, "firstName":"FirstName", "lastName":"LastName", "email":"example@mobile-text-alerts.com", "number":3175551111, "e164Number":"+13175551111", "date":{"val":"CURRENT_TIMESTAMP"}, "countryId":209, "groups":[], "subscriberFieldData":[], "signupMethod":5, "longNumber":3175551111, "carrierId":"41" } } ``` ## Create Subscriber > Add a new subscriber. If given a phone number or email that already exists tied to the same account, updates the existing subscriber with new information > \\ > > \ > \_Required Fields: email or number\_ > \ > \ > \ > \# Rate Limiting\ > \ > This endpoint overrides the general rate limit with an account rate limit. Requests are limited by the authenticated account instead of the IP address. This endpoint is limited to \`15\` requests every \`15\` seconds ```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":{"CreateSubscriber.Response":{"allOf":[{"$ref":"#/components/schemas/IApiResponse"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/IPublicNumber"}},"required":["data"]}]},"IApiResponse":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"string"},"message":{"type":"string"},"data":{}}},"IPublicNumber":{"type":"object","properties":{"id":{"type":"number"},"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"number":{"type":"number"},"e164Number":{"type":"string"},"date":{"oneOf":[{"format":"date-time","type":"string"},{"type":"string"}]},"countryId":{"type":"number"},"groups":{"type":"array","items":{"$ref":"#/components/schemas/IPublicGroupName"}},"subscriberFieldData":{"type":"array","items":{"$ref":"#/components/schemas/IPublicSubscriberFieldDatum"}},"signupMethod":{"type":"number","nullable":true},"longNumber":{"type":"number"},"carrierId":{"type":"number"}},"required":["id","firstName","lastName","email","number","date","countryId","groups","subscriberFieldData","signupMethod","longNumber","carrierId"]},"IPublicGroupName":{"type":"object","properties":{"id":{"type":"number"},"name":{"type":"string"},"addedToGroupAt":{"oneOf":[{"format":"date-time","type":"string"},{"type":"string"}]}},"required":["id","name"]},"IPublicSubscriberFieldDatum":{"type":"object","properties":{"id":{"type":"number"},"subscriberFieldId":{"type":"number"},"data":{"type":"string"}},"required":["id","subscriberFieldId","data"]},"CreateSubscriber.Request":{"$ref":"#/components/schemas/INewNumber"},"INewNumber":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"number":{"oneOf":[{"type":"number"},{"type":"string"}]},"e164Number":{"type":"string"},"groupIds":{"type":"array","items":{"type":"number"}},"subscriberFields":{"type":"object","additionalProperties":{"type":"string"}},"employeeNumber":{"type":"string"},"welcomeMessage":{"type":"string"}}}},"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":{}}}}}},"RateLimitError":{"description":"RateLimitError","content":{"application/json":{"schema":{"type":"object","properties":{"httpCode":{"type":"number","enum":[429]},"message":{"type":"string"},"timestamp":{"type":"string","format":"date-time"},"type":{"type":"string","enum":["rate_limit_error"]},"name":{"type":"string","enum":["MTARateLimitError"]},"requestId":{"type":"string","format":"uuid"}}}}}},"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":{"/subscribers":{"post":{"tags":["Subscribers"],"summary":"Create Subscriber","description":"Add a new subscriber. If given a phone number or email that already exists tied to the same account, updates the existing subscriber with new information\r\n\r\n_Required Fields: email or number_\r\n\n\n# Rate Limiting\n\nThis endpoint overrides the general rate limit with an account rate limit. Requests are limited by the authenticated account instead of the IP address. This endpoint is limited to `15` requests every `15` seconds","operationId":"subscribers_create_subscriber","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/CreateSubscriber.Response"}}}},"400":{"$ref":"#/components/responses/BadRequestError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"429":{"$ref":"#/components/responses/RateLimitError"},"500":{"$ref":"#/components/responses/InternalServerError"}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriber.Request"}}},"required":true}}}}} ``` ### More Subscriber Actions * [All Subscribers API endpoints](/api-reference/subscribers.md) * [Assign Custom Subscriber Attributes](/tutorials/manage-subscribers/assign-custom-subscriber-attributes.md) * [Group Subscribers](/tutorials/manage-subscribers/group-subscribers.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://developers.mobile-text-alerts.com/getting-started/add-a-subscriber.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.