Vision 6

subscribeContact

Subscribes a single Contact to a List.

subscribeContact

Subscribes a single Contact to a List.

Top ↑

Syntax

int subscribeContact(
    string api_key,
    int list_id,
    object contact_details,
  [ string consent_type,
    string consent_text,
    object list_preferences,
    string ip_address ] 
);

API Key Access Level required: Standard access

Parameters

api_key (string)

The key required to access the API. See Getting Started for more information.

list_id (int)

The ID of the List to subscribe the Contact to.

contact_details (object)

An object of Contact details, indexed using each of the Field names or Field Ids in the List. See the examples below.

consent_type (string - optional)

A flag that provides the level of consent the contact has agreed to. Valid values are:

  • gdpr - The contact has accepted the required consent text and agrees that their personal details will be added to the list.
  • direct - The contact has been supplied with the intent of supplying their personal details.
  • not_recorded - The contact was not supplied with the implication of a Direct or GDPR agreement (default).

If the list is marked as GDPR compliant, consent_type is required to be gdpr, with a supplied consent_text.

consent_text (string - optional)

A summary of the text the contact accepted to when requesting to be added to the list. ie, "Our mail provider is Vision6 and by submitting this form I consent to receiving marketing content.". This information is recommended and required when the consent_type is gdpr. This text has a 255 character limit.

list_preferences (object - optional)

An object of preference name keys with boolean values to signify that the contact wishes to agree to or decline from certain preferences. Preferences not in this object are ignored.

ip_address (string - optional)

The contact's last known IP address.

Return Value

Returns the ID of the subscribed Contact on success.

Examples

The example shows how to use subscribeContact to subscribe a new Contact to a List.

PHP

$list_id = 1234567;     // can be obtained using searchLists()

$contact_details = array(
    'Email'           => 'bob@example.com',
    'Mobile Phone'    => '0404555555',
    'Name'            => 'Bob Jones'
    'field_78978'     => 'Engineer'
);

$consent_type = 'gdpr';
$consent_text = 'By submitting this form I consent to receiving marketing content.';

$list_preferences    = array(
    'Newsletters' => true,
    'Promotions'  => false,
);

$api = new Api($url, 'YOURAPIKEY');
$contact_id = $api->invokeMethod(
    'subscribeContact',
    $list_id,
    $contact_details,
    $consent_type,
    $consent_text,
    $list_preferences,
    '0.0.0.0'
);

JSON Request

{
    "id": 1,
    "method": "subscribeContact",
    "params": [
        "YOURAPIKEY",
        1234567,
        {
            "Email": "bob@example.com",
            "Mobile Phone": "0404555555",
            "Name": "Bob Jones",
            "field_78978": "Engineer"
        },
        "direct",
        "By submitting this form I consent to receiving marketing content.",
        {
            "Newsletters": true,
            "Promotions": false
        },
        "0.0.0.0"
    ]
}

JSON Response

{
    "id": 1,
    "result": 32,
    "error": null
}

Remarks

When a contact is successfully subscribed, the system will:

  • Trigger associated Subscribe Campaign Events or Autoresponders.
  • Send a notification message to each address in the on_register_address value for the List (see addList).

Use addContacts for adding multiple Contacts to a List.

The API does not check the mandatory value of List Fields when adding or editing Contacts.

Error Codes

This method may return the following error codes in addition to the standard error codes:

Code Error Description
303 Unable to Load List list_id is not a valid List
310 Invalid Method Parameters contact_details must be a single array of Contact details
330 Contact Limit Reached The Contact limit for the Account has been reached
317 Invalid Email Address Specified The supplied Email address is not valid
302 Undefined Error: Contact Subscription Failed An internal error occurred while the system was trying to subscribe the Contact
334 Invalid Contact consent type The consent_type was supplied with a value other than gdpr, direct or not_recorded
335 The GDPR Contact consent type and consent text are required for this list To resubscribe this contact the consent_type must be gdpr and a consent_text must be supplied

See Also