API: Rest Create Subscription
The Create Subscription command allows you to add a new Subscription to a List for a specific Contact. See REST API Subscriptions Overview for a table of Subscription data available to POST. Subscription creation does not result in a tracking event.
To create a new Subscriber and a Subscription to a list at the same time, use Create Subscriber and List Subscription.
POST /subscriptions
https://[siteurl]/rest/subscriptions
Request Body Parameters
The Create Subscription command requires the following in the Posted JSON:
Subscriber ID: "subscriberId": [subscriberId], an integer > 0
List ID: "listId": [listId], an integer > 0
Format: "formatId": [1,2,99], where 1=plain text, 2=html, and 99=MIME
Force Subscribe: "forceSubscribe": [0,1], where 0=false, do not clear opt out, 1=true, clear opt out and force subscribe. Force Subscribe is only used when a Subscriber has requested the opt out to be cleared and their address to be added back to a List.
All other POST-able fields are optional, and can be found in the Data Fields table in REST API Subscriptions Overview.
Request Body Example
Using Create Contact with all arguments, line breaks in JSON for readability:
curl --request POST \
--url 'https://mail.mydomain.com/rest/subscriptions' \
--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \
--header 'content-type: application/json' \
--header 'accept: application/vnd.whatcounts-v1+json' \
--data '{
"subscriberId": 7160984,
"listId": 5,
"forceSubscribe": 0,
"formatId": 99
}' \
--include
Response Body
The response returns all available Subscription data. Based on the example above, the response returns:
HTTP/1.1 200 OK
Server: serverName
Content-Type: application/json
Content-Length: 926
Link: <https://mail.mydomain.com/rest/subscribers>;
Date: Fri, 17 Jun 2016 12:54:44 GMT
{
"subscriptionId": 120002
"subscriberId": 7160984
"listId": 5
"forceSubscribe": 0
"formatId": 99
"createdDate": "Jun 17, 2016 1:12:54 PM"
}
Error Response
Error Response Codes include both Client Errors (4xx) and Server Errors (5xx). Descriptions of each can be found in Response Codes.
For example, if a Subscription already exists for the Contact, the error would appear as:
{ "error": "Cannot insert duplicate subscription" "status": "Internal Server Error" "statusCode": 500 }