# 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)