API Reference – Marketing API – Adding Contacts to Lists

Marketing API Method Documentation

©2009-2017 SocketLabs, Inc., Version 1.0, Last Edit: June 19, 2017

PUT /lists/{listId}/contacts/{contactId}

Synopsis:

Adds a contact to a list.

Recommended Usage:

This PUT method allows you to easily add contacts onto a contact list.

There are two forms of this method. The first allows you to specifiy an integer ID value of the contact to add in the URL. If both the contact and list exist the contact will be added to that list. Otherwise, a 404 Not Found will be returned indicating either the list or contact does not exist.

The second form is provided for convenience and accepts an email address, first name, and last name as parameters passed in via JSON in the message body (with the URL {contactID} value left off). If the contact does not yet exist, it will be created and added to the list. If the contact does already exist (matching on the provided email address only) the first and last name will be ignored and that existing contact will be added to the list. If the server has exceeded its max allowed number of contacts when trying to add a new contact, a 403 Forbidden response will be returned. If the provided email address is poorly formatted or missing, a 400 Bad Request response will be returned.

With either form of the method, if the contact is already on the list the response will simply indicate a successful call (with no error thrown).

Request Information

HTTP Method:

PUT

URL:

https://api.socketlabs.com/marketing/v1/lists/{listId}/contacts/{contactId}

Response Format Types:

JSON or XML

Request Parameters:

The contact’s id can be passed in the URL, or alternately the email address, first name and last name information can be passed as JSON in the message body. When passing in the email address, if the contact does not yet exist it will be created and added to the list.

Using integer ID:

id
The contact’s integer id. If the contact id does not exist for your server, will return a 404 Not Found result. Note that this is passed in the URL (see URL above).

Using email address:

emailAddress
The contact’s email address.
customFields
[optional] An array of name value pairs that contain custom field data.  If you set a value for a custom field that does not exist for your server the call will fail.  If the call omits any existing custom field values and the contact exists, the existing custom field values will stay unchanged.

Example Requests:

Using integer ID:

PUT /marketing/v1/lists/123/contacts/4567 HTTP/1.1
Host: api.socketlabs.com
Authorization: Basic XXXXXXXXXXXXXXXXXXXx==
Cache-Control: no-cache

Using email address:

PUT /marketing/v1/lists/{listId}/contacts HTTP/1.1
Host: api.socketlabs.com
Authorization: Basic XXXXXXXXXXXXXXXXXXXx==
Content-Type: application/json
Cache-Control: no-cache

{ 
    "emailAddress" : "[email protected]",
    "CustomFields":
    [
        {
          "Name":"Gender","Value":"Male"
        },
        {
          "Name":"FirstName","Value":"Joe"
        },
    ]
}

Response Parameters

serverId
Your server’s Id.
id
The contact’s unique integer Id.
listId
The contact list’s unique integer Id.

Response Examples

Example Response (JSON):

{
    "serverId": 6789,
    "contactId": 1234,
    "listId": 5678
}

Update Log

June 19, 2017

Customers Who Trust in SocketLabs

You’re in good company when working with SocketLabs. Here are some companies who have also trusted SocketLabs.

Why SocketLabs?

What Our Customers Are Saying!