JSON:API

Most Membership.io endpoints return JSON:API-style documents. Use this request header:

Content-Type: application/vnd.api+json
Accept: application/vnd.api+json

application/json is also accepted by the backend for compatibility, but application/vnd.api+json is the canonical media type.

Resource response

A single resource response has data.id, data.type, and data.attributes.

{
  "data": {
    "id": "0197...",
    "type": "hubs",
    "attributes": {
      "title": "Member Academy",
      "slug": "member-academy",
      "created_at": "2026-06-08T12:00:00Z"
    }
  }
}

List response

A list response returns data as an array. Paginated endpoints also include links and metadata.

{
  "data": [],
  "links": {
    "self": "/api/v1/teams/team_123/contacts?page[size]=20",
    "next": "/api/v1/teams/team_123/contacts?page[size]=20&page[after]=cursor"
  },
  "meta": {
    "has_more": true
  }
}

Write request

Many newer write endpoints use a JSON:API envelope:

{
  "data": {
    "type": "contacts",
    "attributes": {
      "email": "member@example.com",
      "first_name": "Sam"
    }
  }
}

Update request

A PATCH is a partial update: send only the attributes you want to change. An omitted attribute is left alone. An explicit null clears an attribute that can be empty, and is a 422 on one that can’t. You may send the resource’s id in data, as JSON:API recommends:

{
  "data": {
    "type": "hubs",
    "id": "0197...",
    "attributes": {
      "description": "Weekly calls and recordings"
    }
  }
}

data.id is optional. When you send it, it must be the id of the resource you’re updating, the same id the response returns. A different id is a 409 with code resource_id_mismatch and source.pointer /data/id, and nothing is written. That protects you from updating the wrong record when a client mixes up its ids. Leave id out rather than sending null: "id": null, or any id that isn’t a string, is a 422. Where a path accepts a slug, such as /hubs/{identifier} or /pages/{identifier}, compare against the canonical id, never the slug. Authentication and route-level checks run before this one. Some routes check your permission on the resource later, so a request that isn’t allowed and also names a different id can get the 409 instead of a 403 or 404; nothing is written either way. A request that names a resource that doesn’t exist may likewise get a 404 or the 409. This rule applies to hubs, pages, products, spaces, playlists, playlist items, playlist attachments, files, folders, attachments, report reasons, email templates, hub events, comments, /contact-auth/me and /portal/hubs/{hub_id}/me/profile (the id is your contact id), contact-attribute definitions and options, contacts, coupons, access rules and overrides, automations, page sections, hub price and product displays, product prices, segments, tags, discussions, moderation reports, transcription settings (the id is the team id), conversations, messages, achievements, drip campaigns and drip steps. On routes whose resource id isn’t in the URL, send the id the response gives you:

Route	`data.id`
`PATCH /api/v1/admin/teams/{team_id}/hubs/{hub_id}/members/{contact_id}/role`	`"{hub_id}:{contact_id}"`, exactly as returned
`PATCH .../hubs/{identifier}/policies`	`"{hub_id}:{policy_type}"`, exactly as returned, with `policy_type` from the body
`PATCH .../hubs/{identifier}/email-settings`, `.../policies/gate`	the hub’s id (not its slug)
`PATCH /api/v1/teams/{team_id}/hubs/{hub_id}/content/{node_id}`	the node’s id, even when the path uses a slug
`PATCH /api/v1/contact-auth/me/teams/{team_id}/profile`	your team-contact id
`PATCH /api/v1/conversations/{id}/audiences/me`	your audience id
`PATCH /api/v1/hubs/{hub_id}/spaces/{space_id}/mute`	your space-membership id; with no membership the answer is `404` either way
`PATCH .../hubs/{hub_id}/contact-attributes/{definition_id}`	the hub setting’s id; sending an id before the setting exists is a `409`
`PATCH /api/v1/teams/{team_id}/media/{media_id}/transcript`	the id of the transcript version you edited (the media’s current transcript). An edit made from an older version is a `409` and creates nothing; the response returns the new version’s id.

Some alpha endpoints still accept flat request bodies or return flat token bodies. Check the generated OpenAPI page for the exact endpoint before building a client.

Errors

Errors return an errors array. Each error has an HTTP status string, title, detail, optional code, and optional source pointer.

{
  "errors": [
    {
      "status": "422",
      "code": "validation_error",
      "title": "Validation Error",
      "detail": "Field required",
      "source": {
        "pointer": "/data/attributes/email"
      },
      "meta": {
        "request_id": "req_..."
      }
    }
  ]
}

Get started

Concepts

Resource response

List response

Write request

Update request

Errors

​Resource response

​List response

​Write request

​Update request

​Errors

Resource response

List response

Write request

Update request

Errors