# Search Subjects

Search subjects

Endpoint: GET /api/v1/patient-registry/subject
Version: V1
Security: bearer

## Security:

  - `bearer` (unknown)
    http bearer JWT

## Query parameters:

  - `pageNumber` (number)
    Page number to retrieve (1-based index)

  - `pageSize` (number)
    Number of items per page

  - `sortField` (string)
    Field name to sort by

  - `sortIsDescending` (boolean)
    Whether to sort in descending order

  - `deleted` (boolean)

  - `identifier` (string)

  - `subjectIds` (array)

  - `firstName` (string)

  - `lastName` (string)

  - `city` (string)

  - `state` (string)

  - `addressLine1` (string)

  - `addressLine2` (string)

  - `postalCode` (string)

  - `gender` (string)

  - `birthDate` (string)

  - `birthDateStart` (string)

  - `birthDateEnd` (string)

  - `deathDate` (string)

  - `deathDateStart` (string)

  - `deathDateEnd` (string)

  - `email` (string)

  - `created` (string)

  - `createdStart` (string)

  - `createdEnd` (string)

  - `updated` (string)

  - `updatedStart` (string)

  - `updatedEnd` (string)

  - `phoneNumber` (string)

  - `externalIdentifiers` (array)

  - `labels` (array)

  - `cohortIds` (array)

  - `programDeliveryId` (string)

  - `programDeliveryStatus` (string)

  - `additionalNames` (array)

  - `totalQueries` (number)

  - `successfulQueries` (number)

  - `inflightQueries` (number)

  - `viewId` (string)

## Header parameters:

  - `ProjectId` (string, required)

## Response 200 fields (application/json):

  - `pageNumber` (number)
    Page number to retrieve (1-based index)

  - `pageSize` (number)
    Number of items per page

  - `sortField` (string)
    Field name to sort by

  - `sortIsDescending` (boolean)
    Whether to sort in descending order

  - `totalCount` (number, required)
    Total number of items matching the query

  - `results` (array, required)
    List of results for the current page

  - `results.id` (string, required)
    Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6

  - `results.created` (string, required)
    Example: 2025-05-26T23:30:40.912Z

  - `results.updated` (string, required)
    Example: 2025-05-26T23:30:40.912Z

  - `results.deleted` (string)
    Example: 2025-05-26T23:30:40.912Z

  - `results.identifier` (string, required)
    A human-readable, randomly generated, 6 character alpha-numeric identifier for the subject.
    Example: ABCD12

  - `results.firstName` (string, required)
    Example: David

  - `results.middleName` (string)
    Full middle name or a bare initial; omit if the subject has none. An update that omits this field clears any stored value.
    Example: Quincy

  - `results.lastName` (string, required)
    Example: Mann

  - `results.email` (string)
    Example: david.mann@example.com

  - `results.birthDate` (string)
    Example: 2023-05-26

  - `results.deathDate` (string)
    Example: 2023-05-26

  - `results.gender` (string)
    For guaranteed long term compatibility we recommend using the single character gender identifiers. We will optimistically accept other formats like 'male' and 'female'.
    Enum: "M", "F", "null"

  - `results.addressLine1` (string)
    Example: 123 Main St.

  - `results.addressLine2` (string)
    Example: Apt 4B

  - `results.addressCity` (string)
    Example: Minneapolis

  - `results.addressState` (string)
    Two letter state code
    Example: MN

  - `results.addressPostalCode` (string)
    5 or 9 digit postal code
    Example: 55401

  - `results.phoneNumber` (string)
    Example: 123-456-7890

  - `results.externalIdentifiers` (array)
    Example: [{"externalIdentifier":"12345","externalSystem":"Hospital A"}]

  - `results.externalIdentifiers.externalIdentifier` (string, required)

  - `results.externalIdentifiers.externalSystem` (string, required)

  - `results.labels` (array)
    Example: ["label_1","Label 2"]

  - `results.cohortNames` (array)

  - `results.additionalNames` (array)
    Example: [{"first":"Dave","last":"Mann"}]

  - `results.additionalNames.first` (string)
    At least one of 'first' and 'last' must be provided.

  - `results.additionalNames.last` (string)
    At least one of 'first' and 'last' must be provided.

  - `results.additionalNames.middle` (string)
    Full middle name or a bare initial for this alternate name; omit if unknown.

  - `results.additionalAddresses` (array)
    Example: [{"addressLine1":"456 Other St.","addressCity":"Saint Paul","addressState":"MN","addressPostalCode":"55101"}]

  - `results.additionalAddresses.addressLine1` (string)

  - `results.additionalAddresses.addressLine2` (string)

  - `results.additionalAddresses.addressCity` (string)

  - `results.additionalAddresses.addressState` (string)

  - `results.additionalAddresses.addressPostalCode` (string)

  - `results.tags` (array)

  - `results.tags.id` (string, required)
    Caller-supplied UUID for the tag value. Required on create: the column is `not null` with no database default and no server-side generation.

  - `results.tags.projectTagId` (string, required)
    The ProjectTag being valued. Its `dataType` decides which of the four value fields below is required.

  - `results.tags.valueText` (string)
    Value when the referenced ProjectTag has `dataType` `text`, and required in that case. Absent otherwise.

  - `results.tags.valueNumber` (number)
    Value when the referenced ProjectTag has `dataType` `number`, and required in that case. Absent otherwise.

  - `results.tags.valueDate` (string)
    Value when the referenced ProjectTag has `dataType` `date`, and required in that case. Absent otherwise.

  - `results.tags.valueBoolean` (boolean)
    Value when the referenced ProjectTag has `dataType` `boolean`, and required in that case. Absent otherwise.

  - `results.tags.subjectId` (string)
    Subject the tag belongs to. Assigned from the subject being created or updated; anything sent is ignored.

  - `results.tags.organizationId` (string)
    Assigned from the authenticated organization; anything sent is ignored.

  - `results.tags.projectId` (string)
    Assigned from the request `ProjectId`; anything sent is ignored.

  - `results.tags.created` (string)
    Assigned server-side on create; anything sent is ignored.

  - `results.tags.updated` (string)
    Assigned server-side on create and update; anything sent is ignored.