MyVeeva External APIs

The Veeva eCOA APIs help integrate participant data from external systems into Veeva eCOA. Pulling in the data from external systems prevents errors that may be caused by manually reentering data.

Before You Begin

All operations in the Participant API require authentication. Before you attempt to call any of the APIs described, work with your project team to ensure that the Veeva eCOA system is properly configured to accept your calls.

Also work with your project team to obtain an external system key and secret for the system to be integrated. These credentials are issued by Veeva personnel and should be closely protected.

Depending on the architecture of the integrating system, the system key may represent a study, a customer, or some other business entity. Your project team will help you decide on a name for your external system key.

The project team will need the following information to create your study mapping and issue your external system key and secret:

• IP address
• Study ID for the study in the external system

Authentication

Authenticate your account using the following method: HTTP Authentication, scheme: bearer

Discovery

The Discovery API enables you to determine the regional domain where the study site exists in Veeva eCOA. The URL returned in the response will be used as the base URL for the next two calls.

Note that some studies may have sites in only one geographic region. If this is the case, you may be able to skip this discovery call. Your project team will help you determine whether this is the case.

Discover Study Site

Request

# You can also use wget
curl -X POST https://sponsors.myveeva.com/services/v24.3/discover-study-site \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST services/{version}/discover-study-site

Identify the regional URL to use for subsequent calls.

Note that the base URL for this API is https://sponsors.myveeva.com

Example JSON Request Body

{
  "externalSystemId": "mv-ext-NT-VeevaPharm-RTSM",
  "externalStudySiteId": "1005",
  "externalSponsorStudyId": "5c8684a9-f2ec-4c69-b4bc-16cd05450fc2"
}

Parameters

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "",
  "errorType": null,
  "errors": [

  ],
  "data": [
    {
      "region": "https://sponsors-us.myveeva.com/"
    }
  ]
}

Responses

Authorization

Authorize External

Request

# You can also use wget
curl -X POST https://sponsors-us.myveeva.com/auth/v24.3/authorize \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json'

POST auth/{version}/authorize

Validate and authorize external requests to access the Veeva eCOA API.

Note that the base URL is the region URL that was returned by the Discovery API.

Example JSON Request Body

{
  "externalSystemId": "mv-ext-NT-VeevaPharm-RTSM",
  "externalSystemSecret": "your-secret",
  "tenantId": "NT-VeevaPharm-RTSM"
}

Parameters

Response

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODY5MCIsInVzZXJuYW1lIjoiSm9obiIsInJvbGUiOiJhZG1pbiIsImlhdCI6MTUxNjIzOTU0NywiZXhwIjoxNTE2MjQ1NTQ3fQ.r95Xz9056186h8530X93s0-86g_2-000000000000000000000000000000000000000000000000"
}

Responses

Participants

The Veeva eCOA Participant API allows integrating systems to read and write participant data in Veeva eCOA.

The most common operation is the creation of participants. When you use the Veeva eCOA API to create participants, their participant IDs are controlled by the system that first created the participants, such as an RTSM application. Site users are prevented from manually updating the participant IDs in Veeva eCOA. If the participant ID is updated in the source system, the update should be pushed to Veeva eCOA using the API.

Get Participant

Request

# You can also use wget
curl -X GET https://sponsors-us.myveeva.com/services/v24.3/sponsor/5c8684a9-f2ec-4c69-b4bc-16cd05450fc2/site/1005/participant?internalId=925c6db2-b07b-49fe-8f92-0f6a2cb405a6 \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODY5MCIsInVzZXJuYW1lIjoiSm9obiIsInJvbGUiOiJhZG1pbiIsImlhdCI6MTUxNjIzOTU0NywiZXhwIjoxNTE2MjQ1NTQ3fQ.r95Xz9056186h8530X93s0-86g_2-000000000000000000000000000000000000000000000000

GET services/{version}/sponsor/{sponsorStudyId}/site/{siteNum}/participant?internalId={internalId}

Retrieve participant information from Veeva eCOA.

Note that the base URL is the region URL that was returned by the Discovery API.

Parameters

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "",
  "errorType": null,
  "errors": [

  ],
  "data": [
    {
      "myVeevaParticipantId": "c8e85718-7c59-4ef6-8faa-45154ccdb58b",
      "participantId": "1005-003"
    }
  ]
}

Responses

Create or Update Participant

Request

# You can also use wget
curl -X POST https://sponsors-us.myveeva.com/services/v24.3/sponsor/5c8684a9-f2ec-4c69-b4bc-16cd05450fc2/site/1005/participant \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODY5MCIsInVzZXJuYW1lIjoiSm9obiIsInJvbGUiOiJhZG1pbiIsImlhdCI6MTUxNjIzOTU0NywiZXhwIjoxNTE2MjQ1NTQ3fQ.r95Xz9056186h8530X93s0-86g_2-000000000000000000000000000000000000000000000000

POST services/{version}/sponsor/{sponsorStudyId}/site/{siteNum}/participant

Creates and updates participant IDs in Veeva eCOA.

Note that the base URL is the region URL that was returned by the Discovery API.

Example JSON Request Body

{
  "participantId": "1005-003",
  "internalId": "925c6db2-b07b-49fe-8f92-0f6a2cb405a6"
}

Parameters

Response

{
  "responseStatus": "SUCCESS",
  "responseMessage": "",
  "errorType": null,
  "errors": [

  ],
  "data": [
    "c8e85718-7c59-4ef6-8faa-45154ccdb58b"
  ]
}

Responses

Schemas

DiscoverStudySiteRequest

{
  "externalSponsorStudyId": "5c8684a9-f2ec-4c69-b4bc-16cd05450fc2",
  "externalStudySiteId": "1005",
  "externalSystemId": "mv-ext-NT-VeevaPharm-RTSM"
}

Properties

DiscoverStudySiteResponse

{
  "responseStatus": "SUCCESS",
  "responseMessage": "",
  "errorType": null,
  "errors": [

  ],
  "data": [
    {
      "region": "https://sponsors-us.myveeva.com/"
    }
  ]
}

Properties

Enumerated Values

Error

{
  "code": "ID-0001",
  "message": "Invalid Data"
}

Properties

StudySiteData

{
  "region": "https://sponsors-us.myveeva.com/"
}

Properties

AuthorizeExternalRequest

{
  "externalSystemId": "mv-ext-NT-VeevaPharm-RTSM",
  "externalSystemSecret": "your-secret",
  "tenantId": "NT-VeevaPharm-RTSM"
}

Properties

AuthorizeExternalResponse

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODY5MCIsInVzZXJuYW1lIjoiSm9obiIsInJvbGUiOiJhZG1pbiIsImlhdCI6MTUxNjIzOTU0NywiZXhwIjoxNTE2MjQ1NTQ3fQ.r95Xz9056186h8530X93s0-86g_2-000000000000000000000000000000000000000000000000"
}

Properties

ParticipantExternalGetResponse

{
  "responseStatus": "SUCCESS",
  "responseMessage": "",
  "errorType": null,
  "errors": [

  ],
  "data": [
    {
      "myVeevaParticipantId": "c8e85718-7c59-4ef6-8faa-45154ccdb58b",
      "participantId": "101-0010"
    }
  ]
}

Properties

Enumerated Values

ParticipantData

{
  "myVeevaParticipantId": "c8e85718-7c59-4ef6-8faa-45154ccdb58b",
  "participantId": "1005-003"
}

Properties

ParticipantExternalPostRequest

{
  "participantId": "1005-003",
  "internalId": "925c6db2-b07b-49fe-8f92-0f6a2cb405a6"
}

Properties

ParticipantExternalPostResponse

{
  "responseStatus": "SUCCESS",
  "responseMessage": "",
  "errorType": null,
  "errors": [

  ],
  "data": [
    "c8e85718-7c59-4ef6-8faa-45154ccdb58b"
  ]
}

Properties

Enumerated Values

Errors

Failure Response

{
    "responseStatus": "FAILURE",
    "responseMessage": "NOT_FOUND: Mapping info not found",
    "errorType": "NOT_FOUND",
    "errors": [
        {
            "code": "NF-0002",
            "message": "External system ID or external sponsor study ID not found"
        }
    ],
    "data": []
}

The following HTTP response status codes are possible:

If the request results in a 200 the response will includes a field called responseStatus. Possible values are:

• SUCCESS - The API request was successfully processed.
• FAILURE - The API request could not be processed because of user error.
• EXCEPTION - The API request could not be processed because of system error.

A responseStatus other than SUCCESS will include an errorType field. Possible values are:

• UNEXPECTED_ERROR
• INVALID_DATA
• NOT_FOUND
• INVALID_CONFIG

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

• code - Possible codes per errorType are listed below.
• message - The message accompanying each error type and code. When available, the error message includes the specific reason. These messages are subject to change and are not contractual parts for error handling. Developers should consider error messages for debugging and troubleshooting purposes only and should not implement application logic which relies on specific error strings or formatting.

Error Types

UNEXPECTED_ERROR

INVALID_DATA

NOT_FOUND

INVALID_CONFIG