TOC Navbar
shell

Authentication

Authenticate your account using one of the methods outlined below. The response returns a session ID that you can use in subsequent API calls. Session IDs time out after a period of inactivity. The period varies by vault.

After acquiring a Vault Session ID, include it on every subsequent API call inside the Authorization HTTP request header.

Basic Authorization

Name Description
Authorization {sessionId}

Alternatively, you can use Salesforce™ or OAuth2/OIDC Delegated Requests.

The Vault API also accepts Vault Session IDs as Bearer tokens. Include Bearer keyword to send Vault Session IDs with as bearer tokens:

Bearer Token Authorization

Name Description
Authorization Bearer {sessionId}

User Name and Password

Request

$ curl -X POST https://{vault_domain_name}/api/{versions}/auth \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/xml" \
-d "username={username}&password={password}"

Response

{
  "responseStatus": "SUCCESS",
  "sessionId": "3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B462BE5C2BE2ACB82F6704FDA216EBDD69996EB23A6050723D1EFE6FA2B",
  "userId": 12021,
  "vaultIds": [
    {
      "id": 1776,
      "name": "PromoMats",
      "url": "https://promomats-veevapharm.veevavault.com/api"
    },
    {
      "id": 1777,
      "name": "eTMF",
      "url": "https://etmf-veevapharm.veevavault.com/api"
    },
    {
      "id": 1779,
      "name": "QualityDocs",
      "url": "https://qualitydocs-veevapharm.veevavault.com/api"
    }
  ],
  "vaultId": 1776
}

Authenticate your account using your Vault user name and password to obtain Vault Session ID.

POST https://login.veevavault.com/api/{version}/auth

Headers

Name Description
Content-Type multipart/form-data or application/x-www-form-urlencoded
Accept application/json (default) or application/xml

Body Parameters

Name Description
username Your Vault user name assigned by your administrator.
password Your Vault password associated with your assigned vault user name.
vaultDNS The DNS of the vault for which you want to generate a session. If omitted, generates a session for the user’s default vault.

OAuth 2.0 / OpenID Connect

Request

$ curl -X POST \
-H "Authorization: Bearer 1C29326C3DF" \
-H "Host: Bearer 1C29326C3DF" \
https://myserver.com/auth/oauth/session/_9ad0a091-cbd6-4c59-ab5a-d4f2870f218c

Response

{
  "responseStatus": "SUCCESS",
  "sessionId": "3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29EF9916AF41AF7E44B170BAA01F232B462BE5C2BE2ACB82F6704FDA216EBDD69996EB23A6050723D1EFE6FA2B",
  "userId": 12021,
  "vaultIds": [
    {
      "id": 1776,
      "name": "PromoMats",
      "url": "https://promomats-veevapharm.veevavault.com/api"
    },
    {
      "id": 1777,
      "name": "eTMF",
      "url": "https://etmf-veevapharm.veevavault.com/api"
    },
    {
      "id": 1779,
      "name": "QualityDocs",
      "url": "https://qualitydocs-veevapharm.veevavault.com/api"
    }
  ],
  "vaultId": 1776
}

Authenticate your account using OAuth 2.0 / Open ID Connect token to obtain a Vault Session ID. Learn more about OAuth 2.0 / Open ID Connect in Vault Help.

When requesting a sessionId, Vault allows the ability for Oauth2/OIDC client applications to pass the client_id with the request. Vault uses this client_id when talking with the introspection endpoint at the authorization server to validate that the access_token presented by the application is valid. Learn more about Client ID in the REST API Documentation.

POST https://login.veevavault.com/auth/oauth/session/{oath_oidc_profile_id}

Headers

Name Description
Authorization Bearer {access_token}
Accept application/json (default)

URI Path Parameters

Name Description
oath_oidc_profile_id The ID of your OAuth2.0 / Open ID Connect profile.

Body Parameters

Name Description
vaultDNS Optional: The DNS of the vault for which you want to generate a session. If omitted, the session is generated for user’s default vault.
client_id Optional: The ID of the client application at the Authorization server.

Authentication Type Discovery

Request

$ curl -X GET \
-H "Accept: application/json" \
https://login.veevavault.com/auth/discovery?username=meganmurray@veepharm.com&client_id=VaultCheckOut

Response: Password User

{
    "responseStatus": "SUCCESS",
    "errors": [],
    "data": {
        "auth_type": "password"
    }
}

Response: SSO User

{
    "responseStatus": "SUCCESS",
    "data": {
        "auth_type": "sso",
        "auth_profiles": [
            {
                "id": "_9ad0a091-cbd6-4z59-ab5a-d4f35789918c",
                "label": "VeePharm",
                "description": "",
                "vault_session_endpoint": "https://veepharm.com/auth/oauth/session/_9ad0a091-cbd6-4z59-ab5a-d4f35789918c",
                "use_adal": false,
                "as_client_id":"34524523452345234523452345098098234",
                "as_metadata": {
                    "issuer": "https://veevaintrospection.com/oauth2/asdf123",
                    "authorization_endpoint": "https://veevintrospection.com/oauth2/asdf123/v1/authorize",
                    "token_endpoint": "https://veevaintrospection.com/oauth2/asdf123/v1/token",
                    "registration_endpoint": "https://veevaintrospection.com/oauth2/v1/clients",
                    "jwks_uri": "https://veevaintrospection.com/oauth2/asdf123/v1/keys",
                    "response_types_supported": [
                        "code",
                        "token",
                        "code token"
                    ],
                    "response_modes_supported": [
                        "query"
                    ],
                    "introspection_endpoint": "https://veevatintrospection.com/oauth2/asdf1234/v1/introspect",
                    "introspection_endpoint_auth_methods_supported": [
                        "client_secret_basic",
                    ],
                    "revocation_endpoint": "https://veevaintrospection.com/oauth2/asdf123/v1/revoke",
                    "revocation_endpoint_auth_methods_supported": [
                        "client_secret_basic",
                    ],
                    "end_session_endpoint": "https://veevaintrospection.com/oauth2/asdf123/v1/logout"
                }
            }
        ]
    }
}

Discover the authentication type of a user. With this API, applications can dynamically adjust the login requirements per user, and support either username/password or OAuth2.0 / OpenID Connect authentication schemes.

POST https://login.veevavault.com/auth/discovery

Headers

Name Description
Accept application/json (default)

Query String Parameters

Name Description
username The user’s Vault user name.
client_id Optional: The user's mapped Authorization Server client_id. This only applies the SSO auth_type.

Response Details

The response specifies the user’s authentication type (auth_type):

If the user’s authentication type is sso, the response specifies the user’s authentication profiles (auth_profiles). If the user’s Security Policy is associated with:

If the Authorization Server Provider is set to use ADFS, the use_adal field will appear in the response as true. If the Authorization Server Provider is set to anything else, this field is false.

If the user provides a client_id and Client Application client ID mapping is defined on the OAuth 2.0 / OpenID Connect profile, the as_client_id field will appear in the response with the Authorization Server client ID value. If there is no defined mapping for the specified client_id, Vault will not include the as_client_id field in the response. Learn about Client ID Mapping in Vault Help.

Studies

Vault CDMS uses the Study object (study__v) to group together all study-related data in vault.

Retrieve Studies

Request

$ curl -X GET \
-H "Authorization: {SESSION_ID}" \
-H "Accept: application/json" \
https://myvault.veevavault.com/api/v19.3/app/cdm/studies

Response

{
    "responseStatus": "SUCCESS",
    "studies": [
        {
            "study_name": "CHOLECAP_DEV",
            "external_id": "S.CHOLECAP",
            "study_phase": "Phase I",
            "study_status": "Execution"
        },
        {
            "study_name": "CHOLECAP_PROD",
            "external_id": "S.CHOLECAP_PROD",
            "study_phase": "Phase I",
            "study_status": "Planning"
        },
        {
            "study_name": "DEETOZA_DEV1",
            "external_id": "DEETOZA_DEV1",
            "study_phase": "Phase I",
            "study_status": "Planning"
        },
        {
            "study_name": "WONDERDRUG_DEV1",
            "external_id": "WONDERDRUG_DEV1",
            "study_phase": "Phase I",
            "study_status": "Execution"
        },
        {
            "study_name": "CHOLECAP_UAT1",
            "external_id": "S.CHOLECAP",
            "study_phase": "Phase I",
            "study_status": "Planning"
        }
    ]
}

Retrieve a list of all Studies in your vault that you have permission to view.

The following rules govern study retrieval:

GET /api/{version}/app/cdm/studies

Headers

Name Description
Accept application/json (default)

Response Details

On SUCCESS, Vault returns a list of Studies that you have permission to view.

Metadata Field Description
name The Name (Study Number) field value from the Study record (study__v.name__v)
external_id The External ID field value from the Study record (study__v.oid__v)
study_status The Study Status field value from the Study record (study__v.study_status__v)
study_phase The Study Phase field value from the Study record (study__v.study_phase__v)

Subjects

Set Subject Status

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v20.1/app/cdm/subjects/actions/setstatus' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "Cholecap",
    "subjects": [
            {
                "site": "0101",
                "study_country": "United States",
                "subject": "0101-0010",
                "subject_status": "randomized__v",
                "date": "2020-03-03"
            }
        ]
    }'

Response

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "site": "0101",
            "subject": "0101-0010",
            "subject_status": "randomized__v"
        }
    ]
}

Set the Subject Status for a Subject and record the status change date in the appropriate field. Note that you can only use Set Subject Status on one Subject per request.

POST /api/{version}/app/cdm/subjects/actions/setstatus

A Subject must move through the different statuses in a certain order:

Notes on using Set Subject Status:

You can undo any changes made with this API using Unset Subject Status.

Headers

Name Description
Accept application/json (default)
Content-Type application/json (default)

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Subject (study__v.name__v)
subjects The Subjects (subject__v) you want to change the status of. As an array, provide the following for each Subject:
  • site: The Site Number (site__v.name__v) of the subject's assigned site
  • study_country
  • study_country: The Study Country (site__v.study_country__v) of the assigned site
  • subject_status: The Subject Status you're moving the Subject into. You must use the API Name of the status. See the list below.
  • date: The date to associate with the status change This date is recorded in different fields on the Subject record, depending on the target status. See the list below Use the "yyyy-mm-dd" format. Vault processes this date as UTC.

Subject Statuses

Status API Name Status Change Date Field
Pre Screen pre_screen__v Vault doesn't record a date for the initial status.
In screening in_screening__v screened_date__v
Screen Failure screen_failure__v screen_failed_date__v
Enrolled enrolled__v enrolled_date__v
Randomized randomized__v randomized_date__v
End of Treatment end_of_treatment__v end_of_treatment_date__v
Withdrawn withdrawn__v withdrawn_date__v
Complete complete__v end_of_study_date__v

Unset Subject Status

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v20.1/app/cdm/subjects/actions/unsetstatus' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID' \
-d '{
    "study_name": "Cholecap",
    "subjects": [
            {
                "site": "0101",
                "study_country": "United States",
                "subject": "0101-0010",
                "subject_status": "enrolled__v"
            }
        ]
    }'

Response

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "site": "0101",
            "subject": "0101-0010",
            "set_subject_status": "in_screening__v"
        }
    ]
}

You can use Unset Subject Status to clear a Status from a Subject. This sets the chosen status's field to No and clears the status change date (see the list above for a list of statuses and their date fields). The Subject will remain in the highest possible status. If you use this endpoint to remove the subject's current status, Vault moves the Subject into the last held status.

POST https://{vaultDNS}/api/{version}/app/cdm/subjects/actions/unsetstatus

Note that you can only use Unset Subject Status on one Subject per request.

Headers

Name Description
Accept application/json (default)
Content-Type application/json (default)

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Subject (study__v.name__v)
subjects The Subjects (subject__v) you want to change the status of. As an array, provide the following for each Subject:
  • site: The Site Number (site__v.name__v) of the subject's assigned site
  • study_country
  • study_country: The Study Country (site__v.study_country__v) of the assigned site
  • subject_status: The Status you want to clear from the Subject. The Subject will remain in the highest possible status. See the list above.

Casebooks

Create Casebooks

Request

curl -X POST  https://myvault.veevavault.com/api/v19.3/app/cdm/subjects \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "subjects": [
        {
            "site": "101",
            "study_country": "United States"
        },
        {
            "site": "102",
            "study_country": "United States"
        }
    ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "subjects": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0004"
        },
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "102",
            "subject": "SCR-0001"
        }
    ]
}

Create a new subject Casebook. Learn more about Casebooks in Vault CDMS Help.

POST /api/{version}/app/cdm/subjects

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Body Parameters

Name Description
study_name The Study Number (Name) of the Study to contain the Casebook (study__v.name__v)
site The Site Number (Name) of the Site you want to create the Casebook in (site__v.name__v)
study_country The Name of the Study Country you want to create the Casebook in (site__v.study_country__v)
subject Optional: The Subject ID (subject__v.name__v) of the Subject you want to create the Casebook for. If you don’t include a subject, Vault creates a subject for the casebook.

Event Groups

Create Event Groups

Request

curl -X POST https://myvault.veevavault.com/api/v20.1/app/cdm/eventgroups \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '
  {
    "study_name": "Cholecap",
    "eventgroups": [
      {
        "site": "0101",
        "study_country": "United States",
        "subject": "0101-0001",
        "eventgroup_name": "unscheduled_treatment_visits",
        "date": "2020-03-03"
      }
    ]
  }'

Response

{
    "responseStatus": "SUCCESS",
    "eventgroups": [
                {
                    "responseStatus": "SUCCESS",
                    "site": "0101",
                    "study_country": "United States",
                    "subject": "0101-0001",
                    "eventgroup_name": "unscheduled_treatment_visits"
                }
              ]
}

Create an Event Group. An Event Group is a container for multiple events, or visits, in a subject's casebook.

Event Groups can be repeating. The repeating Event Groups, or cycles, contain the same collection of Events and Forms for each sequence (repetition) of the Event Group.

POST /api/{version}/app/cdm/eventgroups

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Casebook you're adding an Event Group to (study__v.name__v)
eventgroups For each Event Group that you want to create, provide the following as an array:
  • site: The Site Number (Name) of the Site containing the Casebook you're adding an Event Group to (site__v.name__v)
  • study_country: The Study Country of the Site specified in the site parameter (site__v.study_country__v)
  • subject: The Subject ID (Name) of the Subject whose Casebook you're adding an Event Group to (subject__v.name__v)
  • eventgroup_name: The Name of the Event Group Definition (event_group_def__v.name__v) for the Event Group that you want to create
  • date: (Optional) Enter a Date to associate with the Event Group. Use "yyyy-mm-dd" format. This is for use with unscheduled event groups. If omitted, Vault sets the date to the current date.

Events

Set Event Date

Request

curl -X POST https://myvault.veevavault.com/api/v19.3/app/cdm/events/actions/setdate \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "S.CHOLECAP",
    "events": [
                {
                "site": "101",
                "study_country": "United States",
                "subject": "SCR-0002",
                "eventgroup_name": "Screening-Visit",
                "event_name": "Screening-Visit",
                "date": "2019-11-21"
                }
              ]
    }'

Response

{
    "responseStatus": "SUCCESS",
    "events": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "SCR-0002",
            "eventgroup_name": "Screening-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Screening-Visit",
            "event_sequence": 1
        }
    ]
}

Set the Event Date (Actual Date) for an Event.

POST /api/{version}/app/cdm/events/actions/setdate

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Event (study__v.name__v)
site The Site Number (Name) of the Site containing the Event (site__v.name__v)
study_country The Name of the Study Country containing the Event (site__v.study_country__v)
subject The Subject ID (Name) of the Subject for the Casebook containing the Event (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
eventgroup_sequence Optional: For repeating Event Groups, the Sequence of the Event Group containing the Event (event_group__v.seq__v). If omitted, the default value is 1.
event_name The Name of the Event Definition for the Event (event_def__v.name__v)
date Enter the Event Date, using "yyyy-mm-dd" format
change_reason If an Event Date already exists for this event, enter a Reason for Change, for example, "Date updated by remote system"
allow_planneddate_override Optional: Set this to true to set the Event Date to a date that falls outside of the event's planned date range. When true, Vault accepts the Event Date even if it falls outside of the planned date range. When false, Vault only accepts dates within range. If omitted, the default value is false.

Forms

Vault CDMS uses forms (form__v) to represent case report forms. Forms contain groups of data collection Items (item__v). Learn more about forms in Vault CDMS Help.

Create Form

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v20.1/cdm/forms' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "Cholecap",
    "forms": [
            {
                "site": "0101",
                "study_country": "United States",
                "subject": "0101-0001",
                "eventgroup_name": "baseline",
                "event_name": "baseline_visit",
                "form_name": "medical_history"
            }
        ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "forms": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0001",
            "eventgroup_name": "baseline",
            "eventgroup_sequence": 1,
            "event_name": "baseline_visit",
            "event_sequence": 1,
            "form_name": "medical_history",
            "form_sequence": 1
        }
    ]
}

Create a new instance of a repeating Form. Learn more about repeating forms in Vault CDMS Help.

POST /api/{version}/app/cdm/forms

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Item (study__v.name__v)
forms A JSON array with the information for each Form to create. The array must include the following sub-attributes for each Form:
  • site: The Site Number of the Site containing the Form (site__v.name__v)
  • study_country: The Name of the Study Country containing the Form (site__v.study_country__v)
  • subject: The Subject ID (Name) of the Subject for the Casebook containing the Form (subject__v.name__v)
  • eventgroup_name: The Name of the Event Group Definition containing the Form (event_group_def__v.name__v)
  • eventgroup_sequence: (Optional) If your Form is within a repeating Event Group, enter the Sequence Number (event_group__v.event_group_seq__v) of the Event Group containing your Form. If omitted, the default is "1".
  • event_name: The Name of the Event Definition for the Event containing the Form (event_def__v.name__v)
  • form_name: The Name of the Form Definition for the Form (form_def__v.name__v)

Create Item Group

Request

curl -L -X POST 'https://myvault.veevavault.com/api/v20.1/cdm/itemgroups' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
    "study_name": "Cholecap",
    "itemgroups": [
            {
                "site": "0101",
                "study_country": "United States",
                "subject": "0101-0001",
                "eventgroup_name": "baseline",
                "event_name": "baseline_visit",
                "form_name": "physical_exam",
                "itemgroup_name": "physical_exam"
            }
        ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "itemgroups": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "0101",
            "subject": "0101-0001",
            "eventgroup_name": "baseline",
            "eventgroup_sequence": 1,
            "event_name": "baseline_visit",
            "event_sequence": 1,
            "form_name": "physical_exam",
            "form_sequence": 1,
            "itemgroup_name": "physical_exam",
            "itemgroup_sequence": 7
        }
    ]
}

Create a new instance of a repeating Item Group. Learn more about repeating item groups in Vault CDMS Help.

POST /api/{version}/app/cdm/itemgroups

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Item (study__v.name__v)
itemgroups A JSON array with the information for each Item Group to create. The array must include the following sub-attributes for each Item Group:
  • site: The Site Number of the Site containing the Item Group (site__v.name__v)
  • study_country: The Name of the Study Country containing the Item Group (site__v.study_country__v)
  • subject: The Subject ID (Name) of the Subject for the Casebook containing the Item Group (subject__v.name__v)
  • eventgroup_name: The Name of the Event Group Definition containing the Item Group (event_group_def__v.name__v)
  • eventgroup_sequence: (Optional) If your Item Group is within a repeating Event Group, enter the Sequence Number (event_group__v.event_group_seq__v) of the Event Group containing your Item Group. If omitted, the default is "1".
  • event_name: The Name of the Event Definition for the Event containing the Item Group (event_def__v.name__v)
  • form_name: The Name of the Form Definition for the Item Group (item_group_def__v.name__v)
  • form_sequence: (Optional) If the Item Group is within a repeating Form, provide the Sequence Number of the Form (form__v.form_sequence__v) you want to add the Item Group to. If omitted, the default is "1".
  • itemgroup_name: The Name of the Item Group Definition (item_group_def__v.name__v) that you want to add.

Set Item Value

Request

curl -X POST https://myvault.veevavault.com/api/v19.3/app/cdm/items \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "forms": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "0101-0001",
            "eventgroup_name": "Enrollment-Visit",
            "event_name": "Enrollment-Visit",
            "form_name": "Randomization",
            "items": [
                {
                    "itemgroup_name": "Randomization",
                    "item_name": "Randomization-number",
                    "value": "42957928309475"
                },
                {
                    "itemgroup_name": "Randomization",
                    "item_name": "Date-of-randomization",
                    "value": "2019-11-21"
                }
            ]
        }
    ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "items": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "0101-0001",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Randomization-number"
        },
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "0101-0001",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization"
        }
    ]
}

Set the value for a data collection Item. Note that you can't use this API to set the value of read-only or derived Items.

POST /api/{version}/app/cdm/items

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Item (study__v.name__v)
site The Site Number of the Site containing the Item (site__v.name__v)
study_country The Name of the Study Country containing the Item (site__v.study_country__v)
subject The Subject ID of the Subject for the Casebook containing the Item (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Item (event_group_def__v.name__v)
eventgroup_sequence Optional: For repeating Event Groups, the sequence of the Event Group containing the Item (event_group__v.seq__v)
event_name The Name of the Event Definition for the Item (event_def__v.name__v)
form_name The Name of the Form Definition for the Item (form_def__v.name__v)
form_sequence Optional: For repeating Forms, the sequence of the Form (form__v.seq__v)
items A JSON array with the information for each Item value to be set. The array must include the following sub-attributes for each Item:
  • itemgroup_name: The Name of the Item Group Definition for the Item Group containing the Item (item_group_def__v.name__v)
  • itemgroup_sequence: Optional: For repeating Item Groups, the sequence of the Item Group (item_group__v.seq__v)
  • item_name: The Name of the Item's Item Definition (item_def__v.name__v)
  • value: Enter the value for this Item
  • unit_value: Optional: For unit-type Items, enter the name of the unit (item__v.unit_value__v)
  • change_reason: (Optional) If the Item already had a value, enter a reason for change.

Submit Form

Request

curl -X POST https://myvault.veevavault.com/api/v19.3/app/cdm/forms/actions/submit \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "forms": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "0101-0001",
            "eventgroup_name": "Enrollment-Visit",
            "event_name": "Enrollment-Visit",
            "form_name": "Randomization"
        }
    ]
}'

Response

{
    "study_name": "Cholecap",
    "forms": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "0101-0001",
            "eventgroup_name": "Enrollment-Visit",
            "event_name": "Enrollment-Visit",
            "form_name": "Randomization"
        }
    ]
}

Submit a Form.

POST /api/{version}/app/cdm/forms/actions/submit

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the Event (study__v.name__v)
site The Site Number of the Site containing the Event (site__v.name__v)
study_country The Name of the Study Country containing the Event (site__v.study_country__v)
subject The Subject ID of the Subject for the Casebook containing the Event (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
eventgroup_sequence Optional: For repeating Event Groups, the sequence of the Event Group containing the Event (event_group__v.seq__v)
event_name The Name of the Event Definition for the Event (event_def__v.name__v)
form_name The Name of the Form Definition for the Form (form_def__v.name__v)
form_sequence Optional: For repeating Forms, the sequence of the Form (form__v.seq__v)

Edit Submitted Form

Request

curl -X POST https://cdms.vaultdev.com/api/v19.3/app/cdm/forms/actions/edit \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "forms": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "event_name": "Enrollment-Visit",
            "form_name": "Randomization",
            "change_reason": "Transcription error"
        }
    ]
}'

Response

{
    "responseStatus": "SUCCESS",
    "forms": [
        {
            "responseStatus": "SUCCESS",
            "study_country": "United States",
            "site": "101",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Enrollment-Visit",
            "form_sequence": 1,
            "change_reason": "Transcription error"
        }
    ]
}

Make a submitted Form editable and enter a reason for change. Learn more about editing Forms in Vault CDMS Help.

POST /api/{version}/app/cdm/forms/actions/edit

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Body Parameters

Name Description
study_name The Study Number (Name) of the Study (study__v.name__v)
study_country The Name of the Study Country (site__v.study_country__v)
site The Site Number of the Site (site__v.name__v)
subject Optional: Enter the Subject ID of the subject for the Casebook containing the Form (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Form (event_group_def__v.name__v)
eventgroup_sequence Optional: For repeating Event Groups, the sequence of the Event Group containing the Form (event_group__v.seq__v)
event_name The Name of the Event Definition for the Event (event_def__v.name__v)
form_name The Name of the Form Definition for the Form (form_def__v.name__v)
form_sequence Optional: For repeating Forms, the sequence of the Form (form__v.seq__v)
change_reason Enter a reason for change.

Queries

Queries are a method of questioning entered data. There are two types of queries: system and manual.

A system query is an edit check, run by Vault EDC. Vault creates system queries based on configured data validation rules in your Study. For example, the system would create a query on a value that was outside of the defined acceptable range. If you update your data to a value that’s in range, Vault automatically closes the query for you.

A manual query is a Query record that a CRA or Data Manager creates, or that you create via the Open Query API.

Learn more about queries in Vault CDMS Help.

Retrieve Queries

Request

curl -L -X GET 'myvault.veevavault.com/api/v19.3/app/cdm/queries?study_name=S.CHOLECAP&site=101&study_country=United%20States&subject=42957928309475&query_status=open__v,closed__v' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "id": "OPW000000000201",
            "query_name": "VV-000002",
            "manual": true,
            "created_date": "2019-11-21T22:40:49Z",
            "created_by": "151125",
            "query_status": "open__v",
            "study_country": "United States",
            "site": "101",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization",
            "rule_definition": null,
            "messages": [
                {
                    "id": "OPY000000000301",
                    "activity": "open__v",
                    "message": "Didn't we do enrollment on the 20th for this round of subjects?",
                    "message_date": "2019-11-21T22:40:50Z",
                    "message_by": "151125"
                }
            ]
        }
    ]
}

Retrieve a list of all queries for a Site, a Subject, or a Form. You can also retrieve only queries in a certain Query Status.

GET /api/{version}/app/cdm/queries?study_name={study_name}&site={site}&study_country={study_country}

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Query String Parameters

Include the following parameters to filter the results:

Name Description
study_name The Study Number (Name) of the Study (study__v.name__v)
study_country The Name of the Study Country containing the Site (site__v.study_country__v)
site The Site Number of the Site (site__v.name__v)
subject Optional: Enter a subject's Subject ID to retrieve queries only for that Subject (subject__v.name__v). If omitted, the endpoint retrieves queries for all subjects at the site.
form_name Optional: The Name of the Form Definition (form_def__v.name__v). Include this parameter to return only queries on the chosen Form. If omitted, the endpoint retrieves queries for all forms.
query_status Optional: The Query Statuses to include, as an array. Include this parameter to return only queries with the chosen statuses. If omitted, the endpoint retrieves all queries. Available statuses:
  • open__v (Open)
  • answered__v (Answered)
  • closed__v (Closed)

Response Details

On SUCCESS, Vault returns a list of queries meeting your filter criteria.

Open Query

Request

curl -X POST \
  https://myvault.veevavault.com/api/v19.3/app/cdm/queries \
  -H "Authorization: {SESSION_ID}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "study_name": "Labrinone",
    "queries": [
            {
                "site": "101",
                "study_country": "United States",
                "subject": "101001",
                "query_global_id": 284536,
                "eventgroup_name": "EG.SCR",
                "eventgroup_sequence": 1,
                "event_name": "EV.SCR",
                "form_name": "F.DM",
                "form_sequence": 1
                "itemgroup_name": "IG.DEMOG",
                "itemgroup_sequence": 1,
                "item_name": "DOB",
                "message": "This date does not match our records."
            },
            ]
  }'

Response


{
    "responseStatus": "SUCCESS",
    "queries": [
                {
                    "responseStatus": "SUCCESS",
                    "id": "OPW000000006001",
                    "query_name": "VV-000091",
                    "query_status": "open__v",
                    "site": "101",
                    "study_country": "United States",
                    "subject": "101-001",
                    "eventgroup_name": "EG.SCR",
                    "eventgroup_sequence": 1,
                    "event_name": "EV.SCR",
                    "form_name": "F.DM",
                    "form_sequence": 1,
                    "itemgroup_name": "IG.DM",
                    "itemgroup_sequence": 1,
                    "item_name": "DOB"
                },
                :
                :
              ]
}

Open a Query on an Item or Event Date.

POST /api/{version}/app/cdm/queries

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Body Parameters

Name Description
study_name The Study Number (Name) of the Study (study__v.name__v)
site The Site Number of the Site(site__v.name__v)
study_country The Name of the Study Country for the Site (site__v.study_country__v)
subject The Subject ID of the Subject for the Casebook (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
eventgroup_sequence Optional: For repeating Event Groups, the sequence of the Event Group containing the Event (event_group__v.seq__v)
event_name The Name of the Event Definition for the Event (event_def__v.name__v)
form_name (For Item-level queries) The Name of the Form Definition for the Form (form_def__v.name__v)
form_sequence (For Item-level queries) Optional: For repeating Forms, the sequence of the Form (form__v.seq__v)
itemgroup_name (For Item-level queries) The Name of the Item Group Definition for the Item Group (item_group_def__v.name__v)
itemgroup_sequence (For Item-level queries) The Item Group Sequence (sequence number) of the Item Group containing the Item (item_group__v.itemgroup_seq__v)
item_name (For Item-level queries) The Name of the Item Definition for the Item (item_def__v.name__v)
message Enter the query message text.

Response Details

On SUCCESS, Vault opens a new query on either the Item or the Event Date.

Answer Query

Request

curl -X POST  https://myvault.veevavault.com/api/v19.3/app/cdm/queries/actions/answer \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "queries": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization",
            "message": "This subject was enrolled late."
        }
    ]
  }'

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000000201",
            "query_name": "VV-000002",
            "query_status": "open__v",
            "study_country": "United States",
            "site": "101",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization"
        }
    ]
}

Answer an open query with a comment.

POST /api/{version}/app/cdm/queries/actions/answer

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Body Parameters

Name Description
study_name The Study Number (Name) of the Study containing the query (study__v.name__v)
site The Site Number of the Site(site__v.name__v)
study_country The Name of the Study Country for the Site (site__v.study_country__v)
subject The Subject ID of the Subject for the Casebook (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
eventgroup_sequence Optional: For repeating Event Groups, the sequence of the Event Group containing the Event (event_group__v.seq__v)
event_name The Name of the Event Definition for the Event (event_def__v.name__v)
form_name (For Item-level queries) The Name of the Form Definition for the Form (form_def__v.name__v)
form_sequence (For Item-level queries) Optional: For repeating Forms, the sequence of the Form (form__v.seq__v)
itemgroup_name (For Item-level queries) The Name of the Item Group Definition for the Item Group (item_group_def__v.name__v)
itemgroup_sequence (For Item-level queries) The Item Group Sequence (sequence number) of the Item Group containing the Item (item_group__v.itemgroup_seq__v)
item_name (For Item-level queries) The Name of the Item Definition for the Item (item_def__v.name__v)
message Enter the query message text.

Close Query

Request

curl -X POST  https://myvault.veevavault.com/api/v19.3/app/cdm/queries/actions/close \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "queries": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization",
            "message": "This issue is now resolved. Query closed."
        }
    ]
  }'

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000000201",
            "query_name": "VV-000002",
            "query_status": "closed__v",
            "study_country": "United States",
            "site": "101",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization"
        }
    ]
}

Close a query.

POST /api/{version}/app/cdm/queries/actions/close

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Body Parameters

Name Description
study_name The Study Number (Name) of the Study (study__v.name__v)
site The Site Number of the Site(site__v.name__v)
study_country The Name of the Study Country for the Site (site__v.study_country__v)
subject The Subject ID of the Subject for the Casebook (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
eventgroup_sequence Optional: For repeating Event Groups, the sequence of the Event Group containing the Event (event_group__v.seq__v)
event_name The Name of the Event Definition for the Event (event_def__v.name__v)
form_name (For Item-level queries) The Name of the Form Definition for the Form (form_def__v.name__v)
form_sequence (For Item-level queries) Optional: For repeating Forms, the sequence of the Form (form__v.seq__v)
itemgroup_name (For Item-level queries) The Name of the Item Group Definition for the Item Group (item_group_def__v.name__v)
itemgroup_sequence (For Item-level queries) The Item Group Sequence (sequence number) of the Item Group containing the Item (item_group__v.itemgroup_seq__v)
item_name (For Item-level queries) The Name of the Item Definition for the Item (item_def__v.name__v)
message Optional: Enter a comment to add to the query as you close it.

Reopen Query

Request

curl -X POST  https://myvault.veevavault.com/api/v19.3/app/cdm/queries/actions/reopen \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "queries": [
        {
            "site": "101",
            "study_country": "United States",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization",
            "message": "Sign-in logs indicate that this subject was actually enrolled on the 20th. Reopening the query."
        }
    ]
  }'

Response

{
    "responseStatus": "SUCCESS",
    "queries": [
        {
            "responseStatus": "SUCCESS",
            "id": "OPW000000000201",
            "query_name": "VV-000002",
            "query_status": "open__v",
            "study_country": "United States",
            "site": "101",
            "subject": "42957928309475",
            "eventgroup_name": "Enrollment-Visit",
            "eventgroup_sequence": 1,
            "event_name": "Enrollment-Visit",
            "event_sequence": 1,
            "form_name": "Randomization",
            "form_sequence": 1,
            "itemgroup_name": "Randomization",
            "itemgroup_sequence": 1,
            "item_name": "Date-of-randomization"
        }
    ]
}

Reopen a closed query.

POST /api/{version}/app/cdm/queries/actions/reopen

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Body Parameters

Name Description
study_name The Study Number (Name) of the Study (study__v.name__v)
site The Site Number of the Site(site__v.name__v)
study_country The Name of the Study Country for the Site (site__v.study_country__v)
subject The Subject ID of the Subject for the Casebook (subject__v.name__v)
eventgroup_name The Name of the Event Group Definition containing the Event (event_group_def__v.name__v)
eventgroup_sequence Optional: For repeating Event Groups, the sequence of the Event Group containing the Event (event_group__v.seq__v)
event_name The Name of the Event Definition for the Event (event_def__v.name__v)
form_name (For Item-level queries) The Name of the Form Definition for the Form (form_def__v.name__v)
form_sequence (For Item-level queries) Optional: For repeating Forms, the sequence of the Form (form__v.seq__v)
itemgroup_name (For Item-level queries) The Name of the Item Group Definition for the Item Group (item_group_def__v.name__v)
itemgroup_sequence (For Item-level queries) The Item Group Sequence (sequence number) of the Item Group containing the Item (item_group__v.itemgroup_seq__v)
item_name (For Item-level queries) The Name of the Item Definition for the Item (item_def__v.name__v)
message Optional: Enter a comment to add to the query as you reopen it.

Users

You can create user accounts and assign users a role in your Study.

Learn more about study user access in Vault CDMS Help.

Retrieve Users

Request

$ curl -X GET \
https://myvault.veevavault.com/api/v19.3/app/cdm/users
  -H "Authorization: {SESSION_ID}" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
         "study_name": "Labrinone",
         "user_names": ["olivia.eva@labrinonepharma.com"]
   }'

Response

{
    "responseStatus": "SUCCESS",
    "users": [
                {
                "study_instance": "Labrinone_UAT1"
                "user_name": "olivia.eva@labrinonepharma.com",
                "user_first_name": "Olivia",
                "user_last_name": "Ava",
                "user_email": "olivia.eva@email.com",
                "user_timezone": "(GMT-05:00) Eastern Standard Time (America/New_York)",
                "user_title": "Clinical Research Associate",
                "study_access": "Enabled",
                "security_policy": "Basic",
                "user_language": "en",
                "user_locale": "en_US",
                "company": "VeevaPharm",
                "security_profile": "Data Entry",
                "site_access": "All Sites",
                "country_access": "Mexico, Australia",
                "study_role": "CDMS Lead Data Manager"
                }
              ]
}

Retrieve a list of Users in your Study.

GET /api/{version}/app/cdm/users

Headers

Name Description
Accept application/json (default)

Body Parameters

Name Description
study_name The Study Number (Name) of the Study (study_master__v.name__v for automatic deployment studies, study__v.label__v for manual deployment studies)
user_names Optional Include a list of user names (user__v.user_name__v) to retrieve information about specific users. If omitted, Vault returns all Users for the specified Study.

Response Details

On SUCCESS, Vault returns a list of users currently in your Study, or, if you provided a User Name, information for that user.

Create Users

Request

curl -X POST https://myvault.veevavault.com/api/v19.3/app/cdm/users \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: {SESSION_ID}' \
  -d '{
    "study_name": "Cholecap",
    "users": [
        {
            "study_environment": "CHOLECAP_DEV",
            "user_name": "olivia.eva@verteopharma.com",
            "user_first_name": "Olivia",
            "user_last_name": "Eva",
            "user_email": "oliva-eva@verteopharma.com",
            "user_timezone": "(GMT-05:00) Eastern Standard Time (America/New_York)",
            "user_title": "Clinical Research Associate",
            "study_access": "Enabled",
            "user_language": "en",
            "user_locale": "en_US",
            "company": "Verteo Pharma",
            "security_profile": "Data Review",
            "site_access": "All Sites",
            "country_access": "",
            "study_role": "CDMS Clinical Research Associate",
            "federated_id": "",
            "security_policy": "Basic"
        }
    ]
  }'

Response

{
    "responseStatus": "SUCCESS",
    "users": [
        {
            "email__sys": "oliva-eva@verteopharma.com",
            "study_access__v": "Enabled",
            "sites__v": "All Sites",
            "study_instance__v": "CHOLECAP_DEV",
            "security_policy__sys": "Basic",
            "locale__sys": "en_US",
            "bulk_import_status": "Warning: Adding Cross Vault User",
            "role__v": "CDMS Clinical Research Associate",
            "language__sys": "en",
            "countries__v": "",
            "timezone__sys": "(GMT-05:00) Eastern Standard Time (America/New_York)",
            "username__sys": "olivia.eva@verteopharma.com",
            "first_name__sys": "Olivia",
            "last_name__sys": "Eva",
            "errors": []
        }
    ]
}

Create a new user and assign them to your study.

POST /api/{version}/app/cdm/users

Headers

Name Description
Accept application/json (default)
Content-Type application/json

Body Parameters

Name Description
study_name For automated deployment studies, the Name of the Study Master (study_master__v.name__v) you want to assign the user to. For manual deployment studies, the Name of the Study (study__v.name__v).
study_environment For automated deployment studies, the Name field value from the Study Instance record (study_instance__v.name__v). For manual deployment studies, exclude this parameter.
user_name The user’s vault username (login credential). For example, ewoodhouse@veepharm.com
user_first_name The user’s first name
user_last_name The user’s last name
user_email The user’s email address
company Optional: The user’s company
user_title Optional: The user’s title
user_timezone The user’s time zone. See a list of available timezones and their appropriate entry format here
user_locale The user’s location. See a list of available locales and their appropriate entry format here
user_language The user’s preferred language. See a list of available languages and their appropriate entry format here.
study_role The Label of the Study Role (Application Role) for this user (application_role_v.label_v).
study_access Enter "Disabled" or "Enabled". If "Disabled", this user will not have access to the Study in their vault.
site_access Enter a Site or list of Sites (comma separated) to allow the User to access. To give the user access to all sites in your study, enter "all sites".
country_access Enter a Study Country or list of Study Countries (comma separated) to allow the User to access. If you provided access to "all sites" in the site_access parameter, don't include this parameter in your request.
security_profile The Name of the Security Profile for this user (security_profile__sys.name__v)
license_type Optional: The user’s license type. If omitted, the default value is full__v.
federated_id Optional: A Federated ID for the user. Vault uses the Federated ID to map enterprise user names to Vault user names for SSO.
security_policy Optional: The user’s security policy. If omitted, the default value is basic__v.

Response Details

On SUCCESS, Vault creates the user's Vault account and assigns the user to the specified Study.

Errors

Example: Failed Authentication

{
    "responseStatus" : "FAILURE",
    "errors" : [
        {
            "type" : "NO_PASSWORD_PROVIDED",
            "message" : "No password was provided for the login call."
        }
    ],
    "errorType" : "AUTHENTICATION_FAILED"
}

Example: Down for Maintenance

{
    "responseStatus": "FAILURE",
    "responseMessage": "Authentication failed for user [chunter@verteopharma.com]",
    "errors": [
        {
            "type": "DOWN_FOR_MAINTENANCE",
            "message": "Vault is currently down for maintenance"
        }
    ],
    "errorType": "AUTHENTICATION_FAILED"
}


The response of every API call includes a field called responseStatus. Possible values are:

For a responseStatus other than SUCCESS, users can inspect the errors field in the response. Each error includes the following fields:

We recommend basing your logic on the responseStatus field and error types, not on the HTTP response status codes.

Error Types

Type Description
UNEXPECTED_ERROR General error catch-all when there is no specific error, or an unidentified error.
MALFORMED_URL The specified resource cannot be found.
METHOD_NOT_SUPPORTED The specified resource does not support the (POST, PUT, GET, DELETE) method. Or, the API request is not supported by this version of API.
INACTIVE_USER User is inactive or not found.
NO_PASSWORD_PROVIDED No password was provided for the login call.
USERNAME_OR_PASSWORD_INCORRECT Authentication failed because an invalid username or password was provided.
USER_LOCKED_OUT The user is locked out. Learn more about user account lockout in Vault Help.
PASSWORD_CHANGE_REQUIRED Password change required.
INVALID_SESSION_ID Invalid session ID provided.
DOWN_FOR_MAINTENANCE The vault is currently down for maintenance.
PARAMETER_REQUIRED Missing required parameters in the API call.
INVALID_DATA Invalid data provided in the API call.
INSUFFICIENT_ACCESS User does not have sufficient privileges to perform the action. Additionally, the /actions endpoints may return this error in cases where the user attempts to access a resource which does not exist.
OPERATION_NOT_ALLOWED Certain rules that must be met to perform this operation have not been met.
ATTRIBUTE_NOT_SUPPORTED The specified resource does not recognize provided attributes.
INVALID_FILTER Provided a non-existent filter to Retrieve Documents.
INCORRECT_QUERY_SYNTAX_ERROR Query string used with VQL has an incorrect query syntax.
RACE_CONDITION A rare condition where the same record is being simultaneously updated by another API call.
EXCEEDS_FILE_MAX_SIZE The size of uploaded file exceeds the maximum size allowed (4 GB).
API_LIMIT_EXCEEDED Vault limits the number of API calls that can be made every 5 minutes and every 24 hours. Additionally, the Job Status endpoint can only be requested once every 10 seconds. When either of these limits are reached, this error message is returned and no further calls will be processed until the next 5 minute or 24 hour period begins. Learn more about API Limits.
CONFIGURATION_MODE_ENABLED Non-Admins cannot access a vault in Configuration Mode. Learn more about Configuration Mode in Vault Help.
SDK_ERROR An error caused by the Vault Java SDK. This error may also include a custom subtype. For more information about this error, check the Debug Log.
shell