About the Veeva OpenData API

The Veeva OpenData API provides programmatic access to Veeva OpenData information and functionality using a simple, powerful, and secure application programming interface.

The API enables you to leverage the power of Veeva OpenData directly in an application or website. The API provides methods to read and submit petitions to apply changes to Veeva OpenData securely, so your application can retrieve and send requests to create, and update information.

The API can be used to develop custom applications and integrations, or other complex tools such as data loaders or schema visualization.

Overview

The Veeva OpenData API is a REST–based API available in JSON format. The guiding principles of the API are:

• Learnable – The API aims to be intuitive and easy to learn. It should incorporate elements of REST, making access to these actions consistent and intuitive.
• Secure – Access through the API will always be authenticated over SSL and in compliance with the access permissions of the authenticated user.
• Efficient – The API strives to be efficient in how it processes requests. Large amount of bits will need to be processed and the API attempts to minimize any inefficiencies.
• Alignment – The API leverages the same underlying code as the UI. This means that new versions of the API will reflect new capabilities introduced in new versions and business logic will be consistent.

Getting Started

The following sections discuss some of the basic concepts and steps you'll need to structure and make requests using the Veeva OpenData API.

To simplify the process, click the Run in Postman button to import the collection and environment to your own Postman workspace. Be sure to update the environment variables with your Veeva OpenData credentials.

The button provides a static link to the collection. To ensure you're accessing the most up to date features, you should import the collection after each release.

Authentication

To make API calls against Veeva OpenData, you need a Veeva OpenData user account defined with API access. Once you have this, you can authenticate to get a session ID.

Network User Account and Permissions

Your user permissions and data visibility profile grant the following permissions:

• Access: This permission is set in your user profile, and controls general access to the API and allows you to successfully make API calls.
• Permissions: Data visibility profiles include an option to hide mail-only addresses when accessing records from the search API.

If you do not have API access, your authentication request will succeed, but any other API calls you make will return the following error:

INSUFFICIENT_ACCESS: User does not have sufficient privileges to perform the action.

If you do not have API access, contact your Veeva OpenData administrator to modify your user profile.

Structuring the Endpoint

Every endpoint for API calls includes the following variables.

• server is the domain name of the Veeva OpenData instance. This value is opendataexplorer.veeva.com for all Veeva OpenData calls.
• version is the API version. This value is v1.0 for all Veeva OpenData calls.

Get a Session ID

Your first API call will be an authentication request, which provides your session ID for other API calls. To do this, call the auth endpoint.

The auth endpoint /api/opendata/v1.0/auth expects the following POST data in the body of the request: username and password.

Request

curl -X POST https://opendataexplorer.veeva.com/api/opendata/v1.0/auth \
	-H "Content-Type: application/x-www-form-urlencoded" \
	-H "Accept: application/json" \
	-d "username={username}&password={password}"

This call returns a JSON response that contains the session ID.

Response

{
  "responseStatus": "SUCCESS",
  "sessionId": "14435B027716F5FD4260F6ADB1730A5747CD3A19FA3901D125498B7 \
EFD4A7244B5BF8D032BA9A31EA091A5B030CF32601455B48CCAC30654FC48D7E06B0696F89 \
16A8F668AC942EE13BFD9734238F7A5",
  "userId": 2000049,
  "openDataId": "3",
  "openDataIds": [
    {
      "id": 3,
      "name": "vod",
      "url": "https://opendataexplorer.veeva.com/api/opendata"
    }
  ]
}

Retrieve data

Now that you have a session ID, you can use it to make other Veeva OpenData API calls. For example, if you want to view the objects available in Veeva OpenData, you would use the metadata API.

Assign the session ID to the header parameter Authorization.

Request

curl -X GET -H "Authorization: 14435B027716F5FD4260F6ADB1730A5747CD \
3A19FA3901D125498B7EFD4A7244B5BF8D032BA9A31EA091A5B030CF32601455 \
B48CCAC30654FC48D7E06B0696F8916A8F668AC942EE13BFD9734238F7A5" \
"https://opendataexplorer.veeva.com/api/opendata/v1.0/metadata/objectTypes"

If your request is successful, the response includes the metadata you requested along with a SUCCESS message to indicate its status.

Response

{
   "objectTypes" : [
      {
         "status" : "ACTIVE",
         "description" : "Health Care Professional",
         "type" : "object",
         "customer_defined" : false,
         "name" : "HCP"
      },
      {
         "type" : "object",
         "description" : "Health Care Organization",
         "status" : "ACTIVE",
         "name" : "HCO",
         "customer_defined" : false
      },
      {
         "name" : "ADDRESS",
         "customer_defined" : false,
         "type" : "sub-object",
         "description" : "Address",
         "status" : "ACTIVE"
      },
      {
         "customer_defined" : false,
         "name" : "LICENSE",
         "description" : "License",
         "status" : "ACTIVE",
         "type" : "sub-object"
      },
      {
         "status" : "ACTIVE",
         "description" : "Parent HCO",
         "type" : "relationship",
         "customer_defined" : false,
         "name" : "PARENTHCO"
      }
   ],
   "responseStatus" : "SUCCESS"
}

Now that you've successfully retrieved data from Veeva OpenData, you can try making calls with the other Veeva OpenData API using your session ID and parameters required by each API.