# How can we help?

## Overview

Cordial provides a standard opt-out page for unsubscribing contacts via the [default opt-out link](https://support.cordial.com/hc/en-us/articles/115005855988). In some cases, however, you may want greater control over functionality and branding. You can achieve this by building and hosting your own custom preference center page while utilizing the [Cordial REST API](https://support.cordial.com/hc/en-us/sections/200533927-Contact-management-APIs) to update a contact's subscribe status and list memberships.

This article will provide examples of how to take advantage of Cordial's REST API for updating a contact record. Please view the article on [API summary and usage](https://support.cordial.com/hc/en-us/articles/203885498-RESTful-API-Summary-and-Usage) for more information on authentication, Cordial's API endpoint, supported methods and more.

## Example preferences form

The following is an example form used to update a contact's list membership and subscribe status:

## Retrieve the contact record

### Create the URL to your preference page

In order to populate the form with a contact's profile data you will need to retrieve the contact's record using the contact's ID (cID). The cID may be passed in the URL to your preferences form using a [system variable](https://support.cordial.com/hc/en-us/articles/115005855508-System-Variables) in the query string.

Example URL with cID appended as a query string:

```
https://example.com/preference_form.html?cID={$contact._id}
```

### Password protect your preference page

In order to maintain security, we strongly recommend protecting your preference form behind a password protected page, such as an account login. However, we recognize that many clients do not require or support authenticated access to their domains. In this case, clients should follow our recommended best practices below.

### Best practices: use a hash-based message authentication code (HMAC)

If you're unable to password protect your page, we recommend hashing the URL using a hashing algorithm and HMAC to authenticate.

Cordial supports a hash_hmac Smarty modifier you can use to generate an HMAC signed link:

```
{$hmac_secret = 'some long secret value'}
{$link = "https://example.com/preference_form.html?cID={$contact._id}"}
{$hmac = "{$link|hash_hmac:'sha256':$hmac_secret}"}

<a href="{$link}&hmac={$hmac}">{$link}&hmac={$hmac}</a>
```

- For more information on using HMAC for authentication please view the following page:

[https://en.wikipedia.org/wiki/HMAC](https://en.wikipedia.org/wiki/HMAC)

### Retrieve contact data using the API

Using the [GET <path>/contacts/cID:{cID}](https://support.cordial.com/hc/en-us/articles/203885958-Contacts#getContactsPrimaryKey) API call, you can retrieve data about the contact.

For example:

```
GET <path>/contacts/cID:5552fc99990c811781477777
```

Sample response from a GET <path>/contacts API call:

```
{
    "_id": "5552fc99990c811781477777",
    "channels": {
      "email": {
        "address": "john@example.com",
        "subscribeStatus": "subscribed"
      }
    },
    "attributes": {
        "firstName": "John",
        "lastName": "Smith",
        "lists": [
            "daily_promotions",
            "weekly_promotions",
            "monthly_newsletter"
        ]
    }
}
```

In the past, the `?isCid=true` URI parameter was used to specify the contact identifier type being passed. This query parameter is still supported, however, we recommend the `key:value` structure going forward, which is consistent with the Cordial REST resource naming convention.

## Update the contact record

Once you have contact data available, you can update the contact record using the PUT methods to the [contact collection](https://support.cordial.com/hc/en-us/articles/203885958-Contacts) with the contact's primary key (most likely email address).

Remember to use all the appropriate web security measures to assure that only authenticated users are allowed to submit a request to modify a contact. Ensure that the contents of the changes are valid, and that the form itself is protected against abuse.

## Update contact's email address

Using the [PUT <path>/contacts/{primary_key} or /{secondary_key}:{value}](https://support.cordial.com/hc/en-us/articles/203885958-Contacts#putContactsPrimaryKey) API call, you can update the contact's email address to a new value.

Example JSON request to update the contact's email address:

```
{
   "channels":{
      "email":{
         "address":"new_email@example.com"
      }
   }
}
```

## Update list membership

To update the list membership of the contact, use the [PUT <path>/contacts/{primary_key} or /{secondary_key}:{value}](https://support.cordial.com/hc/en-us/articles/203885958-Contacts#putContactsPrimaryKey) API call.

Example JSON request to update the list membership:

```
{
  "daily_promotions": false,
  "weekly_promotions": false,
  "monthly_newsletter": true,
}
```

## Update subscribe status

### Unsubscribe a contact

To unsubscribe a contact, use the [PUT <path>/contacts/{primary_key} or /{secondary_key}:{value}/unsubscribe/{channel}](https://support.cordial.com/hc/en-us/articles/203885958-Contacts#putContactsPrimaryKeyUnsub) API call.

Example request to unsubscribe the contact from the `email` channel:

```
PUT <path>/contacts/email:john@exampe.com/unsubscribe/email
```

### Attribute an unsubscribe

By adding the mcID ( [message contact ID](https://support.cordial.com/hc/en-us/articles/360016355691#mcID)) query parameter, you can attribute the unsubscribe to a specific message.

Example request to unsubscribe the contact from the `email` channel with attribution:

```
PUT /contacts/email:john@exampe.com/unsubscribe/email?mcID=252:5bb795c36fc360de221c03ae:ot:5bb647499dadbb3b3b14d855:1
```

Unsubscribing a contact using the above methods will change the subscribe status of a contact to "unsubscribed" and create a new opt-out event in the [contact activities collection](https://support.cordial.com/hc/en-us/articles/203885968-Contact-Activities-Events-).

Sample response of an opt-out event using GET <path>/contactactivities.

```
{
      "cID": "5552fc99990c811781477777",
      "mcID": "252:5bb795c36fc360de221c03ae:ot:5bb647499dadbb3b3b14d855:1",
      "first": true,
      "_id": "5bb796bf2cab4e1b1697573e",
      "action": "optout",
      "time": "2018-10-05T16:52:15+0000",
      "bmID": "252:5bb795c36fc360de221c03ae:ot",
      "email": "john@example.com",
      "system_properties": {
        "mTags": []
      }
    }
```

### Subscribe a contact

Using the [POST <path>/contacts](https://support.cordial.com/hc/en-us/articles/203885958-Contacts#postContacts) API call you can subscribe a contact.

Example JSON request to subscribe a contact to the `email` channel:

```
{
   "channels":{
      "email":{
         "address":"john@example.com",
         "subscribeStatus":"subscribed"
      }
   }
}
```

### Resubscribe a contact

Using the [POST<path>/contacts](https://support.cordial.com/hc/en-us/articles/203885958-Contacts#postContacts) API call you can re-subscribe a contact.

Example JSON request to re-subscribe the contact from the `email` channel:

```
{
  "channels": {
    "email": {
      "address": "john@example.com",
      "subscribeStatus": "subscribed",
      "invalid": false
    }
  },
  "forceSubscribe": true
}
```

In the request body above `forceSubscribe` is required to re-subscribe a contact if previously unsubscribed. The `"invalid" : false` parameter is required if a contact's email had been previously invalidated due to a hard bounce.

If a contact unsubscribes via the list-unsubscribe mechanism of an inbox provider (i.e. Gmail) and added to an MTA (message transport agent) suppression list, re-validating the contact using the `invalid` parameter will **not** update the MTA suppression.

- [Learn more about unsubscribe status](https://support.cordial.com/hc/en-us/articles/115002492212).