---
title: "POST /AUDIENCE"
slug: "post-audience"
updated: 2025-09-16T19:46:58Z
published: 2025-09-16T19:46:58Z
canonical: "help.yahooinc.com/post-audience"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.yahooinc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# POST /AUDIENCE

Use this API to upload any and all types of user data. This is a “one stop shop” for uploading data. Use it to upload one or more segments, scores and/or a set of attributes, or a disjoint mixture of all of these in a single upload for a set of users.

DataX also provides use-case specific APIs to upload a single segment as a list of users, or a score (or any attribute defined in the taxonomy) as a simple key value pair for a set of users. We recommend that you use this API, if possible.

> [!NOTE]
> Note
> 
> A taxonomy request should be sent before the audience request. Also there should be a 30 minute delay between the taxonomy and audience request.

## JSON Representation

Data in this representation is organized as a set of segment qualifications and attribute values on a per-user basis. Each user record is treated as an independent data unit, i.e., each user may have a completely different set of segment & attribute data specified in the same upload. A single record in the payload must be represented as the following JSON object:

```json
{
        "urn":{string}, "seg":[{"id":{string},"ts":{number},"exp":{number}}],
        "att":[{"id":{string},"ts":{number},"exp":{number}, "val":{string}}]
}
```

ResourceType for this representation is “datax-audience”.

## JSON Key Descriptions

| **Property Name** | **Type** | **Description** |
| --- | --- | --- |
| urn | String | User identifier must conform to “urnType” specified in metadata. |
| seg (segment inclusions and exclusions) | Array | A list of taxonomy entities, of type SEGMENT, that this user should now be qualified in or removed from. Each value in this array is an object with the following keys: **Id** [*required*] - It must be the “id” of a taxonomy-entity with type = “SEGMENT”. Call GET /taxonomy to fetch your active taxonomy. All new uploads are validated against the taxonomy version active at the time of processing. **Ts** [*optional*] - Timestamp associated with this qualification. It must be a UNIX epoch value expressed in seconds, e.g., 1376244670 for “Sun Aug 11 18:11:10 2013”. Its value must represent a time in the past. **Exp**: [*optional*] - It represents expiry associated with this qualification. must be a UNIX epoch value expressed in seconds, e.g., 1379234569 for “Sun Sep 15 08:42:49 2013”. Its value must represent a time in the future (upto 90 days), or 0 to expire immediately. For example, use value 0 to delete users from a segment or raw attributes associated with them. |
| att (attributes) | Array | One or more sets of attribute id and value pairs for this user. Each value in this array is an object with the following keys: **Id** [*required*] - Same as “[seg.id](http://seg.id)” above, except type of the taxonomy entity must be ATTRIBUTE. **Ts** [*optional*] - Same as “seg.ts” above. **Exp** [*optional*] - Same as “seg.exp” above. |

## Representation Example 1 – Upload segment inclusions, exclusions and attributes

Individual rows of an upload may represent the following JSON objects. Every row represents a single user record. Two different user records should be formatted in two different rows (separated by a new line). Qualifications/attributes specified for one user can be completely different from those specified for a different user within the same upload. (Please note: each row must be formatted as a single line of input.)

**Row 1:**

```json
{
        "urn" : "99ff2333f3fe7659c38b3674bc927f32",
        "seg" : [{"id":"OH224"},{"id":"AB288"},{"id":"OH228"}],
        "att" : [{"id":"R2345","val":"Modern"},{"id":"R2453","val":32}]
}
```

**Row 2:**

```json
{
        "urn" : "043f2e01b8f170ae7ae60bee17df199c",
        "seg" : [{"id":"AB288"},{"id":"TX333"}],
        "att" : [{"id":"YaRetail-Zipcode","val":"94089"}]
}
```

## Representation Example 2 – Upload user qualifications for segment OH224

A three row sample for a segment with taxonomy Id “OH224”:

```plaintext
{"urn" : "99ff2333f3fe7659c38b3674bc927f32","seg" : [{"id":"OH224"}]}
{"urn" : " 07feb252623ad6302bd64ff0885339d3","seg" : [{"id":"OH224"}]}
{"urn" : " f10d53af308a12eb4d9bbd07a68067e6","seg" : [{"id":"OH224"}]}
```

## Representation Example 3 – Upload a score file

A three row sample for an attribute with taxonomy Id “YaScore”:

```plaintext
{"urn":"07feb252623ad6302bd64ff039d3","att":[{"id":"YaScore","val":28}]}
{"urn":"99ff2333f3fe7659c38b36747f32","att":[{"id":"YaScore","val":99}]}
{"urn":"f10ad53af308a12eb4d9bbd067e6","att":[{"id":"YaScore","val":2}]}
```

### POST Call Example

### Request

```plaintext
POST /v1/audience HTTP/1.1
Host: datax.yahooapis.com
Content-Type: multipart/form-data;boundary=xyz

--xyz
Content-Type: application/json;charset=UTF-8 Content-Disposition: form-data; name="metadata"
{
        "description" : "user qualifications – daily bucket 05/19/2013",
        "extensions" : { "urnType" : "IXID" }
}
--xyz
Content-Type: application/octet-stream;charset=UTF-8
Content-Disposition: form-data; name="data"; filename="example.txt.bz2"

< bz2 compressed data >
--xyz--
```

### Successful Response

```plaintext
HTTP/1.1 202 Accepted
Content-Type: application/json;charset=UTF-8 Date: Sun, 19 May 2013 12:29:09 GMT

{
        "resourceType" : "datax-audience",
        "resourceId" : "130815T013759Z662589033",
        "description" : "user qualifications – daily bucket 05/19/2013",
        "createTime" : "2013-19-05T12:19:17Z",
        "links" : [
                {
                        "rel"   : "self",
                        "href" : "https://datax.yahooapis.com/v1/link/s/mJF90HlzC0618PRm-"
                },
                {
                        "rel"   : "describes",
                        "href" : "https://datax.yahooapis.com/v1/link/5qMQo4h4c2zi-"
                }
        ],
        "status" : {
                "state" : "PROCESSING",
                "lastUpdateTime" : "2013-19-05T12:22:17Z "
        },
        "extensions" : { "urnType" : "IXID",
        "view" : "INCREMENTAL",
                "links" : [
                        {
                                "rel"   : "https://datax.yahooapis.com/rels/taxonomy",
                                "href" : "https://datax.yahooapis.com/v1/link/O3stRliZAT.G.oqiu-"
                        },
                        {
                                "rel"   : "https://datax.yahooapis.com/rels/stats",
                                "href" : "https://datax.yahooapis.com/v1/link/VJbGt6S0hiqECL_-"
                        }
                ]
        }
}
```