Reference

Update a saved audience

PATCH /v1/audiences/{id}. Rename a saved audience or replace its definition.

Generated from the contractsView as Markdown

PATCH /v1/audiences/{id}

Rename a saved audience or replace its definition. The next count uses the new definition.

Property	Value
Endpoint	`PATCH https://mydatahub.emailmovers.com/v1/audiences/{id}`
Operation id	`updateAudience`
Cost	Free (0 credits)
Access	An API key or an OAuth 2.1 token with the scope `audiences:write`.
MCP tool	`save_audience`
Tag	Audiences

Request

Parameters

Name	In	Type	Required	Description
`id`	path	string	yes	Format: an audience id: aud_ followed by a 26 character ULID in upper case Crockford base32, such as aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA.
`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.

Body

Member	Type	Required	Description
`name`	string	no
`audience`	`Audience`	no	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.
`brief`	string or null	no

Example request

curl -X PATCH "https://mydatahub.emailmovers.com/v1/audiences/aud_01JB4H2K9V6XN3M9R6T1Y5W8ZA" \
  -H "Authorization: Bearer $MYDATAHUB_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "Marketing directors, Leeds"
}'

Responses

200: The updated audience.

Headers: RateLimit, RateLimit-Policy.

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.
`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

{
  "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.

Status	Problem codes	When
400	`invalid-request`, `idempotency-key-required`, `unsupported-version`	The request could not be read, or an Idempotency-Key is missing.
401	`authentication-required`, `account-required`	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`, `confirmation-required`, `business-details-required`, `licence-acceptance-required`, `dpa-acceptance-required`, `agent-budget-exceeded`	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.
404	`not-found`	No such object for this organisation.
422	`validation-failed`, `quote-required`, `dataset-unavailable`	The request is not valid. errors lists every problem with a JSON pointer and did_you_mean.
429	`rate-limited`	Too many requests. Wait for Retry-After.
Any other failure	`internal-error`, `service-unavailable`, `tps-screen-expired`	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.