Bulk Create/Update Subscribers
Learn how to use the bulk subscriber endpoints, useful for large scale subscriber updates.
When creating or updating many subscribers at one time with the Create Subscriber and Update Subscriber endpoints you can quickly exhaust the available rate limit. The Bulk Create Subscribers and Bulk Update Subscribers endpoints are recommended for handling large subscriber changes via the API, this can save on both request round trip time and overall API call volume.
Bulk Create Subscribers
This endpoint is used to create (or update and create) many subscriber accounts in one request.
CreateOnly Parameter
CreateOnly ParameterIf set to true the createOnly path parameter indicates the only action should be to create new subscribers and will not update records of existing subscribers. If set to false then both creating or updating (if the subscriber exists) actions will be performed.
Subscriber Request Body
Records of subscribers should be in an array.
Required Fields for new subscribers: email or number
firstName
string
First name of the subscriber.
lastName
string
Last name of the subscriber.
number(required if no email)
number
Phone number of the subscriber.
email (required if no number)
string
Email address of the subscriber.
e164Number
string
E.164 international telephone number of the subscriber. If supplied, will be used over number .
E.164 Format:
[+] [country code] [subscriber number including area code] (max. 15 digits)
groupIds
number[]
List of group ids of the groups the subscriber belongs to.
subscriberFields
dictionary: subscriberFieldIds:string as the keys and data: string corresponding values
A dictionary of key value pairs of additional custom subscriber attributes for the subscriber.
Example:
"subscriberFields": {
"2000": "January 1st, 2000",
"2001": "Custom Field Data"
}Record Limit
This endpoint will accept a maximum of 1,000 records in a single request. Records of subscribers should be in an array. The createOnly field indicates if the action is creating new subscribers only (doesn't accept records of existing subscribers) or the action is creating or updating (accept records of existing subscribers and update info according to the records).
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
POST /v3/subscribers/bulk HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 203
[
{
"firstName": "text",
"lastName": "text",
"email": "text",
"number": 1,
"e164Number": "text",
"groupIds": [
1
],
"subscriberFields": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"employeeNumber": "text",
"welcomeMessage": "text"
}
]{
"statusCode": "MTANoLinkedAccountError",
"success": true,
"error": "text",
"message": "text",
"data": {
"totalRecordCount": 1,
"createdRecordCount": 1,
"errorRecordCount": 1,
"createdRecords": [
{
"id": 1,
"firstName": "text",
"lastName": "text",
"email": "text",
"number": 1,
"e164Number": "text",
"date": "2025-06-26T20:52:17.223Z",
"countryId": 1,
"groups": [
{
"id": 1,
"name": "text",
"addedToGroupAt": "2025-06-26T20:52:17.223Z"
}
],
"subscriberFieldData": [
{
"id": 1,
"subscriberFieldId": 1,
"data": "text"
}
],
"signupMethod": 1,
"longNumber": 1
}
],
"errorRecords": [
{
"firstName": "text",
"lastName": "text",
"email": "text",
"number": 1,
"e164Number": "text",
"groupIds": [
1
],
"subscriberFields": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"employeeNumber": "text",
"welcomeMessage": "text",
"error": "text"
}
]
}
}Bulk Update Subscribers
This endpoint is used to update many subscriber accounts in one request. The number field is used to identify the subscriber record to be updated , if no number is provided then email will be used an identifier. One of these fields must be provided to identify the subscriber record to be updated.
Subscriber Request Body
Records of subscribers should be in an array.
firstName
string
First name of the subscriber.
lastName
string
Last name of the subscriber.
number
number
Phone number of the subscriber.
email
string
Email address of the subscriber.
e164Number
string
E.164 international telephone number of the subscriber. If supplied, will be used over number .
E.164 Format:
[+] [country code] [subscriber number including area code] (max. 15 digits)
groupIds
number[]
List of group ids of the groups the subscriber belongs to.
subscriberFields
dictionary: subscriberFieldIds:string as the keys and data: string corresponding values
A dictionary of key value pairs of additional custom subscriber attributes for the subscriber.
Example:
"subscriberFields": {
"2000": "January 1st, 2000",
"2001": "Custom Field Data"
}Record Limit
This endpoint will accept a maximum of 1,000 records in a single request.
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
BulkUpdateSubscribers.RequestRecord
BulkUpdateSubscribers.RequestRecord
BulkUpdateSubscribers.RequestWithId
BulkUpdateSubscribers.RequestWithPhoneNumber
BulkUpdateSubscribers.RequestWithEmail
PATCH /v3/subscribers/bulk HTTP/1.1
Host: api.mobile-text-alerts.com
Authorization: Bearer apiKey
Content-Type: application/json
Accept: */*
Content-Length: 221
[
{
"record": {
"firstName": "text",
"lastName": "text",
"email": "text",
"number": 1,
"e164Number": "text",
"groupIds": [
1
],
"subscriberFields": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"employeeNumber": "text",
"welcomeMessage": "text"
},
"id": 1
}
]{
"statusCode": "MTANoLinkedAccountError",
"success": true,
"error": "text",
"message": "text",
"data": {
"totalRecordCount": 1,
"updatedRecordCount": 1,
"errorRecordCount": 1,
"updatedRecords": [
{
"record": {
"id": 1,
"firstName": "text",
"lastName": "text",
"email": "text",
"number": 1,
"e164Number": "text",
"date": "2025-06-26T20:52:17.223Z",
"countryId": 1,
"groups": [
{
"id": 1,
"name": "text",
"addedToGroupAt": "2025-06-26T20:52:17.223Z"
}
],
"subscriberFieldData": [
{
"id": 1,
"subscriberFieldId": 1,
"data": "text"
}
],
"signupMethod": 1,
"longNumber": 1
},
"id": 1
}
],
"errorRecords": [
{
"error": "text",
"id": 1
}
]
}
}Last updated
Was this helpful?