Tutorial: Create Subject & Submit Data

In this tutorial, we will create a new Subject in our example study, ABCP-2022-01_TST3, enter data on the Demographics Form, and then submit the Form.

For additional examples and scenarios, refer to the extended EDC API Guide:

This tutorial uses the following APIs:

Authentication: User Name & Password
Create Subject/Casebook
Set Subject Status
Set Event Date
Upsert Form Data
Submit Form

Authenticate

Authentication Request

$ curl -X POST https://my-vault.veevavault.com/api/v23.3/auth \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/xml" \
-d "username=joe.smith@eke.com&password=my_password_here_as_body_parameter"

Authentication Response

{
  "responseStatus": "SUCCESS",
  "sessionId": "3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B462BE5C2BE2ACB82F6704FDA216EBDD69996EB23A6050723D1EFE6FA2B",
  "userId": 12021,
  "vaultIds": [
    {
      "id": 2596,
      "name": "Verteo Pharma - TST",
      "url": "https://my-vault.veevavault.com/api"
    }
  ]
  "vaultId": 12345
}

First, we connect and obtain a session from the vault, in this case a TST vault. (full detail: Authentication: User Name & Password)

Create Subject

Request - Create One Subject

curl -X POST  https://my-vault.veevavault.com/api/v23.3/app/cdm/subjects \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_TST3",
    "subjects": [
        {
            "study_country": "United States",
            "site": "101",         
            "subject": "101-005"
        }
    ]
}'

Response - Create One Subject

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "101-005"
        }
    ]
}

Next, we create a Subject / Casebook. The Casebook contains all of the Events (visits) and forms for the subject throughout the study. Our Subject number was set in the upstream system, so we set it, 101-005, at Site 101. (full detail: Create Subject/Casebook)

Set Subject Status

Request - Set Subject Status / Milestone

curl -L -X POST 'https://my-vault.veevavault.com/api/v23.3/app/cdm/subjects/actions/setstatus' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "ABCP-2022-01_DEV1",
    "subjects": [
        {
            "study_country": "United States",
            "site": "101",
            "subject": "101-005",
            "subject_status": "in_screening__v",
            "date": "2022-07-01"
        }
    ]
}'

Response - Set Subject Status / Milestone

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "101-005",
            "subject_status": "in_screening__v"
        }
    ]
}

Initial statuses in Vault CDMS are Pre Screen. We move the new Subject forward in status to In Screening, plus stamp a Screening milestone date. (full detail: Set Subject Status)

Set Event Date

Request - Set Event Date

curl -X POST https://my-vault.veevavault.com/api/v23.3/app/cdm/events/actions/setdate \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "events": [
          {
          "study_country": "United States",
          "site": "101",          
          "subject": "101-005",
          "eventgroup_name": "egSCR",
          "event_name": "evSCR",
          "date": "2022-07-01"
          }
      ]
    }'

Response - Set Event Date

{
    "responseStatus": "SUCCESS",
    "events": [
        {
          "responseStatus": "SUCCESS",
          "study_country": "United States",
          "site": "101",          
          "subject": "101-005",
          "eventgroup_name": "egSCR",
          "eventgroup_sequence": 1,
          "event_name": "evSCR",
          "event_sequence": 1,
          "date": "2022-07-01",
          "change_reason": "Action performed via the API",
          "externally_owned_date": true,
          "allow_planneddate_override": false                              
        }
    ]
}

Next, we set the event date of the Screening Event which in turn will build out the Forms of that Event, one of which is the Demographics form (design name = DM). The location of our Demographics Form is in the Event Group with design name egSCR and Event with design name evSCR. (full detail: Set Event Date)

Upsert Form Data (Items)

Request - Upsert Form Data (Items)

curl -X PUT https://my-vault.veevavault.com/api/v23.3/app/cdm/items \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "forms": [
        {
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "egSCR",
            "event_name": "evSCR",
            "form_name": "DM",
            "items": [
                {
                    "itemgroup_name": "igDM",
                    "item_name": "TRT_ONSET",
                    "value": "1998-UN-UN"
                },
                {
                    "itemgroup_name": "igDM",
                    "item_name": "DOB",
                    "value": "1978-11-22"
                },
                {
                    "itemgroup_name": "igDM",
                    "item_name": "SEX",
                    "value": "MALE"
                }
            ]
        }
    ]
}'

Response - Upsert Form Data (Items)

{
    "responseStatus": "SUCCESS",
    "items": [
        {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "DM",
            "form_sequence": 1,            
            "itemgroup_name": "igDM",
            "itemgroup_sequence": 1,
            "item_name": "TRT_ONSET",
            "value": "1998-UN-UN",
            "change_reason": "Action performed via the API",
            "externally_owned": true            
        },
        {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "DM",
            "form_sequence": 1,            
            "itemgroup_name": "igDM",
            "itemgroup_sequence": 1,
            "item_name": "DOB",
            "value": "1978-11-22",
            "change_reason": "Action performed via the API",
            "externally_owned": true            
        },
        {
            "responseStatus": "SUCCESS:UPDATED",
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "DM",
            "form_sequence": 1,            
            "itemgroup_name": "igDM",
            "itemgroup_sequence": 1,
            "item_name": "SEX",
            "value": "MALE",
            "change_reason": "Action performed via the API",
            "externally_owned": true                        
        }
    ]
}

With the Form now present under the Screening Event, we can now set data onto the Demographics Form. Our Items to be updated are read only on the Form, and all reside in an Item Group of design name igDM:

Treatment Onset (design name = TRT_ONSET) = 1998, unknown month and day.
Date of Birth (design name = DOB) = Nov 22nd, 1978
Gender (design name = SEX) = MALE (the codelist code used in that Item)

The Form is inside a non-repeating Event Group the Form itself does not repeat, nor does the Item Group of the Items repeat, so we can omit those sequence parameters. (1 is assumed for each) (full detail: Upsert Form Data)

Submit Form

Request - Submit Form

curl -X POST https://my-vault.veevavault.com/api/v23.3/app/cdm/forms/actions/submit \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "ABCP-2022-01_DEV1",
    "forms": [
        {
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "egSCR",
            "event_name": "evSCR",
            "form_name": "DM"
        }
    ]
}'

Response - Submit Form

{
    "study_name": "ABCP-2022-01_DEV1",
    "forms": [
        {
            "study_country": "United States",
            "site": "101",            
            "subject": "101-001",
            "eventgroup_name": "egSCR",
            "eventgroup_sequence": 1,
            "event_name": "evSCR",
            "event_sequence": 1,
            "form_name": "DM",
            "form_sequence": 1
        }
    ]
}

Finally, with data set on the Demographics Form, we submit the Form. (full detail: Submit Form)