API: Rest Create Contact and List Subscription
The Create Contact and List Subscription command allows you to add a new Contact and Subscription to a List. Subscription creation does not result in a tracking event. It also does not allow you to overwrite opt outs using a Force Subscribe option.
POST /lists
https://[siteurl]/rest/lists/[listId]?querystring
The following queries are supported:
format=[1,2,99], where 1=plain text, 2=html, and 99=MIME
duplicates=[0,1], where 0=Do not create duplicate Contact, default; 1=Create duplicate
Request Body Parameters
The Create Contact and List Subscription command requires the URI call with the List ID. Optional Filters include Format and Duplicates parameters.
The query strings 'format' and 'duplicates' are case sensitive and must be defined as in the example above. If the query string is incorrect or missing, it is ignored and the command creates a Plain Text subscription without duplication.
The command also requires the following in the Posted JSON:
Contact ID: "subscriberId": [subscriberId], an integer > 0; If 0, create new contact
Email: "email": [email]
First Name: "firstName": [firstName]
To create a Contact in a Customer Key enabled Realm, you must also include the Customer Key in the JSON:
Customer Key: "customerKey": [customerKey]
Request Body Example
Using Create a new Contact and Subscription with all arguments, line breaks in JSON for readability:
curl --request POST \
--url 'https://mail.mydomain.com/rest/lists/13?format=99&duplicates=1' \
--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \
--header 'content-type: application/json' \
--header 'accept: application/vnd.whatcounts-v1+json' \
--data '{
"subscriberId": 0,
"email": "jon.doe@mydomain.com",
"firstName": "Jon"
}' \
--include
Using Create a new Subscription for existing Contact with all arguments, line breaks in JSON for readability:
curl --request POST \
--url 'https://mail.mydomain.com/rest/lists/13?format=99&duplicates=0' \
--header 'authorization: Basic bXlBY2NvdW50Onh5enB3ZDEyMw==' \
--header 'content-type: application/json' \
--header 'accept: application/vnd.whatcounts-v1+json' \
--data '{
"subscriberId": 716094,
"email": "jon.doe@mydomain.com",
"firstName": "Jon"
}' \
--include
Response Body
The response returns a combination of Contact and List data. Based on the first 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/lists>;
Date: Fri, 17 Mar 2018 12:54:44 GMT
{
"subscriptionId": 120002
"subscriberId": 7160984
"listId": 13
"formatId": 99
"sentFlag": 0
"createdDate": "Jun 17, 2016 1:12:54 PM"
"formatType": "MIME"
"forceSubscribe": false
"skip": 0
"max": 0
}
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 }
Feature added in v12.17.0