# Save an audience

> POST /v1/audiences. Save a named audience definition, shared across the organisation.

Source: https://emailmovers.com/mydatahub/docs/reference/rest/create-audience

`POST /v1/audiences`

Save a named audience definition, shared across the organisation. Saving is free; it is counted at once and on every refresh.

| Property | Value |
| --- | --- |
| Endpoint | `POST https://mydatahub.emailmovers.com/v1/audiences` |
| Operation id | `createAudience` |
| Cost | Free (0 credits) |
| Access | An API key or an OAuth 2.1 token with the scope `audiences:write`. |
| Idempotency-Key | Optional. Makes a retry safe. |
| MCP tool | [`save_audience`](https://emailmovers.com/mydatahub/docs/reference/mcp/save_audience.md) |
| Tag | Audiences |

> **Not yet live.** MyDataHub v2 is built and tested locally and is not yet live. The v2 hosts open at launch, date to confirm. This page describes the contract the API is tested against.

## Request

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `MyDataHub-Version` | header | string | no | The dated API version, pinned per key when left out. Non-breaking changes ship as new dates; the path major changes only for breaking changes, with a 12 month deprecation window. |
| `Idempotency-Key` | header | string | no | Makes the request safe to retry: the same key returns the stored response. Keys are kept for the life of the organisation. |

### Body

| Member | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | string | yes |  |
| `audience` | `Audience` | yes | Who you want, as filters grouped by entity (company., site., contact., email., phone., signal.). The server fills its defaults (active companies, named emails, corporate subscribers, the current dataset_version) and returns the effective definition with every count. See [Audience](https://emailmovers.com/mydatahub/docs/audience.md). |
| `brief` | string | no |  |

## Example request

```bash
curl -X POST "https://mydatahub.emailmovers.com/v1/audiences" \
  -H "Authorization: Bearer $MYDATAHUB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "Marketing directors, Leeds",
  "audience": {
    "schema": "mydatahub.audience/1",
    "dataset": "uk_contacts",
    "dataset_version": "2026-W39",
    "where": {
      "all": [
        {
          "field": "contact.title",
          "op": "matches",
          "terms": ["marketing manager"],
          "mode": "contains",
          "expand": ["plural_singular", "department_synonyms", "ampersand_and", "abbreviations"]
        },
        {
          "field": "contact.job_level_rank",
          "op": "in",
          "values": [1, 2, 3, 4, 5, 6, 8, 9]
        },
        {
          "field": "company.sic_2007",
          "op": "in",
          "values": ["C"]
        },
        {
          "field": "company.employee_band",
          "op": "gte",
          "value": "50-99"
        },
        {
          "field": "site.location",
          "op": "within_radius",
          "centre": {
            "place": "Leeds"
          },
          "radius_miles": 20
        },
        {
          "not": {
            "field": "email.address_sha256",
            "op": "in_list",
            "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
          }
        }
      ]
    },
    "email_policy": {
      "min_deliverability_score": 70,
      "allow_catch_all": false
    },
    "dedupe": "none"
  }
}'
```

## Responses

### 201: The saved audience.

Headers: `RateLimit`, `RateLimit-Policy`, `Location`.

| Member | Type | Always present | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA. |
| `name` | string | yes |  |
| `audience` | `Audience` | yes | Who you want, as filters grouped by entity (company., site., contact., email., phone., signal.). The server fills its defaults (active companies, named emails, corporate subscribers, the current dataset_version) and returns the effective definition with every count. See [Audience](https://emailmovers.com/mydatahub/docs/audience.md). |
| `brief` | string or null | yes | The brief it was compiled from, if any. |
| `current_count` | `AudienceCountSummary` or null | yes |  |
| `current_count.count_id` | string | yes | Format: a count id: cnt_ followed by 20 base32 characters (A to Z and 2 to 7), such as cnt_7K2PQ4MAXN3R6TBY5WDZ. |
| `current_count.dataset_version` | string | yes | The immutable weekly build a count is bound to, such as 2026-W39. The last 52 stay queryable. |
| `current_count.contacts` | integer (0 or more) | yes |  |
| `current_count.companies` | integer (0 or more) | yes |  |
| `current_count.emailable` | integer (0 or more) | yes |  |
| `current_count.counted_at` | string (date-time) | yes |  |
| `last_refreshed_at` | string (date-time) or null | yes |  |
| `created_at` | string (date-time) | yes |  |
| `updated_at` | string (date-time) | yes |  |
| `created_by` | string | yes | Format: a user id: usr_ followed by a 26 character ULID in upper case Crockford base32, such as usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8. |
| `url` | string (uri) | yes | The audience in the app, mydatahub.emailmovers.com/audiences/{id}. |

#### Example response

```json
{
  "id": "aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA",
  "name": "Marketing directors, Leeds",
  "audience": {
    "schema": "mydatahub.audience/1",
    "dataset": "uk_contacts",
    "dataset_version": "2026-W39",
    "where": {
      "all": [
        {
          "field": "contact.title",
          "op": "matches",
          "terms": ["marketing manager"],
          "mode": "contains",
          "expand": ["plural_singular", "department_synonyms", "ampersand_and", "abbreviations"]
        },
        {
          "field": "contact.job_level_rank",
          "op": "in",
          "values": [1, 2, 3, 4, 5, 6, 8, 9]
        },
        {
          "field": "company.sic_2007",
          "op": "in",
          "values": ["C"]
        },
        {
          "field": "company.employee_band",
          "op": "gte",
          "value": "50-99"
        },
        {
          "field": "site.location",
          "op": "within_radius",
          "centre": {
            "place": "Leeds"
          },
          "radius_miles": 20
        },
        {
          "not": {
            "field": "email.address_sha256",
            "op": "in_list",
            "list_id": "sup_01JB4H7Q2V7XN3M9R6T1Y5W8ZA"
          }
        }
      ]
    },
    "email_policy": {
      "min_deliverability_score": 70,
      "allow_catch_all": false
    },
    "dedupe": "none"
  },
  "brief": "Marketing managers and above at manufacturers within 20 miles of Leeds",
  "current_count": {
    "count_id": "cnt_7K2PQ4MAXN3R6TBY5WDZ",
    "dataset_version": "2026-W39",
    "contacts": 12840,
    "companies": 3115,
    "emailable": 12310,
    "counted_at": "2026-09-26T10:14:00Z"
  },
  "last_refreshed_at": "2026-09-28T06:00:00Z",
  "created_at": "2026-09-26T10:20:00Z",
  "updated_at": "2026-09-26T10:20:00Z",
  "created_by": "usr_01JA0Q3V7XN3M9R6T1Y5W8ZAK8",
  "url": "https://mydatahub.emailmovers.com/audiences/aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA"
}
```

## Errors

Every error is a problem object with a `code` and a `next_step`. Every response carries the `RateLimit` and `RateLimit-Policy` headers; see [Rate limits](https://emailmovers.com/mydatahub/docs/rate-limits.md).

| Status | Problem codes | When |
| --- | --- | --- |
| 400 | [`invalid-request`](https://emailmovers.com/mydatahub/docs/errors/invalid-request.md), [`idempotency-key-required`](https://emailmovers.com/mydatahub/docs/errors/idempotency-key-required.md), [`unsupported-version`](https://emailmovers.com/mydatahub/docs/errors/unsupported-version.md) | The request could not be read, or an Idempotency-Key is missing. |
| 401 | [`authentication-required`](https://emailmovers.com/mydatahub/docs/errors/authentication-required.md), [`account-required`](https://emailmovers.com/mydatahub/docs/errors/account-required.md) | Sign in (OAuth) or send an API key (authentication-required), or create a free account for what the anonymous tier does not cover (account-required). |
| 403 | [`insufficient-scope`](https://emailmovers.com/mydatahub/docs/errors/insufficient-scope.md), [`confirmation-required`](https://emailmovers.com/mydatahub/docs/errors/confirmation-required.md), [`business-details-required`](https://emailmovers.com/mydatahub/docs/errors/business-details-required.md), [`licence-acceptance-required`](https://emailmovers.com/mydatahub/docs/errors/licence-acceptance-required.md), [`dpa-acceptance-required`](https://emailmovers.com/mydatahub/docs/errors/dpa-acceptance-required.md), [`agent-budget-exceeded`](https://emailmovers.com/mydatahub/docs/errors/agent-budget-exceeded.md) | The token lacks a scope (insufficient-scope, with required_scope and a WWW-Authenticate step-up challenge); no person confirmed the spend and no agent key covers it (confirmation-required, with an approval_url); an agent key's per-order cap or monthly budget does not cover it (agent-budget-exceeded); an account made by self-serve sign-up has not yet confirmed its business name and that it is a UK business, which its first order needs (business-details-required); the order needs the Data Licence and Sharing Agreement accepted at the version in force (licence-acceptance-required); or a suppression upload comes before the organisation has accepted the Article 28 data processing agreement in force (dpa-acceptance-required). Nothing is charged. |
| 409 | [`idempotency-key-reused`](https://emailmovers.com/mydatahub/docs/errors/idempotency-key-reused.md), [`quote-expired`](https://emailmovers.com/mydatahub/docs/errors/quote-expired.md), [`order-not-ready`](https://emailmovers.com/mydatahub/docs/errors/order-not-ready.md), [`order-not-cancellable`](https://emailmovers.com/mydatahub/docs/errors/order-not-cancellable.md) | An Idempotency-Key reused with different parameters, an expired machine quote, or an object in the wrong state. |
| 422 | [`validation-failed`](https://emailmovers.com/mydatahub/docs/errors/validation-failed.md), [`quote-required`](https://emailmovers.com/mydatahub/docs/errors/quote-required.md), [`dataset-unavailable`](https://emailmovers.com/mydatahub/docs/errors/dataset-unavailable.md) | The request is not valid. errors lists every problem with a JSON pointer and did_you_mean. |
| 429 | [`rate-limited`](https://emailmovers.com/mydatahub/docs/errors/rate-limited.md) | Too many requests. Wait for Retry-After. |
| Any other failure | [`internal-error`](https://emailmovers.com/mydatahub/docs/errors/internal-error.md), [`service-unavailable`](https://emailmovers.com/mydatahub/docs/errors/service-unavailable.md), [`tps-screen-expired`](https://emailmovers.com/mydatahub/docs/errors/tps-screen-expired.md) | Something failed on our side (500 internal-error) or the service is briefly unavailable (503 service-unavailable, with Retry-After). Nothing was charged; retry with the same Idempotency-Key. A count, sample, quote or order with telephone in play is also refused with 503 tps-screen-expired, with no Retry-After, while the dataset version's TPS and CTPS screen is more than 28 days old. |