# 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="/files/-M\_1ZmsMDLd3ZhJH5tjc" %}
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;

![](/files/-M_1YwG3SQPp14x3eT3t)

## 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;


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.heypoplar.com/api/endpoints/audience.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.