# Create Subject V2 Creates and returns the subject. Endpoint: POST /api/v2/patient-registry/subject Version: V1 Security: bearer ## Header parameters: - `ProjectId` (string, required) ## Request fields (application/json): - `id` (string, required) Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - `firstName` (string, required) Example: David - `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 - `lastName` (string, required) Example: Mann - `email` (string) Example: david.mann@example.com - `birthDate` (string) Example: 2023-05-26 - `deathDate` (string) Example: 2023-05-26 - `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 - `addressLine1` (string) Example: 123 Main St. - `addressLine2` (string) Example: Apt 4B - `addressCity` (string) Example: Minneapolis - `addressState` (string) Two letter state code Example: MN - `addressPostalCode` (string) 5 or 9 digit postal code Example: 55401 - `phoneNumber` (string) Example: 123-456-7890 - `externalIdentifiers` (array) Example: [{"externalIdentifier":"12345","externalSystem":"Hospital A"}] - `externalIdentifiers.externalIdentifier` (string, required) - `externalIdentifiers.externalSystem` (string, required) - `labels` (array) Example: ["label_1","Label 2"] - `additionalNames` (array) Example: [{"first":"Dave","last":"Mann"}] - `additionalNames.first` (string) At least one of 'first' and 'last' must be provided. - `additionalNames.last` (string) At least one of 'first' and 'last' must be provided. - `additionalNames.middle` (string) Full middle name or a bare initial for this alternate name; omit if unknown. - `additionalAddresses` (array) Example: [{"addressLine1":"456 Other St.","addressCity":"Saint Paul","addressState":"MN","addressPostalCode":"55101"}] - `additionalAddresses.addressLine1` (string) - `additionalAddresses.addressLine2` (string) - `additionalAddresses.addressCity` (string) - `additionalAddresses.addressState` (string) - `additionalAddresses.addressPostalCode` (string) - `tags` (array) - `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. - `tags.projectTagId` (string, required) The ProjectTag being valued. Its `dataType` decides which of the four value fields below is required. - `tags.valueText` (string) Value when the referenced ProjectTag has `dataType` `text`, and required in that case. Absent otherwise. - `tags.valueNumber` (number) Value when the referenced ProjectTag has `dataType` `number`, and required in that case. Absent otherwise. - `tags.valueDate` (string) Value when the referenced ProjectTag has `dataType` `date`, and required in that case. Absent otherwise. - `tags.valueBoolean` (boolean) Value when the referenced ProjectTag has `dataType` `boolean`, and required in that case. Absent otherwise. - `options` (object) - `options.initiateEhrQuery` (boolean) When true, initiates an EHR query for the subject after creation. Defaults to true when omitted. ## Response 201 fields (application/json): - `id` (string, required) Example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 - `created` (string, required) Example: 2025-05-26T23:30:40.912Z - `updated` (string, required) Example: 2025-05-26T23:30:40.912Z - `deleted` (string) Example: 2025-05-26T23:30:40.912Z - `identifier` (string, required) A human-readable, randomly generated, 6 character alpha-numeric identifier for the subject. Example: ABCD12 - `firstName` (string, required) Example: David - `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 - `lastName` (string, required) Example: Mann - `email` (string) Example: david.mann@example.com - `birthDate` (string) Example: 2023-05-26 - `deathDate` (string) Example: 2023-05-26 - `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 - `addressLine1` (string) Example: 123 Main St. - `addressLine2` (string) Example: Apt 4B - `addressCity` (string) Example: Minneapolis - `addressState` (string) Two letter state code Example: MN - `addressPostalCode` (string) 5 or 9 digit postal code Example: 55401 - `phoneNumber` (string) Example: 123-456-7890 - `externalIdentifiers` (array) Example: [{"externalIdentifier":"12345","externalSystem":"Hospital A"}] - `externalIdentifiers.externalIdentifier` (string, required) - `externalIdentifiers.externalSystem` (string, required) - `labels` (array) Example: ["label_1","Label 2"] - `cohortNames` (array) - `additionalNames` (array) Example: [{"first":"Dave","last":"Mann"}] - `additionalNames.first` (string) At least one of 'first' and 'last' must be provided. - `additionalNames.last` (string) At least one of 'first' and 'last' must be provided. - `additionalNames.middle` (string) Full middle name or a bare initial for this alternate name; omit if unknown. - `additionalAddresses` (array) Example: [{"addressLine1":"456 Other St.","addressCity":"Saint Paul","addressState":"MN","addressPostalCode":"55101"}] - `additionalAddresses.addressLine1` (string) - `additionalAddresses.addressLine2` (string) - `additionalAddresses.addressCity` (string) - `additionalAddresses.addressState` (string) - `additionalAddresses.addressPostalCode` (string) - `tags` (array) - `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. - `tags.projectTagId` (string, required) The ProjectTag being valued. Its `dataType` decides which of the four value fields below is required. - `tags.valueText` (string) Value when the referenced ProjectTag has `dataType` `text`, and required in that case. Absent otherwise. - `tags.valueNumber` (number) Value when the referenced ProjectTag has `dataType` `number`, and required in that case. Absent otherwise. - `tags.valueDate` (string) Value when the referenced ProjectTag has `dataType` `date`, and required in that case. Absent otherwise. - `tags.valueBoolean` (boolean) Value when the referenced ProjectTag has `dataType` `boolean`, and required in that case. Absent otherwise. - `tags.subjectId` (string) Subject the tag belongs to. Assigned from the subject being created or updated; anything sent is ignored. - `tags.organizationId` (string) Assigned from the authenticated organization; anything sent is ignored. - `tags.projectId` (string) Assigned from the request `ProjectId`; anything sent is ignored. - `tags.created` (string) Assigned server-side on create; anything sent is ignored. - `tags.updated` (string) Assigned server-side on create and update; anything sent is ignored. ## Response 400 fields (application/json): - `status` (number) - `title` (string) - `detail` (string) ## Response 403 fields (application/json): - `status` (number) - `title` (string) - `detail` (string) ## Response 409 fields (application/json): - `status` (number) - `title` (string) - `detail` (string) ## Response 429 fields (application/json): - `status` (number) - `title` (string) - `detail` (string) ## Response 500 fields (application/json): - `status` (number) - `title` (string) - `detail` (string) ## Response 503 fields (application/json): - `status` (number) - `title` (string) - `detail` (string)