> ## Documentation Index > Fetch the complete documentation index at: https://moengage.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Subscription Preferences (V5) > Fetches a user profile's per-category subscription state and global unsubscribe status. The user is identified by a `user_identifier_type` / `user_identifier_value` pair rather than a path parameter. #### Rate Limit The rate limit is 100 RPM and 360k per day. ## OpenAPI ````yaml /api/subscription-categories/subscription-categories-v5/subscription-categories-v5.yaml get /v5/subscription-preferences openapi: 3.0.3 info: title: MoEngage Subscription Preferences API description: > Server-to-server API for reading and managing a user's Subscription Category preferences directly, without depending on MoEngage-hosted landing-page flows. This API provides endpoints for: * **List Subscription Categories**: Fetches the active subscription-category catalog for the workspace. * **Get Subscription Preferences**: Fetches a user's per-category subscription state and global unsubscribe status. * **Update Subscription Preferences**: Updates a user's per-category subscription state and/or global unsubscribe status. Users are identified by a `user_identifier_type` / `user_identifier_value` pair (`moe_user_id`, `uid`, or `email`), rather than a path parameter. **Transitional authentication note:** This route currently accepts HTTP Basic Auth only. Bearer token support is planned but not yet active on this path; Bearer requests return `401` until the APISIX gateway fronts this route. version: '2.0' servers: - url: https://api-{dc}.moengage.com description: MoEngage API Server variables: dc: default: '01' description: >- The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number and replace the value of ‘dc’ in the URL by referring to the DC and API endpoint mapping [here](/api/introduction#data-centers). Your MoEngage Data Center (DC) can be 01, 02, 03, 04, 05, 06, or 101. security: - basicAuth: [] tags: - name: Subscription Categories description: Fetch the active subscription-category catalog. - name: Subscription Preferences description: >- Fetch and update a user's per-category subscription state and global unsubscribe status. paths: /v5/subscription-preferences: get: tags: - Subscription Preferences summary: Get Subscription Preferences (V5) description: > Fetches a user profile's per-category subscription state and global unsubscribe status. The user is identified by a `user_identifier_type` / `user_identifier_value` pair rather than a path parameter. operationId: getSubscriptionPreferences parameters: - name: Accept in: header required: false schema: type: string example: application/json - name: MOE-APPKEY in: header required: true description: > This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at Settings > Account > APIs > Workspace ID (earlier app id). schema: type: string - name: MOE-PROJECT-CODE in: header required: false description: > This is the project ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at Settings > Account > Portfolio > Project ID. Note: This parameter is mandatory for workspaces with the [Portfolio](/user-guide/settings/account/portfolio/portfolio) feature enabled. schema: type: string - name: X-MOE-Request-Id in: header required: false description: > Client-supplied trace ID for tracing. Correlates with `response_id`. Supply this header or `request_id` in the body; if both are set, they must match. schema: type: string - name: user_identifier_type in: query required: true description: The type of identifier supplied in `user_identifier_value`. schema: type: string enum: - moe_user_id - uid - email - name: user_identifier_value in: query required: true description: > The identifier value. For `moe_user_id`, accepts either the `usr_`-prefixed ID or the bare 24-character hex ID. schema: type: string - name: channel in: query required: false description: >- Optional. Restricts the returned category preferences to a single channel. Only the `email` channel is supported at present. schema: type: string enum: - email responses: '200': description: >- This response is returned when the request is processed successfully. content: application/json: schema: type: object properties: response_id: type: string description: Unique identifier for this API response. example: resp_1b2c3d4e5f60708192a3b4c5d6e7f809 type: type: string description: The resource type returned in `data`. example: subscription_preference data: $ref: '#/components/schemas/SubscriptionPreference' example: response_id: resp_1b2c3d4e5f60708192a3b4c5d6e7f809 type: subscription_preference data: user_id: usr_64f0a1b2c3d4e5f600112233 is_globally_unsubscribed: false categories: - name: promotional display_name: Promotional channel: email group: Marketing status: subscribed - name: product_update display_name: Product Update channel: email group: Updates status: unsubscribed '400': description: This response is returned when the identifier is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: missingValue: summary: Missing Identifier Value value: error: code: BAD_ARGUMENT message: user_identifier_value is required target: user_identifier_value unsupportedType: summary: Unsupported Identifier Type value: error: code: BAD_ARGUMENT message: >- user_identifier_type must be one of: moe_user_id, uid, email target: user_identifier_type '401': description: >- This response is returned when authentication is missing or invalid, or when a required workspace header is missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: auth_required: summary: Invalid or Missing Credentials value: error: code: UNAUTHORIZED message: Invalid or missing credentials target: Authorization missing_project_code: summary: Missing MOE-PROJECT-CODE Header value: error: code: UNAUTHORIZED message: MOE-PROJECT-CODE header missing target: MOE-PROJECT-CODE '403': description: >- This response is returned when the credentials lack the required scope. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: FORBIDDEN message: Token is missing required scope read:subscriptions target: Authorization '404': description: >- This response is returned when the identifier resolves to no user profile. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: NOT_FOUND message: No user found for the given identifier target: user_identifier_value '409': description: >- This response is returned when an email identifier matches multiple user profiles and email-based unsubscribe is disabled for the workspace. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: CONFLICT message: >- Multiple user profiles match this email; cannot resolve unambiguously target: user_identifier_value '429': description: This response is returned when the rate limit has been exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: TOO_MANY_REQUESTS message: Rate limit exceeded target: null '500': description: >- This response is returned when the system runs into an unexpected error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: code: INTERNAL_SERVER_ERROR message: Something went wrong, please retry target: null components: schemas: SubscriptionPreference: type: object description: A user's subscription preferences. properties: user_id: type: string description: The `usr_`-prefixed MoEngage ID of the resolved user profile. example: usr_64f0a1b2c3d4e5f600112233 is_globally_unsubscribed: type: boolean description: >- Whether the user is globally unsubscribed, irrespective of individual category state. example: false categories: type: array description: >- The user's subscription state for each category in the active catalog. items: $ref: '#/components/schemas/SubscriptionCategoryPreference' ErrorResponse: type: object properties: error: type: object properties: code: type: string description: A machine-readable error code. example: BAD_ARGUMENT message: type: string description: A human-readable error message. example: user_identifier_type is not supported target: type: string nullable: true description: The field or header the error relates to, if any. example: user_identifier_type SubscriptionCategoryPreference: type: object description: A single category's subscription state for a user. properties: name: type: string description: The unique category name. example: promotional display_name: type: string description: The human-readable category name. example: Promotional channel: type: string enum: - email description: >- The channel the category applies to. Only the `email` channel is supported at present. example: email group: type: string description: The group this category belongs to. example: Marketing status: type: string enum: - subscribed - unsubscribed description: The user's subscription state for this category. example: subscribed securitySchemes: basicAuth: type: http scheme: basic description: > Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format 'username:password'. - **Username**: Your MoEngage app key. - **Password**: Your MoEngage API secret. **Transitional note:** This route currently accepts Basic Auth only. Bearer token support (`Authorization: Bearer `) is planned but not yet active here — Bearer requests return `401` until the APISIX gateway fronts this route. For more information on authentication and getting your credentials, refer [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials). ````