# User Status API

The User Status endpoint allows a customer (Relying Party) to query consented data subject (end user) identity data according to specified filters and result keys.

Requests may include filtering criteria to return only those data subject (end user) records that match the specified conditions.
All responses are paginated to optimise performance and simplify handling of large result sets.

* HTTP method: `POST`
* Path: `/v1/user-status`
* Requires a valid OAuth 2.0 bearer token with the appropriate scope


## Walkthrough

### Filtering Data

The `filters` object allows customers to constrain the result set returned by the `User Status` endpoint.

Filters act like query conditions, they tell the API which user records should be included in the results set.

A filter expression is passed in the request body as part of the `filters` object.  One or many field (key) and value pairs may be submitted as part of the filter expression.
When multiple fields are provided, they are evaluated with `AND` logic, a returned record must satisfy all conditions.

A list of supported fields is provided within the `User Status` API specification documentation page.

###### Example


```
{
  "filters": {
    "field_1": "value",
    "field_2": "value"
  }
}
```

#### Supported Filter Types

##### Exact Match Filters

String values are matched exactly and are case-sensitive.

###### Example


```
{ "registration_status": "active" }
```

##### Boolean Filters

Use `true` or `false` to match binary fields.

###### Example


```
{ "field": false }
```

##### Range Filters (comparisons)

Numeric and date fields can be filtered using comparison operators.
Supported operators include;

* `gte` → greater than or equal
* `lte` → less than or equal
* `gt` → strictly greater than
* `lt` → strictly less than
* `eq` → equals to


Use of the `eq` operator is mandatory if an exact match is required for numeric or date field.

###### Examples

Filter records where age is 65


```
{ "age": { "eq": 65 } }
```

Filter records where, age is greater than or equal to 18 AND where age is less than or equal to 65


```
{ "age": { "gte": 18, "lte": 65 } }
```

##### Combined Example

The following example illustrates a combination of filter criteria.


```
{
  "filters": {
    "registration_status": "active",
    "email": "user@example.com",
    "age": { "gte": 18, "lte": 65 },
    "is_deleted": false
  },
  "result_keys": ["id", "email", "name", "registration_status"],
  "pagination": { "limit": 10, "offset": 0 }
}
```

#### Filter Processing Behaviour

If no `filters` object is provided, all records accessible to the customer are returned.
Unknown fields or unsupported operators result in a `400 Bad Request` error.

Supplying more selective filters can improve performance by reducing the result set and is strongly recommended.

### Selecting Fields with `result_keys`

The `result_keys` array allows customers (Relying Parties) to control which fields are returned for each data subject (end user) record.
Instead of receiving an entire data subject object, you can explicitly request only the fields your application needs.

Importantly, use of the `result_keys` empowers customersto act inaccordance with data minimisation, extracting only required data for a given function.

A reduction in returned data also reduces response payloads, bandwidth requirements and improves overall performance.

If `result_keys` is omitted, the API response will return a default set of fields per object stored within the `results` array.

If `result_keys` is provided as an array of field name strings, only the specified fields will appear in each object inside the `results` array.

You can include any field that is available within a user object. Fields not available within a resultant object will be excluded from the response, invalid fields do not generate an error.

###### Example


```
"result_keys": ["id", "email", "name", "phone", "registration_status"]
```

##### Request including result_keys

The request below returns `id`, `first_name`, `last_name`, `middle_name`, `phone` fields for each matching record.


```
{
  "filters": {
    "email": "user@example.com"
  },
  "result_keys": ["id", "first_name", "last_name", "middle_name", "phone"],
  "pagination": {
    "limit": 5,
    "offset": 0
  }
}
```

#### Best Practices

* Request only what you need, this improves efficiency, reduces data handling in your application and aligns with data minimisation.
* Combine with filters, use `filters` to narrow down the dataset and `result_keys` to slim down the record shape. Together, they give you precise and efficient queries.


### Authentication

The `User Status` API endpoint requires OAuth 2.0 authentication.

Every request must include a valid access token obtained from the `OAuth Token` endpoint using the Client Credentials Grant flow.
This ensures that only an authorised B2B customer (Relying Party) can query consented Data Subject (end user) information and that access is both secure and auditable.

Each request must include an `Authorization` header as shown below.


```
Authorization: Bearer <access_token>
```

###### Example


```
POST /v1/user-status
Host: api.sqr-group.com
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6...
Content-Type: application/json

{
  "filters": {
    "email": "user@example.com"
  },
  "result_keys": ["id", "email", "name"],
  "pagination": { "limit": 5, "offset": 0 }
}
```