# Audience

In addition to the **Do Not Mail** audience, you can create additional audiences for suppression or mailing. This is done by uploading a CSV in the [**Audiences**](https://app.heypoplar.com/audiences) section or by calling the API. 

{% hint style="info" %}
This endpoint is only able to **add members to an existing list** in your Poplar account. You must first create an Audience within the Poplar platform to generate an `audience_id`
{% endhint %}

## Create Audience Member

<mark style="color:green;">`POST`</mark> `https://api.heypoplar.com/v1/audience/:id`

Use this endpoint to programmatically add users to an audience. At least one of the following is **required:** `address`, `email`, `email_sha256` and `identifier`.

#### Path Parameters

| Name                                 | Type   | Description                                                                                                                                                         |
| ------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id<mark style="color:red;">\*</mark> | string | <p>This is the ID of the audience you are adding to. <br><br>You can obtain this from the audience page on the dashboard, or from the Fetch Audiences endpoint.</p> |

#### Headers

| Name                                            | Type   | Description                                                     |
| ----------------------------------------------- | ------ | --------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer *<mark style="color:blue;">ProductionAccessToken</mark>* |

#### Request Body

| Name          | Type   | Description                                                                                                               |
| ------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| address       | object | Postal Address object (see below).                                                                                        |
| identifier    | string | A unique identifier for this user. This may be a Customer ID, database ID or other field.                                 |
| email\_sha256 | string | A SHA256 hash of the users email address. Please ensure that the email address is lowercased prior to computing the hash. |
| email         | string | Email Address                                                                                                             |

#### Address Object

| Key                                            | Type   | Description                                                                                        |
| ---------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------- |
| address\_1<mark style="color:red;">\*</mark>   | string | First line of the street address (e.g., house number and street name).                             |
| address\_2                                     | string | Second line of the street address (e.g., apartment or suite number). Optional in all combinations. |
| city                                           | string | City name.                                                                                         |
| state                                          | string | State abbreviation (e.g., "CA" for California                                                      |
| postal\_code<mark style="color:red;">\*</mark> | string | ZIP Code.                                                                                          |
| name                                           | string | Name of the addressee.                                                                             |

{% tabs %}
{% tab title="201: Created Audience member added" %}

```javascript
{
    "id": "xxxxx-xxxxx-xxxxx-xxxxx",
    "address": {
        "name": "Jim Halpert",
        "company": null,
        "address_1": "13831 Calvert St",
        "address_2": "# 1A",
        "city": "Van Nuys",
        "state_name": "CA",
        "postal_code": "91401"
    }
}
```

{% endtab %}
{% endtabs %}

## Fetch Audiences

<mark style="color:blue;">`GET`</mark> `https://api.heypoplar.com/v1/audiences`

This endpoint returns a list of audiences attached to your organization.

#### Headers

| Name                                            | Type   | Description                                                     |
| ----------------------------------------------- | ------ | --------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Bearer *<mark style="color:blue;">ProductionAccessToken</mark>* |

{% tabs %}
{% tab title="200: OK Returns a list of your audiences" %}

```javascript
[
    {
        "id": "2965b4fc-30cc-4ec6-b90a-d460fd25f90d",
        "name": "Do Not Mail List",
        "description": "Do Not Mail List for Share Local Media",
        "member_count": 1337
    },
    {
        "id": "087d0603-5b97-4656-9a2b-f739d44fe11b",
        "name": "Existing Customers",
        "description": "Customers who have made a purchase.",
        "member_count": 25181
    },
]
```

{% endtab %}
{% endtabs %}

## Upload Audience CSV

If you are uploading a CSV of audience members, you can use this template:

{% file src="<https://content.gitbook.com/content/xfN4IIBsOUuqBd0ERnDW/blobs/N0UjyjeiMTgz8AhcqTi3/audience-template%20(5).csv>" %}
Audience File Template
{% endfile %}

## Manually Add a Single Audience Member

When you are viewing the audience, you can also add a single audience member:&#x20;

![](https://content.gitbook.com/content/xfN4IIBsOUuqBd0ERnDW/blobs/NRkb3r75JnvgfSDPjzIe/assets_-Lx8Cs4rllp2vxAnMopC_-LyBbLTFt0oDJJZGJsdB_-LyF-fXg2SjlXSblT5Ku_Screen%20Shot%202020-01-10%20at%2010.09.47%20AM.png)

## Common Questions

### Should I upload a CSV to Audiences or use the Audience API?&#x20;

* If you have a list (or batch) of addresses you want to load into Poplar, we recommend using the CSV upload.
* If you need to keep your Audience synced in real-time with your external marketing platform, we recommend setting up the API call.&#x20;