Skip to content
/
Create Subjects

Create Subjects

Request

Creates all the subjects defined in the array. Maximum of 10 subjects allowed.

Security
bearer
Headers
ProjectIdstring, (uuid)required
Example:e6b01018-a333-4732-917e-fe38e91b0fdf
Bodyapplication/jsonrequired

Array of subjects to create, or a batch object with subjects array and optional batch-level options. Maximum of 10 subjects allowed.

One of:

Array of subjects to create. Maximum of 10 subjects allowed.

Array [
[].​idstring, (uuid)required
Example:"3fa85f64-5717-4562-b3fc-2c963f66afa6"
[].​firstNamestringrequired
Example:"David"
[].​lastNamestringrequired
Example:"Mann"
[].​middleNamestring

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"
[].​emailstring, (email)
Example:"david.mann@example.com"
[].​birthDatestring, (yyyy-mm-dd)
Example:"2023-05-26"
[].​deathDatestring, (yyyy-mm-dd)
Example:"2023-05-26"
[].​genderstring

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
Example:"M"
[].​addressLine1string
Example:"123 Main St."
[].​addressLine2string
Example:"Apt 4B"
[].​addressCitystring
Example:"Minneapolis"
[].​addressStatestring, (XX)

Two letter state code

Example:"MN"
[].​addressPostalCodestring, (00000)

5 or 9 digit postal code

Example:"55401"
[].​phoneNumberstring
Example:"123-456-7890"
[].​externalIdentifiersArray of objects(SubjectExternalIdentifier)
Example:
[
  {
    "externalIdentifier": "12345",
    "externalSystem": "Hospital A"
  }
]
[].​labelsArray of strings
Example:
[
  "label_1",
  "Label 2"
]
[].​additionalNamesArray of objects(SubjectAdditionalName)
Example:
[
  {
    "first": "Dave",
    "last": "Mann"
  }
]
[].​additionalAddressesArray of objects(SubjectAddressDto)
Example:
[
  {
    "addressLine1": "456 Other St.",
    "addressCity": "Saint Paul",
    "addressState": "MN",
    "addressPostalCode": "55101"
  }
]
[].​tagsArray of objects(SubjectTagDto)
]
POST
/api/v1/patient-registry/subject
curl -i -X POST \
  https://partner.xcures.com/api/v1/patient-registry/subject \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'ProjectId: e6b01018-a333-4732-917e-fe38e91b0fdf' \
  -d '[
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "firstName": "David",
      "middleName": "Quincy",
      "lastName": "Mann",
      "email": "david.mann@example.com",
      "birthDate": "2023-05-26",
      "deathDate": "2023-05-26",
      "gender": "M",
      "addressLine1": "123 Main St.",
      "addressLine2": "Apt 4B",
      "addressCity": "Minneapolis",
      "addressState": "MN",
      "addressPostalCode": "55401",
      "phoneNumber": "123-456-7890",
      "externalIdentifiers": [
        {
          "externalIdentifier": "12345",
          "externalSystem": "Hospital A"
        }
      ],
      "labels": [
        "label_1",
        "Label 2"
      ],
      "additionalNames": [
        {
          "first": "Dave",
          "last": "Mann"
        }
      ],
      "additionalAddresses": [
        {
          "addressLine1": "456 Other St.",
          "addressCity": "Saint Paul",
          "addressState": "MN",
          "addressPostalCode": "55101"
        }
      ],
      "tags": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "projectTagId": "63cdeb69-699a-46ee-9d32-dd85d73e6a64",
          "valueText": "string",
          "valueNumber": 0,
          "valueDate": "2019-08-24T14:15:22Z",
          "valueBoolean": true
        }
      ]
    }
  ]'

Responses

Bodyapplication/json
Array [
idstring, (uuid)required
Example:"3fa85f64-5717-4562-b3fc-2c963f66afa6"
createdstring, (ISO 8601)read-onlyrequired
Example:"2025-05-26T23:30:40.912Z"
updatedstring, (ISO 8601)read-onlyrequired
Example:"2025-05-26T23:30:40.912Z"
identifierstringread-onlyrequired

A human-readable, randomly generated, 6 character alpha-numeric identifier for the subject.

Example:"ABCD12"
firstNamestringrequired
Example:"David"
lastNamestringrequired
Example:"Mann"
deletedstring, (ISO 8601)read-only
Example:"2025-05-26T23:30:40.912Z"
middleNamestring

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"
emailstring, (email)
Example:"david.mann@example.com"
birthDatestring, (yyyy-mm-dd)
Example:"2023-05-26"
deathDatestring, (yyyy-mm-dd)
Example:"2023-05-26"
genderstring

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
Example:"M"
addressLine1string
Example:"123 Main St."
addressLine2string
Example:"Apt 4B"
addressCitystring
Example:"Minneapolis"
addressStatestring, (XX)

Two letter state code

Example:"MN"
addressPostalCodestring, (00000)

5 or 9 digit postal code

Example:"55401"
phoneNumberstring
Example:"123-456-7890"
externalIdentifiersArray of objects(SubjectExternalIdentifier)
Example:
[
  {
    "externalIdentifier": "12345",
    "externalSystem": "Hospital A"
  }
]
labelsArray of strings
Example:
[
  "label_1",
  "Label 2"
]
cohortNamesArray of strings
additionalNamesArray of objects(SubjectAdditionalName)
Example:
[
  {
    "first": "Dave",
    "last": "Mann"
  }
]
additionalAddressesArray of objects(SubjectAddressDto)
Example:
[
  {
    "addressLine1": "456 Other St.",
    "addressCity": "Saint Paul",
    "addressState": "MN",
    "addressPostalCode": "55101"
  }
]
tagsArray of objects(SubjectTagDto)
failureReasonstring
]
Response
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "created": "2025-05-26T23:30:40.912Z",
    "updated": "2025-05-26T23:30:40.912Z",
    "deleted": "2025-05-26T23:30:40.912Z",
    "identifier": "ABCD12",
    "firstName": "David",
    "middleName": "Quincy",
    "lastName": "Mann",
    "email": "david.mann@example.com",
    "birthDate": "2023-05-26",
    "deathDate": "2023-05-26",
    "gender": "M",
    "addressLine1": "123 Main St.",
    "addressLine2": "Apt 4B",
    "addressCity": "Minneapolis",
    "addressState": "MN",
    "addressPostalCode": "55401",
    "phoneNumber": "123-456-7890",
    "externalIdentifiers": [ … ],
    "labels": [ … ],
    "cohortNames": [ … ],
    "additionalNames": [ … ],
    "additionalAddresses": [ … ],
    "tags": [ … ],
    "failureReason": "string"
  }
]