---
title: Requests and Responses
description: Each resource has an identifier. The resource type name (Users) is combined with the identifier (5caa81af-ec05-41ff-a709-c7378007a99c) to uniquely identify the resource to the PingDirectory or PingDirectoryProxy Server. For example:
component: pingdirectory
page_id: pingdirectory:directory-proxy-scim:requests-and-responses
canonical_url: https://developer.pingidentity.com/pingdirectory/directory-proxy-scim/requests-and-responses.html
section_ids:
  http-request-headers: HTTP request headers
  updating-resources: Updating resources
  specifying-attributes-to-return: Specifying attributes to return
  filtering-searches: Filtering searches
  pagination: Pagination
---

# Requests and Responses

Each resource has an identifier. The resource type name (`Users`) is combined with the identifier (`5caa81af-ec05-41ff-a709-c7378007a99c`) to uniquely identify the resource to the PingDirectory or PingDirectoryProxy Server. For example:

```none
/scim/v2/Users/5caa81af-ec05-41ff-a709-c7378007a99c
```

All requests and responses use UTF-8 character encoding and are formatted as JSON.

## HTTP request headers

* `Accept`

  Provide this header with a value of `application/scim+json` or `application/json`.

* `Content-Type`

  If you provide a request body (as with `POST`, `PUT`, and `PATCH` requests), also include this header with the value `application/scim+json` or `application/json`.

## Updating resources

SCIM resources are modified using the `PUT` and `PATCH` methods, described in sections 3.5.1 and 3.5.2 of [RFC 7644](https://datatracker.ietf.org/doc/html/rfc7644). For examples, refer to [User profile endpoints](user-profile-endpoints.html).

| HTTP method | Description                                                  |
| ----------- | ------------------------------------------------------------ |
| `PUT`       | Updates a resource by completely replacing it.               |
| `PATCH`     | Updates a resource by modifying only the changes to be made. |

Because access controls enforced by the PingDirectory server policies and scopes can limit your view of a resource, the server must assume that you may not have access to all attributes of a resource. This is important for `PUT` requests, because the server needs to distinguish between a case in which you explicitly wish to remove an attribute and a case in which you do not know about an attribute. The general rule is that the server ignores an attribute that is omitted from a `PUT` request, rather than deleting it. If you explicitly wish to delete an attribute, then you should set its value to `null`.

When you request a modification, the server computes the difference between the current state of the resource and the state specified by the modification request, applying a minimal set of changes when passing the modification request to the user store. In effect, this means that a `PUT` request is ultimately treated as if it were a `PATCH` request. This prevents unnecessary modifications from being sent to the user store and, more importantly, also prevents you from inadvertently removing attributes that you did not specify because you did not have access to them.

The server performs this diffing logic at the attribute and sub-attribute level, comparing each attribute in a modification request against the corresponding attribute in the current resource. For multivalued, complex attributes, the server iterates through the values in the modification request and tries to find the corresponding value in the current resource to determine a match. If it is found, it then diffs at the sub-attribute level.

This behavior is summarized by the following table.

| Operation                                                                                                                | Result                                  |
| ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- |
| `PUT` request omitting a simple single-valued attribute (such as userName).                                              | No change.                              |
| `PUT` or `PATCH` request setting a simple single-valued attribute to null.                                               | The attribute is deleted.               |
| `PUT` or `PATCH` request replacing the value of a multi-valued attribute, omitting an existing member of the array.      | The omitted member is deleted.          |
| `PUT` or `PATCH` request replacing the value of a complex attribute, omitting an existing sub-attribute from the object. | No change to the omitted sub-attribute. |

For example, if the current value of a resource's `phoneNumbers` attribute is:

```json
"phoneNumbers": [
   {
      "value": "054-757-2291",
      "type": "work",
      "primary":"true"
   }
]
```

And a modification request includes:

```json
"phoneNumbers": [
   {
      "value": "054-757-2291",
      "primary": "false"
   }
]
```

Then the final result is:

```json
"phoneNumbers": [
   {
      "value": "054-757-2291",
      "type": "work",
      "primary": "false"
   }
]
```

When finding a matching value in a complex attribute, matches of the `value`, `$ref`, `type`, and `display` sub-attribute values are given more weight when compared to values of other sub-attributes. This is done because the above sub-attribute values are typically unique for any given complex attribute.

## Specifying attributes to return

By default, all attributes that you are authorized to read are returned when a resource is requested. Your application can provide special query parameters to override this behavior.

| Parameter          | Description                                                                                                                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| attributes         | Indicates the set of attributes to include in the response. Takes a comma-separated list of attribute names. Extension schema attribute names must be prefixed with the extension schema URN. |
| excludedAttributes | Indicates a set of attributes to exclude from the response. Takes a comma-separated list of attribute names. Extension schema attribute names must be prefixed with the extension schema URN. |

|   |                                                                                                                              |
| - | ---------------------------------------------------------------------------------------------------------------------------- |
|   | The `attributes` and `excludedAttributes` parameters are mutually exclusive and should not be specified in the same request. |

## Filtering searches

Some endpoints support an optional `filter` parameter for filtering responses containing multiple resources. In general, if a SCIM path returns a single resource, it does not support filtering. If it returns multiple resources, then it generally supports filtering. For example, `/scim/v2/Users` supports filtering, but `+/scim/v2/Users/{userid}` does not.

|   |                                                                       |
| - | --------------------------------------------------------------------- |
|   | SCIM filters do not filter for attributes. They filter for resources. |

SCIM filtering is described in detail by [RFC 7644](https://tools.ietf.org/html/rfc7644), section 3.4.2.2. The following discussion should not be considered exhaustive.

The value of the filter parameter is a search filter, which typically takes the form `<attribute> <operator> <value>`. For example:

```none
filter=userName eq "pkd"
```

Search responses are always list responses, except in the case of an error.

The following attribute operators are supported:

| Operator | Description              |
| -------- | ------------------------ |
| eq       | equal                    |
| ne       | not equal                |
| co       | contains                 |
| sw       | starts with              |
| ew       | ends with                |
| pr       | present                  |
| gt       | greater than             |
| ge       | greater than or equal to |
| lt       | less than                |
| le       | less than or equal to    |

The following logical operators are supported:

| Operator |
| -------- |
| and      |
| or       |
| not      |

The following grouping operators are supported:

| Operator | Description                                                                                |
| -------- | ------------------------------------------------------------------------------------------ |
| ()       | Groups expressions to alter precedence.                                                    |
| \[]      | Contains a filter expression to be applied to a complex attribute. Refer to example below. |

The following is a sample of filtering by a core attribute:

```none
filter=userName eq "pkd"
```

The following is a sample of filtering by an extended attribute using the 'starts with' operator:

```none
filter=urn:pingidentity:schemas:sample:profile:1.0:birthDate sw "1939"
```

The following is a sample of a complex filter:

```none
filter=emails[value eq "glen@runciter.com"]
```

The following is a sample of a complex filter with two expressions:

```none
filter=emails[value eq "glen@runciter.com" and type eq "work"]
```

## Pagination

The client can provide pagination parameters to page through search result sets.

| Parameter  | Description                                                                                                                                                                                                                            |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| startIndex | The index of the first query result. Indexing starts at 1.                                                                                                                                                                             |
| count      | A non-negative integer specifying the maximum number of matching resources to return per page. If 0 is specified, then no resources will be returned, but the totalResults field will still indicate the number of matching resources. |