# Add a Subscriber 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 ](https://developers.mobile-text-alerts.com/tutorials/phone-number-format-guide#recommended-format-e.164). See [phone-number-format-guide](https://developers.mobile-text-alerts.com/tutorials/phone-number-format-guide "mention") to learn more. {% endhint %} ### Example request to add a subscriber Below you can see example `POST` requests to the [`/subscribers`](https://developers.mobile-text-alerts.com/api-reference/subscribers#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": "+18002223333", "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: '+18002223333', 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': '+18002223333', '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:* [#create-subscriber-api-endpoint](https://developers.mobile-text-alerts.com/tutorials/manage-subscribers#create-subscriber-api-endpoint "mention") #### 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":8002223333, "e164Number":"+18002223333", "date":{"val":"CURRENT_TIMESTAMP"}, "countryId":209, "groups":[], "subscriberFieldData":[], "signupMethod":5, "longNumber":8002223333, "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":{}},"required":[]},"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"]},"CreateSubscriberRequest":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"email":{"type":"string"},"number":{"type":"number"},"groupIds":{"type":"array","items":{"type":"number"}},"subscriberFields":{"type":"object","additionalProperties":{"type":"string"}},"employeeNumber":{"type":"string"},"welcomeMessage":{"type":"string"}},"required":["firstName","lastName","email","number","groupIds","subscriberFields","employeeNumber","welcomeMessage"],"description":"SubscriberRequest"}},"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\n\n_Required Fields: email or number_\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/CreateSubscriberRequest"}}},"required":true}}}}} ``` ### More Subscriber Actions * [All Subscribers API endpoints](https://developers.mobile-text-alerts.com/api-reference/subscribers) * [Assign Custom Subscriber Attributes](https://developers.mobile-text-alerts.com/tutorials/manage-subscribers/assign-custom-subscriber-attributes) * [Group Subscribers](https://developers.mobile-text-alerts.com/tutorials/manage-subscribers/group-subscribers) --- # 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/getting-started/add-a-subscriber.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.