Search Users

POST /users/search

Returns a paginated list of users

This endpoint should be used if there are more than 30 values for any given filter.

application/json

Body Required

  • search object
    Hide search attributes Show search attributes object
    • userIds array[string(uuid)]

      List of User IDs to filter by

    • upns array[string]

      List of UPNs to filter by

    • externalIds array[string]

      List of External IDs to filter by

    • usernames array[string]

      List of Usernames to filter by

    • name string

      Filter the results by the user's name.

    • email string(email)

      User email address to filter by

    • role string

      User roles

      Values are manager, editor, leadership, guardian, teacher, or student.

  • limit integer(int32)

    The maximum number of results to return per page.

    Minimum value is 1, maximum value is 100. Default value is 100.

  • offset integer(int32)

    Indicates the starting position or index (offset)

    Default value is 0.

  • cursor string(byte) | null

    The cursor for pagination. Encoded byte string used to navigate between pages.

  • sort object
    Hide sort attributes Show sort attributes object
    • field string

      The available sort fields.

      Values are createdAt, updatedAt, firstName, or lastName.

    • direction string

      The sort direction used for ordering the results. Can be "asc" (ascending) or "desc" (descending).

      Values are asc or desc.

Responses

  • 200 application/json

    List of users.

    Hide response attributes Show response attributes object
    • data array[object] Required
      Hide data attributes Show data attributes object
      • userId string(uuid) Required

        User UUID

      • roles array[string]

        User roles

        Values are manager, editor, leadership, guardian, teacher, or student.

      • username string Required

        The username of the user.

      • upn string

        The Unique Pupil Number (UPN) of the user.

      • externalId string

        External user identifier provided during onboarding or signup

      • fullName string Required

        The full name of the user.

      • firstName string Required

        The first name of the user.

      • middleName string

        The middle name of the user.

      • lastName string Required

        The last name of the user.

      • emails array[string(email)]

        A list of all email addresses associated with the user.

      • gender string Required

        The gender of the user.

        Values are male, female, other, or unknown. Default value is unknown.

      • dateOfBirth string(date)

        The date of birth of the user.

      • createdAt string(date-time)

        ISO 8601 formatted datetime string

      • updatedAt string(date-time)

        ISO 8601 formatted datetime string

    • pagination object Required
      Hide pagination attributes Show pagination attributes object
      • total integer(int32) Required

        The total number of items available.

      • limit integer(int32) Required

        The maximum number of results to return per page.

        Minimum value is 1, maximum value is 100. Default value is 100.

      • offset integer(int32) Required

        Indicates the starting position or index (offset)

        Default value is 0.

      • previousCursor string(byte) | null Required

        The cursor for pagination. Encoded byte string used to navigate between pages.

      • nextCursor string(byte) | null Required

        The cursor for pagination. Encoded byte string used to navigate between pages.
  • 400

    Invalid request.

  • 401

    Invalid authentication credentials

  • 403

    Not authorised to access this resource

POST /users/search 
curl \
 -X POST https://connect.century.tech/api/v1/users/search \
 -H "Content-Type: application/json" \
 -d '{"search":{"userIds":["68f06c66-702a-4c26-b8c5-b6dc4f81f25d"],"upns":["Y89421121401A"],"externalIds":["External_ID_123"],"usernames":["john_doe"],"name":"John","email":"john.doe@email.com","role":"student"},"limit":30,"offset":100,"cursor":"eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=","sort":{"field":"createdAt","direction":"asc"}}'
Request examples 
{
  "search": {
    "userIds": [
      "68f06c66-702a-4c26-b8c5-b6dc4f81f25d"
    ],
    "upns": [
      "Y89421121401A"
    ],
    "externalIds": [
      "External_ID_123"
    ],
    "usernames": [
      "john_doe"
    ],
    "name": "John",
    "email": "john.doe@email.com",
    "role": "student"
  },
  "limit": 30,
  "offset": 100,
  "cursor": "eyJsaW1pdCI6MSxiZWZvcmU6IiIsc29ydDpbWyJlbmREYXRlIiwiZGVzYyJdXX0=",
  "sort": {
    "field": "createdAt",
    "direction": "asc"
  }
}
Response examples (200) 
{
  "data": [
    {
      "upn": "Y89421121401A",
      "roles": [
        "student"
      ],
      "emails": [
        "john.doe@email.com"
      ],
      "gender": "male",
      "userId": "68f06c66-702a-4c26-b8c5-b6dc4f81f25d",
      "fullName": "John Doe",
      "lastName": "Doe",
      "username": "john_doe",
      "createdAt": "2024-01-01T12:00:00Z",
      "firstName": "John",
      "updatedAt": "2024-01-01T12:00:00Z",
      "externalId": "External_ID_123",
      "dateOfBirth": "2010-07-01"
    }
  ],
  "pagination": {
    "limit": 10,
    "total": 200,
    "offset": 0,
    "nextCursor": "eyJkYXRhIjp7fSwicmVxdWVzdCI6e30sImRpcmVjdGlvbiI6Ik5FWFQifQ==",
    "previousCursor": "eyJkYXRhIjp7fSwicmVxdWVzdCI6e30sImRpcmVjdGlvbiI6IlBSRVYifQ=="
  }
}