User Status API

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

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 }
}