> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://contentful.com/developers/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://contentful.com/developers/docs/_mcp/server. Contentful's User Management API helps organizations programmatically manage their organizations, organization memberships, teams, space memberships and more. > **Info** > > **Disclaimer:** The User Management API is available for Premium/Enterprise customers on [current pricing plans](https://www.contentful.com/pricing/). > **Info** > > **Note:** For EU data residency customers, the Base URL is *[https://api.eu.contentful.com](https://api.eu.contentful.com)*. ## Basic API information API Base URL `https://api.contentful.com` *This is a read/write API* ## Authentication A valid Content Management API [token](/references/authentication#the-content-management-api) must be included for all requests documented in this section, as follows: * In the `Authorization` header, specifically as: `Authorization: Bearer MY_ACCESS_TOKEN`. * In the `access_token` URL query parameter: `?access_token=MY_ACCESS_TOKEN` For security reasons Contentful strongly recommends passing the token via the `Authorization` header. Note that all permissions and access rights for API endpoints in this section are derived from the user on whose behalf the access token was generated. ## Pagination Contentful returns collections of resources in a wrapper object that contains extra information useful for paginating over large result sets. ### Example Usage Example query string: ``` limit=25&skip=50 ``` Example response: ```js { "sys": { "type": "Array" }, "skip": 50, "limit": 25, "total": 1256, "items": [ /* 25 individual resources */ ] } ``` ### Request Parameters | Parameter | Description | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `skip` | Specify an offset (as an integer) to paginate through results. The first "page" is `skip=0`. If your limit is `10`, the second page would be `skip=10`, the third would be `skip=20`, and so on. | | `limit` | Specify (as an integer) the maximum number of results. The maximum allowed value for limit is 100. | ### Response Attributes Paginated collections include a few additional top-level attributes related to pagination: | Attribute | Description | | --------- | ----------------------------------------------------------------------------------------- | | `skip` | The offset specified in the request | | `limit` | The limit specified in the request (or the default for the collection, if none specified) | | `total` | The total number (i.e. unpaginated) of resources in the collection specified by the query | | `items` | The resources for the current request, as scoped by any pagination or filter parameters | ## Sorting Results You can use the `order` parameter when paging through larger result sets to keep ordering predictable. ### Example Usage ``` order=name,-sys.createdAt ``` * Results are returned in ascending order for the specified attributes(s). * Use `-` in front of the attribute to specify descending order. * Separate multiple sort attributes with a comma. Sort fields are applied in the order specified. * Attributes are identified by their path (e.g. `sys.user.firstName`). * See [endpoint documentation](#/reference) for a list of which order attributes are supported for that endpoint. ## Including Related Resources You can use the `include` parameter to include linked resources in your response. This allows you to avoid making additional requests to fetch related resources. ### Example Usage ``` include=sys.user,sys.createdBy ``` As a more detailed explanation, envision the following API request and response: #### Request ``` GET /organizations/some_organization_id/organization_memberships ``` #### Response ```js { "total": 1, "limit": 25, "skip": 0, "sys": { "type": "Array" }, "items": [{ "sys": { "type": "OrganizationMembership", "id": "0xWanD4AZI2AR35wW9q51n", "version": 0, "createdAt": "2015-05-18T11:29:46.809Z", "updatedAt": "2015-05-18T11:29:46.809Z", "lastActiveAt": null, "status": "active", "sso": null, "user": { "sys": { "type": "Link", "linkType": "User", "id": "7BslKh9TdKGOK41VmLDjFZ" } }, "updatedBy": { "sys": { "type": "Link", "linkType": "User", "id": "7BslKh9TdKGOK41VmLDjFZ" } }, "createdBy": { "sys": { "type": "Link", "linkType": "User", "id": "7BslKh9TdKGOK41VmLDjFZ" } } }, "role": "admin" }] } ``` To fetch the linked users referenced in `sys.user` and `sys.createdBy`, you would normally need to make subsequent API calls. Using the `include` parameter you can request the linked users to be "included" in the response: #### Request ``` GET /organizations/some_organization_id/organization_memberships?include=sys.user,sys.updatedBy ``` #### Response ```js { // ... "items": [{ "sys": { "type": "OrganizationMembership", "id": "0xWanD4AZI2AR35wW9q51n", "version": 0, "createdAt": "2015-05-18T11:29:46.809Z", "updatedAt": "2015-05-18T11:29:46.809Z", "lastActiveAt": null, "status": "active", "sso": null, "user": { "sys": { "type": "Link", "linkType": "User", "id": "7BslKh9TdKGOK41VmLDjFZ" } }, "updatedBy": { "sys": { "type": "Link", "linkType": "User", "id": "7BslKh9TdKGOK41VmLDjFZ" } }, "createdBy": { "sys": { "type": "Link", "linkType": "User", "id": "7BslKh9TdKGOK41VmLDjFZ" } } }, "role": "admin" }], "includes": { "User": [{ "firstName": "Jane", "lastName": "Smith", "sys": { "id": "7BslKh9TdKGOK41VmLDjFZ", "type": "User" } }, { "firstName": "Mary", "lastName": "Jones", "sys": { "id": "7BslKh9TdKGOK41VmLDjFZ", "type": "User" } } ] } } ``` As you can see, the link objects (`user` and `createdBy`) are now fully resolved inside the `includes` attribute in the response, organized by type (i.e. `User`). ### Additional Notes * Linked resources are returned in the `includes` attribute of the response body, organized by type. * Only resources related to the current result set are included in the response. For example, if you are paginating through a list of results, `include` only includes related resources for that page (not the entire result set). * Resources to include are identified by their path in the query string. * See [endpoint documentation](#/reference) for a list of which include fields are supported for a given collection endpoint. ## Searching Multiple Attributes Some collection endpoints support a `query` parameter that performs a full-text search across multiple resource attributes. ### Example Usage ``` query=foo ``` * See [endpoint documentation](#/reference) for details about which fields are searched for a given endpoint. ## Filtering results You can use a variety of filter parameters to search and filter items in the response from collection endpoints. ### Example Usage ``` name[match]=fred&sys.user.sys.id[in]=abc123,zyx987&sys.updatedAt[lt]=2018-09-01 ``` In general the format of a filter parameter is as follows: ``` field[operator]=value ``` ### Operators For each supported field, one or more operators is available. This table explains their usage: | Operator | Description | | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- | | `eq` | The resource field exactly matches the specified value. E.g. `name[eq]=fred` (or `name=fred` for short) | | `ne` | The resource field does *not* match the specified value. E.g. `name[ne]=fred` | | `match` | The resource field does includes the specified value. E.g. `name[match]=fre` | | `in` | The resource field matches one of the specified values in a comma separated list. E.g. `sys.user.sys.id[in]=abc123,zyx987` | | `nin` | The resource field does *not* match at least one of the specified values in a comma separated list. E.g. `sys.user.sys.id[nin]=abc123,zyx987` | | `exists` | The resource field is not null if the specified value is `true`, or null if the specified value is `false`. E.g. `sys.updatedAt[exists]=true` | | `lt` | The resource field is less than the specified value. E.g. `sys.updatedAt[lt]=2018-09-01` | | `lte` | The resource field is less than or equal to the specified value. E.g. `sys.updatedAt[lte]=2018-09-01` | | `gt` | The resource field is greater than the specified value. E.g. `sys.updatedAt[gt]=2018-09-01` | | `gte` | The resource field is greater than or equal to the specified value. E.g. `sys.updatedAt[gte]=2018-09-01` |