Customers

Marketing Preferences

A MarketingPreference represents a preferred form of communication between an organisation and its customers.

The MarketingPreference object

Attributes

  • iduuidrequired

    The ID of the marketing preference

  • textstringrequired

    The text of the marketing preference

  • organisation_idstringrequired

    The ID of the organisation this marketing preference is linked to

  • created_atdate-timerequired

    The date and time which the marketing preference was created

  • updated_atdate-timerequired

    The date and time which the marketing preference was last updated

{
  "id": "00000000-0000-0000-0000-000000000000",
  "text": "I want to receive emails about special offers",
  "organisation_id": "00000000-0000-0000-0000-000000000000",
  "created_at": "2026-01-15T09:30:00+00:00",
  "updated_at": "2026-01-15T09:30:00+00:00"
}
get/customers/marketing-preferences

List marketing preferences

listMarketingPreferences

This endpoint retrieves all the marketing preferences associated with an organisation.

Query parameters

  • organisation_idstringoptional

    Optional organisation filter. When provided, only marketing preferences belonging to the supplied organisation are returned; omit to list preferences across every organisation the caller has access to.

Responses

  • 200

    The marketing preferences were successfully retrieved

  • 401

    The user is unauthenticated

post/customers/marketing-preferences

Create a marketing preference

createMarketingPreference

This endpoint creates a new marketing preference for an organisation.

Request body

  • textstringrequired

    The text of the marketing preference

  • site_iduuidoptional

    Optional site that this marketing preference applies to. When set, only customers signing up at this site are offered the opt-in; leave blank to apply the preference across every site in the organisation.

  • organisation_iduuidrequired

    Identifier of the organisation that owns this marketing preference. Preferences are inherited by every site in the organisation unless site_id narrows the scope.

Responses

  • 201

    The marketing preference was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 422

    The request didn't pass validation

get/customers/marketing-preferences/{marketingPreferenceId}

Get a single marketing preference for an organisation

getMarketingPreference

This endpoint retrieves a single marketing preference belonging to an organisation.

Path parameters

Responses

  • 200

    The marketing preference was successfully retrieved

  • 401

    The user is unauthenticated

  • 404

    The resource couldn't be found

put/customers/marketing-preferences/{marketingPreferenceId}

Update a marketing preference for an organisation

updateMarketingPreference

This endpoint updates a marketing preference belonging to an organisation.

Path parameters

Request body

  • textstringrequired

    The text of the marketing preference

Responses

  • 200

    The marketing preference was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/customers/marketing-preferences/{marketingPreferenceId}

Delete a marketing preference for an organisation

deleteMarketingPreference

This endpoint deletes a marketing preference belonging to an organisation.

Path parameters

Responses

  • 204

    The marketing preference was successfully deleted

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

get/customers/sites/{siteId}/marketing-preferences

List the marketing preferences for a site

listSiteMarketingPreferences

This endpoint retrieves all the marketing preferences associated with a site.

Path parameters

Responses

  • 200

    The marketing preferences for the site were successfully retrieved

  • 401

    The user is unauthenticated

  • 404

    The resource couldn't be found

post/customers/sites/{siteId}/marketing-preferences

Enable a marketing preference for a site

createSiteMarketingPreference

This endpoint enables a marketing preference for a site.

Path parameters

Request body

  • Identifier of the organisation-level marketing preference to enable at this site. After enablement, customers signing up at the site are offered this opt-in checkbox alongside any preferences already enabled.

Responses

  • 201

    The marketing preference was successfully retrieved

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

  • 422

    The request didn't pass validation

delete/customers/sites/{siteId}/marketing-preferences/{marketingPreferenceId}

Disable a marketing preference for a site

deleteSiteMarketingPreference

This endpoint disables a marketing preference for a site.

Path parameters

Responses

  • 204

    The marketing preference was successfully disabled

  • 401

    The user is unauthenticated

  • 403

    The authenticated user does not have permission.

  • 404

    The resource couldn't be found

get/customers/show-marketing-preferences

List public marketing preferences for an organisation

listPublicMarketingPreferences

Returns the marketing preferences (e.g. "email me about offers") that an organisation has defined for public display on unauthenticated signup flows. The response is a stripped-down projection — only the preference ID and display text — so the payload is safe to expose on a public webpage.

Use this to populate the consent checkboxes on a guest-facing signup form before the customer has any login credentials. Once the customer registers, switch to listCustomerMarketingPreferences to read or update their personal opt-in state.

This endpoint is public — no authentication is required.

Query parameters

  • organisation_iduuidrequired

    The organisation whose public marketing preferences to return. Required — public callers must scope the lookup to a specific organisation.

Responses

  • 200

    The public marketing preferences were successfully retrieved.

  • 404

    The resource couldn't be found