---
updatedAt: 2026-05-27T12:49:39.000Z
agentTools:
  projectIndex: https://developer.onetrust.com/onetrust/llms.txt
---

# Get List of Purposes

> ❗️ End of Support Notification
>
>  This API is now deprecated. Any customers leveraging this API are encouraged to use the [Get List of Purpose Versions API](https://developer.onetrust.com/onetrust/reference/getgroupedpurposesv2). For more information, see [OneTrust API Sunsetting & Deprecation Guidelines](https://developer.onetrust.com/onetrust/reference/onetrust-api-sunsetting-deprecation-guidelines).

Use this API to retrieve a paged list of purposes.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "Consent & Preferences - Universal Consent & Preference Management (OAS)",
    "version": "1.0",
    "contact": {
      "name": "OneTrust Support",
      "url": "https://my.onetrust.com/s/contactsupport"
    },
    "license": {
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0"
    },
    "description": "The Universal Consent & Preference Management APIs are used to integrate external systems and streamline the flow of data with Universal Consent & Preference Management in the OneTrust Platform."
  },
  "servers": [
    {
      "url": "https://{hostname}",
      "variables": {
        "hostname": {
          "default": "hostname",
          "description": "The OneTrust hostname such as app.onetrust.com, app-eu.onetrust.com, app-de.onetrust.com, app-uk.onetrust.com, app-apac.onetrust.com, trial.onetrust.com, or uat.onetrust.com."
        }
      }
    }
  ],
  "tags": [
    {
      "name": "Purposes",
      "description": "The Purposes APIs are used to manage the reasons for which data is collected.",
      "externalDocs": {
        "description": "OpenAPI 3.1.0 - Download Definition",
        "url": "https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json"
      },
      "x-displayName": "Purposes"
    }
  ],
  "paths": {
    "/api/consentmanager/v1/purposes": {
      "get": {
        "operationId": "getPurposesUsingGET",
        "summary": "Get List of Purposes",
        "description": "> ❗️ End of Support Notification\n>\n>  This API is now deprecated. Any customers leveraging this API are encouraged to use the [Get List of Purpose Versions API](https://developer.onetrust.com/onetrust/reference/getgroupedpurposesv2). For more information, see [OneTrust API Sunsetting & Deprecation Guidelines](https://developer.onetrust.com/onetrust/reference/onetrust-api-sunsetting-deprecation-guidelines).\n\nUse this API to retrieve a paged list of purposes.",
        "tags": [
          "Purposes"
        ],
        "x-onetrust": {
          "spec-label": "https://developer.onetrust.com/onetrust/openapi/consent-preferences-universal-consent-preference-management-oas.json"
        },
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "description": "Results page you want to retrieve (0-based).",
            "schema": {
              "type": "integer",
              "example": 0,
              "default": 0,
              "minimum": 0
            }
          },
          {
            "name": "size",
            "in": "query",
            "description": "Number of records per page.",
            "schema": {
              "type": "integer",
              "example": 20,
              "default": 20,
              "maximum": 100,
              "minimum": 1
            }
          },
          {
            "name": "sort",
            "in": "query",
            "description": "Sorting criteria in the format: property,(asc|desc). Default sort order is ascending. Multiple sort criteria are supported.",
            "schema": {
              "type": "string",
              "example": "name,asc",
              "default": "name,asc",
              "enum": [
                "id,asc",
                "id,desc",
                "name,asc",
                "name,desc",
                "purposeStatus,asc",
                "purposeStatus,desc",
                "purposeType,asc",
                "purposeType,desc",
                "version,asc",
                "version,desc",
                "createdDate,asc",
                "createdDate,desc",
                "lastModifiedDate,asc",
                "lastModifiedDate,desc",
                "publishedDate,asc",
                "publishedDate,desc"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK - Successfully retrieved purposes",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_PagePurposeDetailsDto"
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "*/*": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "*/*": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests. \nFor more information, see [API Rate Limits](https://developer.onetrust.com/onetrust/reference/rate-limits-overview).",
            "headers": {
              "Retry-After": {
                "schema": {
                  "description": "The number of seconds after which requests will be allowed again.",
                  "format": "int32"
                }
              },
              "ot-period": {
                "schema": {
                  "description": "The unit of time for which the rate limit applies",
                  "enum": [
                    "HOUR",
                    "MINUTE"
                  ]
                }
              },
              "ot-ratelimit-event-id": {
                "schema": {
                  "description": "The unique identifier for the rate-limiting event.",
                  "format": "uuid"
                }
              },
              "ot-request-made": {
                "schema": {
                  "description": "The number of requests made within the specified period.",
                  "format": "int32"
                }
              },
              "ot-requests-allowed": {
                "schema": {
                  "description": "The number of requests allowed within the specified period.",
                  "format": "int32"
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error"
          }
        },
        "deprecated": true,
        "security": [
          {
            "ConsentPreferences-UniversalConsentPreferenceManag_OAUTH2": [
              "CONSENT",
              "CONSENT_READ"
            ]
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "ConsentPreferences-UniversalConsentPreferenceManag_AssociatedAttributeValueInformation": {
        "properties": {
          "id": {
            "description": "Unique identifier for the attribute option",
            "type": "string",
            "format": "uuid",
            "example": "a34ccec7-1ec0-4d65-9075-bdd0d923f1d1"
          },
          "value": {
            "description": "Attribute value",
            "type": "string",
            "example": "Text Value"
          },
          "valueKey": {
            "description": "Translation key used for localizing the value",
            "type": "string",
            "example": "attribute.option.valueKey"
          },
          "colorCode": {
            "description": "Color code associated with the option. Used for score-based attributes.",
            "type": "string",
            "example": "red"
          }
        },
        "required": [
          "value"
        ]
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_AttributeValueInformation": {
        "properties": {
          "id": {
            "description": "Unique identifier for the attribute option",
            "type": "string",
            "format": "uuid",
            "example": "a34ccec7-1ec0-4d65-9075-bdd0d923f1d1"
          },
          "value": {
            "description": "Attribute value",
            "type": "string",
            "example": "Text Value"
          },
          "valueKey": {
            "description": "Translation key used for localizing the value",
            "type": "string",
            "example": "attribute.option.valueKey"
          },
          "colorCode": {
            "description": "Color code associated with the option. Used for score-based attributes.",
            "type": "string",
            "example": "red"
          },
          "optionSelectionValue": {
            "description": "Selection score value linked to the option. Used for score-based or numerical-based attributes.",
            "type": "string",
            "example": "\"3.5\""
          },
          "displayLabel": {
            "description": "Display name for the option, used for external attributes managed by other systems",
            "type": "string",
            "example": "United State | San Francisco"
          },
          "associatedAttributeValueInformation": {
            "description": "Associated attribute option information",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_AssociatedAttributeValueInformation"
            }
          },
          "disabled": {
            "description": "Indicates whether this attribute option is currently disabled.",
            "type": "boolean",
            "example": false,
            "default": false
          }
        },
        "example": "a2229953-b4b5-4042-8cb9-b78038cc4c46",
        "required": [
          "value"
        ]
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_PurposeLanguageDto": {
        "properties": {
          "Name": {
            "description": "The Purpose name",
            "type": "string",
            "example": "Marketing Communications"
          },
          "Description": {
            "description": "The Purpose description",
            "type": "string",
            "example": "Collect customer emails for marketing purposes"
          },
          "Description of Implicit Purpose Confirmation checkbox": {
            "description": "The Implicit Purpose Confirmation checkbox description",
            "type": "string",
            "example": "I can confirm"
          },
          "Language": {
            "description": "The Purpose content language code",
            "type": "string",
            "example": "en-us"
          },
          "Default": {
            "description": "Whether this language is the default one for the Purpose",
            "type": "boolean",
            "example": true
          },
          "HardOptOutMessage": {
            "description": "The message to display with the purpose when the consent status is Hard opt-out. This message only displays when hardOptOutDisplayFormat is set to LOCK.",
            "type": "string",
            "example": "This purpose is required and cannot be opted out"
          }
        },
        "required": [
          "Description",
          "Name"
        ]
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceOptionDto": {
        "properties": {
          "Id": {
            "description": "Unique Identifier identifying an Option",
            "type": "string",
            "format": "uuid",
            "example": "ca0fc41b-b28a-4335-804c-44d1f0f782ed"
          },
          "Label": {
            "description": "The Option label",
            "type": "string",
            "example": "Weekly"
          },
          "Order": {
            "description": "The order of the option, Starts from 0",
            "type": "integer",
            "format": "int32",
            "example": 1
          },
          "IsDefault": {
            "description": "Whether the Option is default option or not",
            "type": "boolean",
            "example": true
          },
          "CanDelete": {
            "description": "Whether the Option can be deleted or not",
            "type": "boolean",
            "example": true
          },
          "Disabled": {
            "description": "Whether Custom Preference is disabled or not",
            "type": "boolean",
            "example": false
          }
        }
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_PurposeCustomPreferenceDto": {
        "properties": {
          "Id": {
            "description": "Unique identifier for the Custom Preference",
            "type": "string",
            "format": "uuid",
            "example": "194e0d3b-0ba8-4bc7-b046-e3ae42b2bd25"
          },
          "Name": {
            "description": "The display name of the Custom Preference",
            "type": "string",
            "example": "Email Frequency",
            "maxLength": 255,
            "minLength": 1
          },
          "Description": {
            "description": "Detailed description explaining the purpose and usage of this Custom Preference",
            "type": "string",
            "example": "Options for different frequencies to receive emails",
            "maxLength": 1000
          },
          "SelectionType": {
            "description": "Defines how options can be selected in this Custom Preference",
            "type": "string",
            "example": "SINGLE_CHOICE",
            "enum": [
              "SINGLE_CHOICE",
              "MULTI_CHOICE",
              "SINGLE_CHOICE",
              "MULTI_CHOICE"
            ]
          },
          "DisplayAs": {
            "description": "Specifies how the preference options should be displayed in the UI",
            "type": "string",
            "example": "BUTTONs",
            "enum": [
              "BUTTONS",
              "CHECKBOXES",
              "BUTTONs",
              "CHECKBOXES",
              "DROPDOWN",
              "RADIO_BUTTONS"
            ]
          },
          "CreatedDate": {
            "description": "Timestamp when the Custom Preference was created",
            "type": "string",
            "format": "date-time",
            "example": "2023-01-15T10:52:30.974Z"
          },
          "UpdatedDate": {
            "description": "Timestamp when the Custom Preference was last updated",
            "type": "string",
            "format": "date-time",
            "example": "2023-01-15T10:55:30.974Z"
          },
          "NumberOfOptions": {
            "description": "Total number of available options for this Custom Preference",
            "type": "integer",
            "format": "int64",
            "example": 4,
            "minimum": 0
          },
          "Required": {
            "description": "Indicates whether a response is mandatory for this Custom Preference",
            "type": "boolean",
            "example": false,
            "default": false
          },
          "NumberOfLanguages": {
            "description": "Number of languages this Custom Preference has been translated into",
            "type": "integer",
            "format": "int64",
            "example": 3,
            "minimum": 0
          },
          "DefaultLanguage": {
            "description": "The default language code for this Custom Preference (BCP 47 format)",
            "type": "string",
            "example": "en-us",
            "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
          },
          "Disabled": {
            "description": "Indicates if this Custom Preference is currently disabled",
            "type": "boolean",
            "example": false,
            "default": false
          },
          "Options": {
            "description": "List of available options for this Custom Preference",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceOptionDto"
            }
          },
          "Languages": {
            "description": "List of language configurations for this Custom Preference",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceLanguageDto"
            }
          },
          "Organizations": {
            "description": "List of Organization IDs that have access to this Custom Preference",
            "type": "array",
            "items": {
              "type": "string",
              "format": "uuid",
              "example": "712a1f61-a548-432f-afc4-5a383c28eeb2"
            }
          },
          "TotalLinkedActivePurposes": {
            "description": "Count of active purposes that reference this Custom Preference",
            "type": "integer",
            "format": "int64",
            "example": 5,
            "minimum": 0
          },
          "PurposeCustomPreferenceId": {
            "description": "Unique identifier of the Purpose and Custom Preference relation",
            "type": "string",
            "format": "uuid",
            "example": "c4a57a38-3774-45ad-9fa4-dbc545542232"
          }
        },
        "required": [
          "DisplayAs",
          "Id",
          "Name",
          "SelectionType"
        ]
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_PurposeDetailsDto": {
        "properties": {
          "Id": {
            "description": "Globally unique identifier of the Purpose",
            "type": "string",
            "format": "uuid",
            "example": "f2229953-b4b5-4042-8cb9-b78038cc4c46"
          },
          "Label": {
            "description": "Name of the Purpose",
            "type": "string",
            "example": "Marketing Communications"
          },
          "Description": {
            "description": "Detailed description of the Purpose's intended use",
            "type": "string",
            "example": "Collect customer emails for marketing purposes"
          },
          "Status": {
            "description": "Status of the Purpose",
            "type": "string",
            "example": "ACTIVE",
            "enum": [
              "DRAFT",
              "ACTIVE",
              "RETIRED"
            ]
          },
          "Version": {
            "description": "Current version of the Purpose",
            "type": "integer",
            "format": "int64",
            "example": 2
          },
          "RetireOnDate": {
            "description": "Date when the purpose will be retired",
            "type": "string",
            "format": "date-time",
            "example": "2025-12-31T23:59:59Z"
          },
          "ParentPurposeId": {
            "description": "Unique identifier of the parent purpose",
            "type": "string",
            "format": "uuid",
            "example": "ba54eb25-90f0-4633-ab12-c7bf5afdd856"
          },
          "ExternalReference": {
            "description": "External reference identifier for the purpose",
            "type": "string",
            "example": "EXT-REF-12345"
          },
          "PurposeType": {
            "description": "Type of the purpose",
            "type": "string",
            "example": "STANDARD",
            "enum": [
              "STANDARD",
              "COOKIE",
              "IAB",
              "MOBILE",
              "NOTIFICATION_OPT_OUT"
            ]
          },
          "ConsentLifeSpan": {
            "description": "Lifespan of the consent in seconds",
            "type": "integer",
            "format": "int64",
            "example": 7776000
          },
          "ImplicitConsentLifeSpan": {
            "description": "Lifespan for implicit consents in seconds",
            "type": "integer",
            "format": "int64",
            "example": 31536000
          },
          "ImplicitConsentConfirmDesc": {
            "description": "Description shown when confirming implicit consent",
            "type": "string",
            "example": "By continuing, you agree to our terms and conditions"
          },
          "PurposeCategory": {
            "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_AttributeValueInformation"
          },
          "Languages": {
            "description": "List of languages supported by the purpose",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_PurposeLanguageDto"
            }
          },
          "Topics": {
            "description": "List of topics associated with the purpose",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_PurposeTopicDto"
            }
          },
          "CustomPreferences": {
            "description": "List of custom preferences associated with the purpose",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_PurposeCustomPreferenceDto"
            }
          },
          "ExpiryDateType": {
            "description": "Date field considered for purpose lifespan/expiry",
            "type": "string",
            "example": "LAST_TRANSACTION_DATE",
            "enum": [
              "LAST_TRANSACTION_DATE",
              "CONSENT_DATE"
            ]
          },
          "attributeValues": {
            "description": "Map of attribute values associated with the purpose",
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "description": "Map of attribute values associated with the purpose",
              "items": {
                "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_AttributeValueInformation"
              }
            }
          },
          "IsMajorVersion": {
            "type": "boolean"
          },
          "HardOptOutDisplayFormat": {
            "description": "The format in which the purpose displays in a Trust Center when the consent status is Hard opt-out. Hard opt-out purposes can either be displayed but locked, or hidden.",
            "type": "string",
            "example": "HIDE",
            "enum": [
              "HIDE",
              "LOCK"
            ]
          },
          "attributes": {
            "description": "Additional attributes attached to the purpose",
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "description": "Additional attributes attached to the purpose",
              "items": {
                "type": "string",
                "description": "Additional attributes attached to the purpose"
              }
            }
          },
          "EnableGeolocation": {
            "description": "Flag to enable geolocation tracking for this purpose",
            "type": "boolean",
            "example": false
          },
          "LastMajorVersion": {
            "description": "Last major version number of the purpose",
            "type": "integer",
            "format": "int64",
            "example": 2
          },
          "VersionNotes": {
            "description": "Notes about the current version of the purpose",
            "type": "string",
            "example": "Updated to include new data retention policies"
          },
          "HardOptOutMessage": {
            "description": "The message to display with the purpose when the consent status is Hard opt-out. This message only displays when hardOptOutDisplayFormat is set to LOCK.",
            "type": "string",
            "example": "This purpose is required and cannot be opted out"
          }
        }
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_PurposeTopicDto": {
        "properties": {
          "Id": {
            "description": "The unique identifier of the Purpose and Topic relation",
            "type": "string",
            "format": "uuid",
            "example": "497c4383-2c61-4906-aed0-660e3fd03ef0"
          },
          "Name": {
            "description": "The Topic name",
            "type": "string",
            "example": "Car Marketing"
          },
          "IntegrationKey": {
            "description": "The Topic integration key (combination of Purpose and Topic names)",
            "type": "string",
            "example": "Marketing-Communications_Car-Marketing"
          },
          "CanDelete": {
            "description": "Whether this Topic can be deleted or not",
            "type": "boolean",
            "example": true
          }
        }
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_PagePurposeDetailsDto": {
        "type": "object",
        "properties": {
          "content": {
            "description": "The list of items for the current page.",
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_PurposeDetailsDto"
            },
            "type": "array"
          },
          "empty": {
            "description": "The flag to check if the entity is empty or not.",
            "type": "boolean",
            "example": false
          },
          "first": {
            "description": "The flag to check if the entity is first entity or not.",
            "type": "boolean",
            "example": true
          },
          "last": {
            "description": "The flag to check if the entity is last entity or not.",
            "type": "boolean",
            "example": false
          },
          "number": {
            "description": "The number associated with the result.",
            "type": "integer",
            "format": "int32",
            "example": 0
          },
          "numberOfElements": {
            "description": "Total number of elements in the result.",
            "type": "integer",
            "format": "int32",
            "example": 20
          },
          "pageable": {
            "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_PageableObject"
          },
          "sort": {
            "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_SortObject"
          },
          "totalPages": {
            "description": "Total number of pages in the result list.",
            "type": "integer",
            "format": "int32",
            "example": 5
          },
          "totalElements": {
            "description": "Total number of elements in the result.",
            "type": "integer",
            "format": "int64",
            "example": 50
          },
          "size": {
            "description": "Size of the result list.",
            "type": "integer",
            "format": "int32",
            "example": 20
          }
        }
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_PageableObject": {
        "properties": {
          "offset": {
            "type": "integer",
            "format": "int64"
          },
          "sort": {
            "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_SortObject"
          },
          "pageNumber": {
            "type": "integer",
            "format": "int32"
          },
          "pageSize": {
            "type": "integer",
            "format": "int32"
          },
          "paged": {
            "type": "boolean"
          },
          "unpaged": {
            "type": "boolean"
          }
        }
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_SortObject": {
        "properties": {
          "empty": {
            "type": "boolean"
          },
          "sorted": {
            "type": "boolean"
          },
          "unsorted": {
            "type": "boolean"
          }
        }
      },
      "ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceLanguageDto": {
        "properties": {
          "Name": {
            "description": "The Custom Preference name",
            "type": "string",
            "example": "Email Frequency"
          },
          "Description": {
            "description": "The description of the Custom Preference",
            "type": "string",
            "example": "Options for different frequencies to receive emails"
          },
          "Language": {
            "description": "The Custom Preference content language code",
            "type": "string",
            "example": "en-us"
          },
          "Default": {
            "description": "Whether this language is the default one for the Custom Preference",
            "type": "boolean",
            "example": true
          },
          "Options": {
            "description": "Options associated with a Custom Preference",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/ConsentPreferences-UniversalConsentPreferenceManag_CustomPreferenceOptionDto"
            }
          }
        },
        "required": [
          "Description",
          "Name"
        ]
      }
    },
    "securitySchemes": {
      "ConsentPreferences-UniversalConsentPreferenceManag_OAUTH2": {
        "type": "oauth2",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://{hostname}/api/access/v1/oauth/token",
            "scopes": {
              "CONSENT": "Consent Scope gives the user access to read/write operations",
              "CONSENT_READ": "Consent Read Scope gives the user read-only access"
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false,
    "proxy-enabled": false,
    "metrics-enabled": false
  },
  "x-onetrust": {
    "spec-label": "OpenAPI 3.1.0"
  }
}
```

# Sibling pages

* [Create Purpose](https://developer.onetrust.com/onetrust/reference/createpurposeusingpost.md)
* [Create New Purpose Version](https://developer.onetrust.com/onetrust/reference/createnewpurposeversionusingpost.md)
* [Update Purpose](https://developer.onetrust.com/onetrust/reference/editpurposeusingput.md)
* [Get List of Data Subjects by Purpose](https://developer.onetrust.com/onetrust/reference/getdatasubjectsforpurposesusingget.md)
* [Publish Purpose](https://developer.onetrust.com/onetrust/reference/publishpurposeusingput.md)
* [Retire Purpose](https://developer.onetrust.com/onetrust/reference/setretirementusingput.md)