Authenticate

This API enables user authentication. User credentials are passed using POST data; for example, with the -d parameter in a curl request.

You can only authenticate with a Veeva OpenData user name defined by an administrator.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/auth

POST data

username

The Veeva OpenData user ID; for example, john.smith@opendataexplorer.veeva.com.

password

The Veeva OpenData password for the user ID.

Response

responseStatus

The status of the response.

sessionId

The session ID for subsequent API calls. This should be set with an authorization header.

userId

An ID number for the authenticated user.

openDataId

An ID number for the Veeva OpenData instance most recently accessed by the authenticated user.

openDataIds

Details about the Veeva OpenData instance the user is accessing:

• id - An ID number for the authenticated user.
• name - The name of the Veeva OpenData instance.
• url - The Veeva OpenData URL used for subsequent API calls.

Create a change request

This API enables you to create a change request to add or update an HCP or HCO and related entities (including addresses, licenses, or parent HCOs).

https://opendataexplorer.veeva.com/api/opendata/v1.0/change_request

This API takes no parameters.

POST data

metadata

Details about the request being made. The details are saved in the entity history if the change is accepted (an array of fields within itself):

• creator - the name of the user that generated the change request
• note - details about the change request
• source - additional information about the source of the change request

entity_type

The entity type of the change request (HCP or HCO).

vid_key

The external HCP or HCO vid_key supplied by the client and used for change request updates. Ignored if provided for add requests.

entity

Details of the changes, one per field, for the entity provided:

• field - The Veeva OpenData API name of the HCP or HCO field.
• value - The new value of the HCP or HCO field.
• addresses__v - An array of change requests for addresses, one per address, for the entity provided:
  • vid_key - the address vid_key supplied by the client
  • field - The Veeva OpenData API name of the HCP or HCO Address field
  • value - the new value of the HCP or HCO Address field
• licenses__v - An array of change requests for licenses, one per license, for the entity provided:
  • vid_key - the license vid_key supplied by the client
  • address_vid_key - the address vid_key to which the license is related, supplied by the client
  • address_index - the address index within the addresses__v object. Can be used when vid_key is not available. (The index is zero-based.)
  • field - The Veeva OpenData API name of the HCP or HCO License field
  • value - the new value of the HCP or HCO License field
• parent_hcos__v - An array of change requests for parent HCOs, one per parent HCO, for the entity provided:
  • vid_key - the parent HCO vid_key supplied by the client
  • parent_hco_vid_key - the actual HCO vid_key of the parent, supplied by the client
  • field - The Veeva OpenData API name of the HCP or HCO ParentHCO field
  • value - the new value of the HCP or HCO ParentHCO field

Response

responseStatus

The status of the response from Veeva OpenData.

change_request_id

The ID of the change request generated in Veeva OpenData.

Notes

• Addresses, licenses, and parent HCOs are an array of fields within themselves. There can be multiple addresses, licenses, or parent HCOs created for the same entity (HCP or HCO) at the same time.

Retrieve Change Request

This API enables you to retrieve response information for change requests.

Your API calls and users will only be able to access and view change requests created for your organization. The visibility model of change requests is private and visible only to the user that created them.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/change_requests/{change_request_ids}

• change_request_ids - A comma separated list of change request IDs.

Parameters

status

Retrieve change requests of a specific status from the IDs provided.

includeEntity

Return the full entity or entities related to the requested change requests. An entity for a change request is determined from the entity identifier (vid__v) of the change request.

sinceDate

Include change requests modified after the specified date (exclusive). This value is specified in epoch time in milliseconds.

toDate

Include change requests modified on or before the specified date (inclusive). This value is specified in epoch time in milliseconds.

Response

responseStatus

The status of the response.

change_requests

resolution_notes - An array of comments containing notes added during change request processing.

• comment - Notes added by the Veeva OpenData user.
• fields - An array of fields for which the comments were made.
• created_date - The date the resolution notes were added by the Veeva OpenData user.
• code - The code or identifier of the note. Null if the resolution note is not defined.

metadata - Details about the request. These details are stored in the entity history if the change is accepted.

• creator - The name of the user that generated the request.
• note - Details about the request.
• source - Additional information about the source of the request.

entity - Details of the response changes, one per field, for the entity provided.

• field - The Veeva OpenData API name of the HCP or HCO field.
  • change_requested - The value of the requested change.
  • final_value - The new value of the field.
  • result - See the Field Results table.
• addresses__v - An array of address response changes, one per address, for the entity provided. See the Child Object Attributes table for more information.
• licenses__v - An array of license response changes, one per license, for the entity provided. See the Child Object Attributes table for more information.
• parent_hcos__v - An array of parent HCO response changes, one per parent HCO, for the entity provided. See the Child Object Attributes table for more information.

errors - Errors in retrieving the requested change requests.

parent_task_ids - List of parent task IDs.

result__v - The change request result.

status__v - The change request status.

• CHANGE_NEW - A new task has been received but not run yet.
• CHANGE_PENDINGREVIEW - All changes for this request are pending approval.
• CHANGE_INQUEUE - The change was made on an unverified object and is pending processing of the parent task.
• CHANGE_PARTIALLYPROCESSED - At least one field change was accepted.
• CHANGE_PROCESSED - The task was processed and a result issued.
• CHANGE_CANCELLED - The task was cancelled.

completed_date - The completed date for the change request. If the change request is not completed, this value is empty. The date format uses the ISO8601 standard.

taskCountry - The country code of the entity.

created_date - The creation date of the change request. The date uses the ISO8601 standard.

entity_type - The entity type of the change request: HCP or HCO.

vid_key - The external HCP or HCO vid_key supplied in the original change request.

original_task_type - The original change request type.

change_request_id - The change request ID.

vid__v - The ID of the entity: HCP or HCO.

task_type - The final change request type as an add request. Could become a change request.

The following may be displayed at the field level within a change request.

Field results

CHANGE_ACCEPTED

The change for this field has been accepted.

CHANGE_REJECTED

The change for this field has been rejected.

CHANGE_MODIFIED

The change for this field has been accepted with differences .

CHANGE_ALREADYAPPLIED

The change for this field has already been applied.

CHANGE_ADDED

The change for this field was added to the change request after creation.

These do not reflect the result of the change request itself; refer to result__v for the request result.

Child object attributes

vid_key

The external vid_key supplied in the original change request.

vid__v

The Veeva ID of the entity.

field

The Veeva OpenData API name of the entity's field for the HCP or HCO.

• change_requested - The value of the requested change.
• final_value - The new value of the field.
• result -
  • CHANGE_ACCEPTED - The change for this field has been accepted.
  • CHANGE_REJECTED - The change for this field has been rejected.
  • CHANGE_MODIFIED - The change for this field has been accepted with differences .
  • CHANGE_ALREADYAPPLIED - The change for this field has already been applied.
  • CHANGE_ADDED - The change for this field was added to the change request after creation.

Notes

• Addresses, licenses, and parent HCOs are an array of fields within themselves. There could be multiple addresses or licenses responses for the same HCP or HCO matching the change request submitted originally.
• The overall result of the change request will be null until all the changes requested are reviewed and the status is PROCESSED or CANCELLED.

Batch retrieve change request

This API enables you to obtain information about multiple change requests through the API.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/change_requests/batch

This API takes no parameters.

POST data

change_requests

An array of change request IDs.

• change_request_id - The ID of the change request generated in Veeva OpenData.

status_codes

A list of status codes.

• CHANGE_NEW - The change request has been received but not run yet.
• CHANGE_PENDINGREVIEW - The change request was received and processed but is pending review by data stewards.
• CHANGE_INQUEUE - The change request is made on an unverified object and is pending parent task processing.
• CHANGE_PARTIALLYPROCESSED - The change request was partially processed by data stewards.
• CHANGE_PROCESSED - The change request was processed and a result issued.
• CHANGE_CANCELLED - The change request was cancelled.

includeEntity

Return the full entity or entities related to the requested change requests. An entity for a change request is determined from the entity identifier (vid__v) of the change request.

sinceDate

Include change requests modified after the specified date (exclusive). This value is specified in epoch time in milliseconds.

toDate

Include change requests modified on or before the specified date (inclusive). This value is specified in epoch time in milliseconds.

Response

responseStatus

The status of the response.

change_requests

metadata - Details about the request. These details are stored in the entity history if the change is accepted.

• creator - The name of the user that generated the request.
• note - Details about the request.
• source - Additional information about the source of the request.

entity - Details of the response changes, one per field, for the entity provided.

• field - The Veeva OpenData API name of the HCP or HCO field.
  • change_requested - The value of the requested change.
  • final_value - The new value of the field.
  • result - See the Field Results table.
• addresses__v - An array of address response changes, one per address, for the entity provided. See the Child Object Attributes table for more information.
• licenses__v - An array of license response changes, one per license, for the entity provided. See the Child Object Attributes table for more information.
• parent_hcos__v - An array of parent HCO response changes, one per parent HCO, for the entity provided. See the Child Object Attributes table for more information.

errors - Errors in retrieving the requested change requests.

parent_task_ids - List of parent task IDs.

result__v - The change request result.

status__v - The change request status.

completed_date - The completed date for the change request. If the change request is not completed, this value is empty. The date format uses the ISO8601 standard.

taskCountry - The country code of the entity.

created_date - The creation date of the change request. The date uses the ISO8601 standard.

entity_type - The entity type of the change request: HCP or HCO.

vid_key - The external HCP or HCO vid_key supplied by the client in the original change request.

original_task_type - The original change request type.

change_request_id - The change request ID.

vid__v - The ID of the entity: HCP or HCO.

task_type - The final change request type as an add request. Could become a change request.

entities

An array of entities associated with the change requests. Each entity is related to a change request through the vid__v field.

The following may be displayed at the field level within a change request.

Field results

CHANGE_ACCEPTED

The change for this field has been accepted.

CHANGE_REJECTED

The change for this field has been rejected.

CHANGE_MODIFIED

The change for this field has been accepted with differences .

CHANGE_ALREADYAPPLIED

The change for this field has already been applied.

CHANGE_ADDED

The change for this field was added to the change request after creation.

These do not reflect the result of the change request itself; refer to result__v for the request result.

Child object attributes

vid_key

The external vid_key supplied in the original change request.

vid__v

The Veeva ID of the entity.

field

The Veeva OpenData API name of the entity's field for the HCP or HCO.

• change_requested - The value of the requested change.
• final_value - The new value of the field.
• result -
  • CHANGE_ACCEPTED - The change for this field has been accepted.
  • CHANGE_REJECTED - The change for this field has been rejected.
  • CHANGE_MODIFIED - The change for this field has been accepted with differences .
  • CHANGE_ALREADYAPPLIED - The change for this field has already been applied.
  • CHANGE_ADDED - The change for this field was added to the change request after creation.

Change Request Search

This API enables you to retrieve all change requests that match a specified search criteria.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/change_request/search

Parameters

q

The text for the search query. Uses the following fields:

• subject
• description
• summary
• task_type
• task_data
• comment

offset

The first record to retrieve from the offset specified. The default value is 0.

limit

The number to limit the results returned. The default is 10; the maximum is 100.

sort

The attribute to sort results by; for example, task_type .

sortOrder

The sort order: asc for ascending or desc for descending.

filters

Filters for refining the results.. See the Search Filters table for more information.

Search filters

task_type

The change request type.

• ADD_REQUEST - An add request submitted on an existing record.
• CHANGE_REQUEST - A change request for a new record.

task_status

The status of the task.

• NEW - A new task has been received but not run yet.
• IN_PROGRESS - A task is pending approval by a data steward.
• CLOSED - A task has been closed.

task_country

The country to which the task belongs.

task_state

The state of the task.

• NEW - A new task has been received but not run yet.
• PENDINGREVIEW - A task was received and processed but is pending review by data stewards.
• CANCELLED - The task was cancelled.
• FAILED - The task failed due to an unexpected error.
• PROCESSED - The task was processed and a result issued.
• PROCESSING - The task is being processed.

resolution

The resolution for the task.

• CHANGE_PENDING - All changes for this request are pending approval.
• CHANGE_ACCEPTED - All changes for this request have been accepted.
• CHANGE_REJECTED - All changes for this request were rejected.
• CHANGE_PARTIAL - At least one field change was accepted.

created_at

The date the task was created .

created_by

The ID of the user that generated the change request.

creator

The user name of the user that generated the change request.

completed_at

The completed date of the task. Is empty if the change request is not completed. Date format is ISO8601 standard.

completed_by

The ID of the user that approved the task.

open

The task is open: True or False.

entity_type

The entity type for the task: HCP or HCO.

entity_id

The Veeva entity ID.

owner

The ID of the owner of the task.

Filter values passed in from a GET request need to be URL-encoded.

Response

responseStatus

The status of the response.

totalCount

The total number of search results, regardless of the set limit.

offset

The first record to retrieve from the offset specified. The default value is 0.

limit

The number provided to limit the search results.

change_requests

metadata - Details about the request. These details are stored in the entity history if the change is accepted.

• creator - The name of the user that generated the request.
• note - Details about the request.
• source - Additional information about the source of the request.

entity - Details of the response changes, one per field, for the entity provided.

• field - The Veeva OpenData API name of the HCP or HCO field.
  • change_requested - The value of the requested change.
  • final_value - The new value of the field.
  • result - See the Field Results table.
• addresses__v - An array of address response changes, one per address, for the entity provided. See the Child Object Attributes table for more information.
• licenses__v - An array of license response changes, one per license, for the entity provided. See the Child Object Attributes table for more information.
• parent_hcos__v - An array of parent HCO response changes, one per parent HCO, for the entity provided. See the Child Object Attributes table for more information.

taskCountry - The country code of the entity.

task_type - The final change request type as an add request. Could become a change request.

original_task_type - The original change request type.

change_request_id - The change request ID.

status__v - The change request status.

• CHANGE_NEW - A new task has been received but not run yet.
• CHANGE_PENDINGREVIEW - All changes for this request are pending approval.
• CHANGE_PARTIALLYPROCESSED - At least one field change was accepted.
• CHANGE_PROCESSED - The task was processed and a result issued.
• CHANGE_CANCELLED - The task was cancelled.

result__v - The change request result.

• CHANGE_ACCEPTED - All changes for this request have been accepted.
• CHANGE_REJECTED - All changes for this request were rejected.
• CHANGE_PARTIAL - At least one field change was accepted.

entity_type - The entity type of the change request: HCP or HCO.

vid_key - The external HCP or HCO vid_key in the original change request.

resolution_notes - An array of comments containing notes added during change request processing.

• comment - Notes added by the Veeva OpenData user.
• fields - An array of fields for which the comments were made.
• created_date - The date the resolution notes were added by the Veeva OpenData user.

created_date - The creation date of the change request. The date uses the ISO8601 standard.

completed_date - The completed date for the change request. If the change request is not completed, this value is empty. The date format uses the ISO8601 standard.

errors - Errors in retrieving the requested change requests.

The following may be displayed at the field level within a change request.

Field results

CHANGE_ACCEPTED

The change for this field has been accepted.

CHANGE_REJECTED

The change for this field has been rejected.

CHANGE_MODIFIED

The change for this field has been accepted with differences .

CHANGE_ALREADYAPPLIED

The change for this field has already been applied.

CHANGE_ADDED

The change for this field was added to the change request after creation.

These do not reflect the result of the change request itself; refer to result__v for the request result.

Child object attributes

vid_key

The external vid_key supplied in the original change request.

vid__v

The Veeva ID of the entity.

field

The Veeva OpenData API name of the entity's field for the HCP or HCO.

• change_requested - The value of the requested change.
• final_value - The new value of the field.
• result -
  • CHANGE_ACCEPTED - The change for this field has been accepted.
  • CHANGE_REJECTED - The change for this field has been rejected.
  • CHANGE_MODIFIED - The change for this field has been accepted with differences .
  • CHANGE_ALREADYAPPLIED - The change for this field has already been applied.
  • CHANGE_ADDED - The change for this field was added to the change request after creation.

Retrieve entity

This API enables you to obtain information on any entity without identifying the specific entity type. It is only used to retrieve information using the GET method.

You can only retrieve entries for which you have access permission.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/entity/{vid_key}

• vid_key is the key of the entity to retrieve

Optional parameters

enrichedResults

Specifies whether or not to display labels for reference type fields in the results.

resultLanguage

Specifies the language to use if the enriched results option is enabled. Uses the IETF BCP 47 language standard.

returnHashtagsForType

Return hashtags for the requested type using the following values:

• NETWORK - Display predefined Network hashtags.
• ALL - Display Network-defined and custom hashtags.
• NONE - Do not display hashtags.

Response

entities

An array of fields and values for each entity.

• entityId - The entity ID.
• entityType - The entity type.
• metaData - Included for structure only; not applicable for this call.
• entity - The fields and corresponding values for the entity.

responseStatus

The status of the response.

hashtags

The list of hashtags available to the authenticated API user:

• name - the hashtag name.
• color - the hashtag color.
• tooltip - the tooltip of the hashtag.
• tooltipLabel - the field value label of the hashtag.
• tooltipValue - the field value of the hashtag.
• tooltipHasOtherValue - Returns True if the tooltip has more than three field values.

Enriched results

When the enrichedResults parameter is used, the following data is returned:

• Reference value labels - _value__u attribute helper
• Parent HCO corporate name - parent_hco_corp_name__v
• Parent HCO address - parenthco_address__u
• Parent HCO record state - parenthco_record_state__u
• Parent HCO status - parenthco_status__u
• Address Network entity ID (VID) for licenses - address_vid__v__u
• Sub-object sorting - Network sorting logic for sub-objects (for example, active objects are listed before inactive objects).

The helper attributes with the __u suffix denote values that are typically displayed in the Network UI.

Notes

• Following a retrieve entity call, Veeva Opendata returns all resource information.
• The information returned does not include attributes with NULL values.

Batch retrieve entities

This API enables you to retrieve entity details directly from Veeva OpenData.

The entities you can retrieve include HCPs and HCOs, and details are returned for all corresponding child entities: addresses, licenses, and parent HCOs.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/entities/batch

This API takes no parameters.

POST data

entities

An array of fields and values for each entity.

• vid_key - The HCP or HCO vid_key.

enrichedResults

Specifies whether or not to display labels for reference type fields in the results.

resultLanguage

Specifies the language to use if the enriched results option is enabled. Uses the IETF BCP 47 language standard.

Response

responseStatus

The status of the response in Veeva OpenData.

errors

An array of errors.

• type - The error type.
• message - A detailed message for the error type. This message is subject to change and is not contractual for error handling.

entities

An array of fields and values for each entity.

• entityType - The entity type.
• metaData - Included for structure only; not applicable for this call.
• entity - The fields and corresponding values for the entity.

Enriched results

When the enrichedResults parameter is used, the following data is returned:

• Reference value labels - _value__u attribute helper
• Parent HCO corporate name - parent_hco_corp_name__v
• Parent HCO address - parenthco_address__u
• Parent HCO record state - parenthco_record_state__u
• Parent HCO status - parenthco_status__u
• Address Network entity ID (VID) for licenses - address_vid__v__u
• Sub-object sorting - Network sorting logic for sub-objects (for example, active objects are listed before inactive objects).

The helper attributes with the __u suffix denote values that are typically displayed in the Network UI.

Notes

• responseStatus returns a failure if standard errors occur.
• responseStatus returns PARTIAL_SUCCESS if:
  • vid_key does not represent an existing entity.
  • the entity specified by vid_key is not an HCP or HCO.
• Batch API calls are limited to 500 operations per call. An attempt to submit more operations will results in a failure of all operations in the call.

Retrieve available API versions

This enables you to retrieve summary information about each API version available in Veeva OpenData.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata

This API takes no parameters.

Response

responseStatus

The status of the response from Veeva OpenData.

values

An array of values containing each available version and the version-specific API URL information.

Retrieve object types metadata

This API enables you to retrieve the list of object types available in Veeva OpenData.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/metadata/objectTypes

This API takes no parameters.

Response

responseStatus

The status of the response from Veeva OpenData.

objectTypes

An array of attribute information objects:

• name - the entity name (HCP, HCO, ADDRESS, LICENSE, PARENTHCO)
• description - Localized text description of the entity
• status - returns all types regardless of the status
• customerDefined -False.
• type - *object*, *sub-object*, or *relationship*

Retrieve fields metadata

This API enables you to retrieve detailed or summary information about the fields on each entity in Veeva OpenData.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/metadata/fields

Optional parameters

objectTypes

Filter fields to those applicable for certain object types:

• Default - do not filter by object type.
• Values - comma-separated list of object types from: HCP, HCO, LICENSE, ADDRESS, PARENTHCO

details

Include field details:

• Default - Only returns field IDs
• Value - full (include field details in the results)

labels

Include labels in field details:

• Default - Include labels
• Values - True or empty (include labels in the field details in the results)

fieldGroup

Filter fields to those applicable for a certain field group:

• Default - do not filter by field group
• Values - The desired field group, for example, credentials, medical_degree, and so on

country

Filter fields by country visibility:

• Default - do not filter by country
• Values - The desired country value, for example, US, GB, FR. The country must be visible to the authenticated user.

countries

Filter fields by country visibility:

• Default - do not filter by country
• Values - The desired country values, for example, US, GB, FR. The countries must be visible to the authenticated user.

Response

responseStatus

The status of the response from.

attributes

An array attribute of information objects:

• field_id - The ID of the field; for example, first_name__v.
• type:
  • dataType - The type object, containing two attributes:
    • VEEVAID - the Veeva ID
    • STRING - text
    • YEAR - year value (no month or day)
    • DATE - date (no time)
    • DATETIME - date + Time (timestamp)
    • NUMBER - integer number
    • DOUBLE - floating point number
    • BOOLEAN - True or False value
    • REFERENCE - reference code
    • SET - a collection of values
    • ALTERNATEKEY - an alternate key
  • discriminator - For reference data type, include the reference data type name

labels

Set of language to description pairs (unless labels is not equal to True or empty).

customerOwned

False.

description

Non-localized text description of field.

readOnly

True if this is a read-only attribute, False otherwise.

ownerOnlyEdit

Not relevant for Veeva OpenData.

status

One of ACTIVE, DELETED, or DEACTIVATED.

fieldGroup

Either null or the name of the group for this attribute.

fieldSet

Either null or the name of the field set for this attribute.

sinceVersion

The Veeva OpenData version of when the attribute was released, for example, 1.0.0.

maximumLength

The recommended maximum length for this attribute.

required

True if this is a required attribute, False otherwise.

blankAllowed

True if this attribute can be blank, False otherwise.

defaultValue

The default value of this attribute.

expression

NEX (Network Expression) rule that is evaluated to determine the value of this attribute

expressionFlags

Bitwise OR of flags that describe when the expression is evaluated (1=evaluate on any value change, 2=evaluate on any attribute value change, 4=evaluate only if current value is not set)

dataPrivacyFlag

The value that will be included in fields when the HCP record is marked as opted out. Current values:

• NONE - No data privacy is applied to the field.
• MASK_WITH_BLANK - The field value is replaced with a blank or null.
• MASK_WITH_LABEL - The field value is replaced with a localized label: Data Privacy/Client Data Privacy

countries

The country code. Current values:

• available - a True/False value that indicates whether the field is available for a particular country
• required - a True/False value that indicates whether the field is required when creating a new record for a particular country
• readOnly - a True/False value that indicates whether the field is read-only for a particular country
• defaultValue - a True/False value that indicates the default value if NULL is provided when creating a new record for a particular country
• expression - NEX (Network Expression) rule that is evaluated to determine the value of this attribute
• expressionFlags - bitwise OR of flags that describe when the expression is evaluated (1=evaluate on any value change, 2=evaluate on any attribute value change, 4=evaluate only if current value is not set)
• allowedObjectTypes - an array of allowed types (from HCP, HCO, ADDRESS, LICENSE, PARENTHCO) for a particular country

Notes

• The response HTTP header includes Last-Modified to indicate the date when the list of fields was last changed.
• Supports the HTTP request header If-Modified-Since to check if the list of fields was modified since the specified date. The HTTP response contains the status code of 304 Not Modified if the content is unchanged.

Retrieve field details metadata

This API enables you to retrieve detailed information about the fields on each entity in Veeva OpenData.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/metadata/fields/{field_ids}

• field_ids is a comma-separated list of field IDs to look up

Optional parameters

labels

Include labels in field details:

• Default - Include labels
• Values - True or empty (include labels in the field details in the results)

countries

Filter fields by country visibility:

• Default - do not filter by country
• Values - The desired country values, for example, US, GB, FR. The countries must be visible to the authenticated user.

Response

responseStatus

The status of the response from Veeva OpenData.

attributes

An array attribute of information objects:

• field_id - The ID of the field; for example, first_name__v.
• type:
  • dataType - The type object, containing two attributes:
    • VEEVAID - the Veeva ID
    • STRING - text
    • YEAR - year value (no month or day)
    • DATE - date (no time)
    • DATETIME - date + Time (timestamp)
    • NUMBER - integer number
    • DOUBLE - floating point number
    • BOOLEAN - True or False value
    • REFERENCE - reference code
    • SET - a collection of values
    • ALTERNATEKEY - an alternate key
  • discriminator - For reference data type, include the reference data type name

labels

Set of language to description pairs (unless labels is not equal to True or empty).

customerOwned

False.

description

Non-localized text description of field.

readOnly

True if this is a read-only attribute, False otherwise.

ownerOnlyEdit

Not relevant for Veeva OpenData.

status

One of ACTIVE, DELETED, or DEACTIVATED.

fieldGroup

Either null or the name of the group for this attribute.

fieldSet

Either null or the name of the field set for this attribute.

sinceVersion

The Veeva OpenData version of when the attribute was released, for example, 1.0.0.

maximumLength

The recommended maximum length for this attribute.

required

True if this is a required attribute, False otherwise.

blankAllowed

True if this attribute can be blank, False otherwise.

defaultValue

The default value of this attribute.

expression

NEX (Network Expression) rule that is evaluated to determine the value of this attribute

expressionFlags

Bitwise OR of flags that describe when the expression is evaluated (1=evaluate on any value change, 2=evaluate on any attribute value change, 4=evaluate only if current value is not set)

dataPrivacyFlag

The value that will be included in fields when the HCP record is marked as opted out. Current values:

• NONE - No data privacy is applied to the field.
• MASK_WITH_BLANK - The field value is replaced with a blank or null.
• MASK_WITH_LABEL - The field value is replaced with a localized label: Data Privacy/Client Data Privacy

countries

The country code. Current values:

• available - a True/False value that indicates whether the field is available for a particular country
• required - a True/False value that indicates whether the field is required when creating a new record for a particular country
• readOnly - a True/False value that indicates whether the field is read-only for a particular country
• defaultValue - a True/False value that indicates the default value if NULL is provided when creating a new record for a particular country
• expression - NEX rule that is evaluated to determine the value of this attribute
• expressionFlags - bitwise OR of flags that describe when the expression is evaluated (1=evaluate on any value change, 2=evaluate on any attribute value change, 4=evaluate only if current value is not set)
• allowedObjectTypes - an array of allowed types (from HCP, HCO, ADDRESS, LICENSE, PARENTHCO) for a particular country

changeProcedure

This field replaces the deprecated changeRequest flag. This value can be configured per region and entity. For each of defaultChangeProcedure (default change procedure for the attribute) and regionalChangeProcedures (change procedures per region), the current values are as follows:

• DEFAULT - let the system decide what to do
• ALWAYS_ACCEPT_CHANGE - any changes will be automatically accepted without data steward review
• ALWAYS_REVIEW - any changes to this field must be reviewed by a data steward

Retrieve field groups metadata

This API enables you to retrieve detailed information about the field groups available in Veeva OpenData.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/metadata/fieldGroups

This API takes no parameters.

Response

responseStatus

The status of the response.

fieldGroups

An array of field groups.

Retrieve reference data types metadata

This API enables you to retrieve information about reference data types in Veeva OpenData.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/metadata/reference_values

Optional parameters

inactive

Include reference codes marked as inactive:

• Default - do not include inactive reference codes
• Values - True (include inactive reference codes in the results), otherwise do not include inactive reference codes. This value only works when includeCodes is True.

includeCodes

Include reference codes details:

• Default - return only type, base English label, and description
• Values - True (include reference codes in the results), otherwise do not include reference codes. If True, the codes returned are filtered by the inactive and owner parameters.

country

Filter codes by country, only if includeCodes is True:

• Default - do not filter by country
• Values - The desired country value, for example, US, GB, FR. The country must be visible to the authenticated user.

countries

Filter fields by country visibility:

• Default - do not filter by country
• Values - The desired country values, for example, US, GB, FR. The countries must be visible to the authenticated user.

Response

responseStatus

The status of the response.

reference_type_values

A single object containing information on the type and its codes:

• type - The reference type name, for example, Country.
• customerOwned - False.
• inactive - True if this reference type has been inactivated.
• description - Non-localized text description of the reference type.
• reference_type_codes- Array of reference code objects if includeCodes is True:
  • type - the reference type value of the code, for example, Country
  • code - the reference code value
  • values - an array of language/value pairs. Each reference item has its textual value provided in a set of translations. This array can be used to determine which languages are supported and the value for each language. For example: [{"en":"Canada"},{"zh":"加拿大"},{"fr":"Canada"},{"de":"Kanada"}]. Language codes are IETF language tags.
  • customerOwned - False
  • inactive - True if this reference type has been inactivated
  • countries - list of countries for which the code is visible, for example, US or GB.

Notes

• The response HTTP header includes Last-Modified to indicate the date when the list of fields was last changed.
• Supports the HTTP request header If-Modified-Since to check if the list of fields was modified since the specified date. The HTTP response contains the status code of 304 Not Modified if the content is unchanged.

Retrieve reference data type details metadata

This API enables you to retrieve detailed information about reference data types in Veeva OpenData.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/metadata/reference_values/{type}

• type is the specific data type to retrieve details about

Optional parameters

inactive

Include reference codes marked as inactive:

• Default - do not include inactive reference codes
• Values - True (include inactive reference codes in the results), otherwise do not include inactive reference codes. This value only works when includeCodes is True.

country

Filter codes by country, only if includeCodes is True:

• Default - do not filter by country
• Values - The desired country value, for example, US, GB, FR. The country must be visible to the authenticated user.

countries

Filter fields by country visibility:

• Default - do not filter by country
• Values - The desired country values, for example, US, GB, FR. The countries must be visible to the authenticated user.

Response

responseStatus

The status of the response.

reference_type_values

A single object containing information on the type and its codes:

• type - The reference type name, for example, Country.
• customerOwned - False.
• inactive - True if this reference type has been inactivated.
• description - Non-localized text description of the reference type.
• reference_type_codes- Array of reference code objects if includeCodes is True:
  • type - the reference type value of the code, for example, Country
  • code - the reference code value
  • values - an array of language/value pairs. Each reference item has its textual value provided in a set of translations. This array can be used to determine which languages are supported and the value for each language. For example: [{"en":"Canada"},{"zh":"加拿大"},{"fr":"Canada"},{"de":"Kanada"}]. Language codes are IETF language tags.
  • customerOwned - False.
  • inactive - True if this reference type has been inactivated
  • countries - list of countries for which the code is visible, for example, US or GB.

Notes

• The response HTTP header includes Last-Modified to indicate the date when the list of fields was last changed.
• Supports the HTTP request header If-Modified-Since to check if the list of fields was modified since the specified date. The HTTP response contains the status code of 304 Not Modified if the content is unchanged.

Retrieve reference data type code details metadata

This API enables you to retrieve detailed information about reference data type codes in Veeva OpenData.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/metadata/reference_values/{type}/{codes}

• type is the specific data type to retrieve details about
• codes is a comma-separated list of codes to look up for the specified type. Unknown codes for the given type are ignored, without errors.

Optional parameters

country

Filter codes by country, only if includeCodes is True:

• Default - do not filter by country
• Values - The desired country value, for example, US, GB, FR. The country must be visible to the authenticated user.

countries

Filter fields by country visibility:

• Default - do not filter by country
• Values - The desired country values, for example, US, GB, FR. The countries must be visible to the authenticated user.

Response

responseStatus

The status of the response.

reference_type_codes

An array of reference code objects:

• type - the reference type value of the code, for example, Country
• code - the reference code value
• values - an array of language/value pairs. Each reference item has its textual value provided in a set of translations. This array can be used to determine which languages are supported and the value for each language. For example: [{"en":"Canada"},{"zh":"加拿大"},{"fr":"Canada"},{"de":"Kanada"}]. Language codes are IETF language tags.
• customerOwned - False.
• inactive - True if this reference type has been inactivated
• countries - list of countries for which the code is visible, for example, US or GB.

Search

This API enables you to retrieve the full set of entities and child objects matching the specified search criteria.

Endpoint URL

https://opendataexplorer.veeva.com/api/opendata/v1.0/search

Parameters

q

The query string (type text).

address_q

The query string scoped to the address object of the entity.

types

The entity type; ALL for all objects, HCO or HCP. If not specified, the default is all types.

offset

The pagination number (type integer). The default is 0.

limit

The number to limit the results returned (type integer). The default is 10. The maximum is 100.

sort

The attribute to sort results by (type text). For example, first_name__v.

sortOrder

The sort order for the search. Value is asc for ascending or desc for descending.

states

A list of entity states to match on, including VALID, DELETED, UNDER_REVIEW, MERGED_INTO, MERGE_INACTIVATED, MERGE_ADDED, or INVALID.

statuses

A list of entity statuses to match on, including A (active), C (closed), D (deceased), I (inactive), R (retired), U (unknown), X (unknown license).

returnFacets

Include the facets in the response. The default is False.

returnHighlights

Include highlights in the response. The default is True.

facetCount

The maximum number of items to return for each facet (type integer). The default is 500.

filters

The filters for refining the result, for example, Country, Region, or Specialty (type text). For child entity attributes, use the following aliases:

• address - The address object.
• license - The license object.
• parent_hco - The parent HCO object.

Filters support scoped entity filters, which enable users to apply filters to a specific entity:

• hcp - The HCP (person) object.
• hco - The HCO (organization) object.

Filters also support collection fields, which enable users to search an OR condition across a collection of fields during search. The fields must be enabled in the data model to be included in collection.

• credentials - credentials_1__v to credentials_5__v.
• medical_degree - medical_degree_1__v to medical_degree_5__v.
• specialty - specialty_1__v to specialty_10__v.

Search filters should not be used with multivalued fields.

fieldQueries

The filters for refining the result (PARTIAL MATCH). For child entity attributes, use the following aliases:

• address - The address object.
• license - The license object.
• parent_hco - The parent HCO object.

lang

The language to run the query against. This is important when searching on reference values. For example, a search on "John Smith Pediatrics" will not return results for the specialty of pediatrics if the specified language is Chinese. If a language is not provided in the search query, the authenticated API user's default language is used.

supplemental

If provided, Veeva OpenData returns related parent HCOs of the entities found in the supplemental results.

• ONE - This is the default. Return at most one parent HCO per entity. Uses the primary relationship if available; otherwise, returns one of the parents.
• NONE - Do not return any parent HCOs.
• ALL - Return all of the parent HCOs.

If ONE or ALL is specified, associated hashtags appear in the supplemental results.

filterByLocation

Search results are filtered by their proximity to the specified location. Results outside the specified distance are excluded. The parameter is a comma separated list of fields in the format of "latitude, longitude, distance, bottomRightLatitude, bottomRightLongitude, filterType":

• latitude - The latitude of the central point of a circle or the top-left corner of a bounding box.
• longitude - The longitude of the central point of a circle or the top-left corner of a bounding box.
• distance - The length and unit of a radius of a circle or half the length of each side of a square when using a central point. Valid distance units are km (kilometers), m (meters), mi (miles), yd (yards), ft (feet). Can be blank for a bounding box with corners specified.
• bottomRightLatitude - The latitude of the bottom-right corner of a bounding box.
• bottomRightLongitude - The longitude of the bottom-right corner of a bounding box.
• filterType - Filter by DISTANCE (default) when specifying the central point of a circle or square, or filter by BOUNDING_BOX when specifying two corners of a bounding box.

sortByLocation

Search results are sorted by their proximity to the specified location. The parameter is a geo coordinate pair in the form latitude,longitude (for example 38.889931,-77.009003). Sort by location cannot be combined with sort by other attributes.

sortResultChildren

For search results containing addresses, licenses or parent HCOs, they will be sorted starting with the most relevant result. Default is False.

The returnHighlights flag must also be True for this functionality.

Address sort rules:

• Highlights for address fields
• Field queries/filters for address fields.
• Primary address field - Primary address is first. (Only one address can be primary.)
• Record state (record_state__v) - Valid records first.
• Address status (address_status__v) - Active records first, then inactive.
• Address type (address_type__v) - Professional (P), Professional and Preferred Mail (B), Mail Only (M), Address (U) Address Ordinal (address_ordinal__v).

License sort rules:

• Highlights for license fields.
• Field queries/filters for license fields.
• Record state (record_state__v) - Valid records first.
• License status (license_status__v) - Active records first, then inactive.
• License type (type__v) - State licenses first.
• Best state license (license_status__v) - Best state license first.

Parent HCO sort rules:

• Highlights for parent HCO fields.
• Field queries/filters for parent HCO fields.
• Primary parent HCO field - Primary affiliation is first. (Only one parent HCO can be primary.)
• Record state (record_state__v) - Valid records first.
• Parent HCO status (license_status__v) - Active records first, then inactive.
• Is primary relationship? (is_primary_relationship__v) - Primary relationship first.

nestChildObjectFieldQueries

Specifies whether or not to apply nesting to child object clauses. This will convert a requested field query into a fuzzy matching filter on the same field. The default is False.

• Filters do not return highlights when matching against these fields. All records are assumed to match the pattern for the specified field, so highlighting this field would be redundant.
• Filters search the field directly, so if you are using this flag for a reference field, you must supply the code value rather than a reference label.

parenthcofilters

Specifies the filters for parent HCO results. Parent HCOs in the parent_hco__v and supplementalResults sections will be returned if they pass these filters. The format is identical to filters but does not support filtering by child entities of the HCO.

enrichedResults

Specifies whether or not to display labels for reference type fields in the results.

resultLanguage

Specifies the language to use if the enriched results option is enabled. Uses the IETF BCP 47 language standard.

excludefilters

The filters for excluding results. The format is identical to filters but does not support child entity-scoped attributes.

parenthcoexcludefilters

The filters for excluding parent HCO results. Parent HCOs in the parent_hco__v and supplementalResults sections will not be returned if they pass these filters. The format is identical to filters but does not support filtering by child entities of the HCO.

Response

responseStatus

The status of the response from Veeva OpenData.

entitiess

An array of attribute information objects:

• entityId - The ID of the entity.
• entityType - The entity type, either HCP or HCO.
• metaData - An array of attribute information objects:
  • highlightTerms - the extracted terms from the highlights.
  • vid__v - the Veeva entity ID.
  • relevance - the relevance score for the entity relative to other results.
  • highlights - the exact results from the elastic search.
• entity - An array of attribute information objects containing all populated fields for the entities returned. An address child object may include the following fields:
  • geo_distance__u - A distance field. When sortByLocation is submitted, the addresses in the results return the distance in kilometers from the specified location.

totalCount

The total number of records hitting the search, regardless of limit.

offset

The pagination number. The default is 0.

limit

The number provided to limit the results.

supplementalResults

An array of attribute information objects containing details of the parent HCOs returned on the results.

hashtags

The list of hashtags available to the authenticated API user:

• name - the hashtag name.
• color - the hashtag color.
• tooltip - the tooltip of the hashtag.
• tooltipLabel - the field value label of the hashtag.
• tooltipValue - the field value of the hashtag.
• tooltipHasOtherValue - Returns True if the tooltip has more than three field values.

Notes

• There are two lines for highlights: The first contains the terms and the second contains the output from the search engine.
• The supplmentalResults set at the end of the result contains the external entity information of any parent HCOs referenced in the main results. Use the parent_hco_vid_v from the parent_hcos__v set and the vid_v on the supplmentalResults for reference.
• Filters are not supported for Date or DateTime type fields.
• Search only returns results based on visibility rules defined in the data visibility profile of the API user.

The response of every API call 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 a system error.

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

type - The specific type of error; for example, INVALID_DATA or METHOD_NOT_SUPPORTED. See the list of the most common types below. These values are not subject to change for a given version of the API, even when newer versions of the API are available.

message - The message accompanying each error type; for example, The request is invalid. Please verify that the requested URL, method and parameters are correct. When available, the error message includes the specific reason for the error. 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.

When Network processes an API request, it returns an HTTP response status code of 200. If Network returns a response status code other than 200, it is likely due to connectivity problems, and you should contact your IT team. You should base your logic on the responseStatus field and error types, rather than the HTTP response status codes.