About the Network API

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

The API enables you to leverage the power of Veeva Network directly in an application or website. The API provides methods to read, match, and submit petitions to apply changes to Veeva Network securely, so your application can retrieve and send requests to create, update, and merge information. It respects business rules and security as if you were in the Network UI.

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 Network 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 Network UI. This means that new versions of the API will reflect new capabilities introduced in new versions of Network and business logic will be consistent.

Compatibility

Network strives to make backward compatibility easy when using the API. Each new Network release consists of two components:

A new release of the Network Platform and Applications
A new version of the Network API

For example, Network version 22.0 included the General Availability of the version 21.0 API.

We maintain support for each API version across releases of Network. The API is backward compatible in that an application created to work with a given API version will continue to work with that same API version in future Network releases. However, newly introduced capabilities will not be available in older versions of the API.

Was this helpful?

Tell us more

Select all that apply. More to say? Send a message to our writers.

Parameters are missing

API usage is not clear

The examples aren't helpful

Additional feedback?

Name Role Email Message** denotes a required field

Thanks, we appreciate your feedback!

If the information on this page is unclear, consider sending a message to our writers.

Thanks, we appreciate your feedback!

Getting Started

The following sections discuss some of the basic concepts and steps you'll need to structure and make requests using the Network 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 Network 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 Network, you need a Network 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 Network administrator to modify your user profile.

Structuring the Endpoint

Every endpoint for API calls includes the following variables. You’ll need to replace these with the correct values.

server is the domain name of the Network instance. You can find this by logging into Network using the UI. Once you log in, you’ll see a URL like this:
https://my.network.com/ui/
In API calls, replace the server variable with the my.network.com portion of the URL.
version is the API version. Replace it with a version number, such as v26.0.

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/version/auth expects the following POST data in the body of the request: username and password.

Request

curl -X POST https://my.veevanetwork.com/api/v31.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

{
   "networkId" : "500",
   "responseStatus" : "SUCCESS",
   "userId" : 552,
   "sessionId" : "8E974F39652C0AC7D2458107D433A78583511D365F0BF13387D45569F37CBD4684B359B6B8FD41502592ACFAD1E6BD7FCA8F82A382A5243D61422119A7920E74689171F507FE98E95C51B0E25CE567BD",
   "networkIds" : [
      {
         "name" : "VERTEO",
         "url" : "https://my.veevanetwork.com/api",
         "id" : 500
      }
   ]
}

The networkIds collection in the response is a list of available Network instances. If there are more than one, an additional field (networkId) indicates which instance you’ve authenticated against.

Retrieve data

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

Assign the session ID to the header parameter Authorization.

Request

curl -X GET -H "Authorization: 7E5B79B3EBD5018CCC721A100FB891A1664A6399\
C673C9527DC6A93773204E0DB7ED7285B0919C04C7285F0B58C401E4D8763ABFD14B0000\
E9ABA2B4AB3C3A2908CFC3AC1A7E0A39195528D855729975" \
"https://my.veevanetwork.com/api/v31.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"
      },
      {
         "status" : "ACTIVE",
         "description" : "Custom Key",
         "type" : "sub-object",
         "customer_defined" : false,
         "name" : "CUSTOMKEY"
      }
   ],
   "responseStatus" : "SUCCESS"
}

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

Was this helpful?

Tell us more

Select all that apply. More to say? Send a message to our writers.

Parameters are missing

API usage is not clear

The examples aren't helpful

Additional feedback?

Name Role Email Message** denotes a required field

Thanks, we appreciate your feedback!

If the information on this page is unclear, consider sending a message to our writers.

Thanks, we appreciate your feedback!

Third-party integration

This tutorial details the steps required to build a bidirectional integration between third-party data providers and Veeva Network using the Network API.

The network API enable you to extract, update, and process data change requests in synchronization with the incremental data files provided.

How does it work?

Integration requires the following processes using the Network API:

Authenticating with Network
Extracting data change requests
Transferring files to Network FTP
Running the third-party source subscription
Updating data change request responses
Processing data change requests

Authenticate

The Authenticate API enables user authentication. After the user is authenticated, a sessionId is returned by Network that must be used on subsequent API calls. The sessionId is valid for 20 minutes.

Use the following command to authenticate with Network:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
-d 'username=john.smith@my.veevanetwork.com&password=12345' \
"https://my.veevanetwork.com/api/v31.0/auth"

If the request is successful, you will receive a response similar to the following:

{
   "networkId" : "500",
   "sessionId" : "26154CB7CEC2C55EE9CD62048C4ECF896E8BF5F3671D040DB7BAF596DD5CF5F960E2C10DBF7D71EBF030C6E1269292F65E700E1361560F7D9EC6108091CBD2A2AB39BC60A23B72BB85F811E8F57B8BB4",
   "networkIds" : [
      {
         "name" : "MYVEEVA",
         "url" : "https://my.veevanetwork.com/api",
         "id" : 500
      }
   ],
   "userId" : 552,
   "responseStatus" : "SUCCESS"
}

For more information on the Authenticate API, see the Authenticating topic.

Extract data change requests

Use the following command to search for change requests in Network:

GET https://my.veevanetwork.com/api/v31.0/change_request/search \
?offset=0&limit=100&filters=task_status:NEW,IN_PROGRESS~task_country:AT \
~rangeDiff||created_at:24&systemName=TEST&masterSystemNames=TEST

You will receive a response similar to the following:

{
   "change_requests" : [
      {
         "resolution_notes" : [
            {
               "created_date" : "2019-08-26T08:54:51.272-07:00",
               "fields" : [
                  "gender__v"
               ],
               "comment" : "System rejected - You are trying to update an invalid, merged or deleted record. Change cannot be processed.",
               "code" : "R-00015"
            }
         ],
         "vid__v" : "928814547694977055",
         "parent_task_ids" : [],
         "task_type" : "CHANGE_REQUEST",
         "entity" : {
            "addresses__v" : [],
            "gender__v" : {
               "change_requested" : "M",
               "result" : "CHANGE_REJECTED",
               "final_value" : null
            }
         },
         "original_task_type" : "CHANGE_REQUEST",
         "taskCountry" : "US",
         "status__v" : "CHANGE_PROCESSED",
         "reserved_vid" : null,
         "vid_key" : "Network:Entity:928814547694977055",
         "result__v" : "CHANGE_REJECTED",
         "entity_type" : "HCP",
         "completed_date" : "2019-08-26T08:54:52.000-07:00",
         "change_request_id" : "928814551096036511",
         "created_date" : "2016-08-17T11:29:21.000-07:00",
         "metadata" : {
            "note" : "Email",
            "creator" : "dharssan@idemo.veevanetwork.com",
            "system" : "dharssan_high",
            "source" : null
         }
      },
      {
         "vid__v" : "928814547694977055",
         "resolution_notes" : [
            {
               "comment" : "Accepted all changes",
               "code" : null,
               "fields" : [
                  "gender__v"
               ],
               "created_date" : "2016-08-17T09:32:39.671-07:00"
            }
         ],
         "original_task_type" : "CHANGE_REQUEST",
         "entity" : {
            "gender__v" : {
               "change_requested" : "M",
               "final_value" : "M",
               "result" : "CHANGE_ACCEPTED"
            }
         },
         "parent_task_ids" : [],
         "task_type" : "CHANGE_REQUEST",
         "taskCountry" : "US",
         "status__v" : "CHANGE_PROCESSED",
         "reserved_vid" : null,
         "result__v" : "CHANGE_ACCEPTED",
         "vid_key" : "Network:Entity:928814547694977055",
         "completed_date" : "2016-08-17T11:32:45.000-07:00",
         "change_request_id" : "928814561779387551",
         "entity_type" : "HCP",
         "metadata" : {
            "system" : "dharssan_high",
            "creator" : "dharssan@idemo.veevanetwork.com",
            "source" : null,
            "note" : "Email"
         },
         "created_date" : "2016-08-17T11:32:04.000-07:00"
      }
   ],
   "responseStatus" : "SUCCESS",
   "limit" : 10,
   "offset" : 0,
   "totalCount" : 2
}

The next step of the integration process is to extract the third-party data change requests.

The Change Request Search API enables the integrator system to retrieve the required records based on the filter criteria defined. This API provides multiple filters that integrator systems can use based on the different requirements and aspects of the integration.

Best practice

Define the best possible filter criteria for the integrator system. In the example, the following criteria are used for extracting add or change requests:
- Status is NEW or IN_PROGRESS.
- Country is AT (Austria).
- Request creation time is the last 24 hours.
If the integration is to occur more than once a day, you can use the Change Request Update API to change the status of the extracted change requests from CHANGE_NEW to CHANGE_PENDINGREVIEW. This ensures that the same change requests are not extracted again.
Use date ranges. It is possible data change requests in Network change status (that is, from NEW to IN_PROGRESS) as a result of customer-owned changes being managed by customer data stewards, or because of auto-accept or reject configuration on them.
The task_country must use the ISO 3166-1 alpha-2 code.
Filter the integrator system by masterSystemNames or pendingMasterSystemNames to extract only relevant data change requests and fields from them. In Network, customers could decide to maintain customer-owned attributes managed by local data stewards. As a result, there could be data change requests with entirely customer-owned attributes that are not relevant to the integrator system.
Include the systemName parameter for the integrator system so that Network will return target alias values specified for reference value codes. It is important for downstream systems to receive their reference codes for proper data change request processing. If the system name is not provided, Network will return default reference value codes.
When you provide the systemName parameter, Network returns the external_custom_keys array, which contains the defined integrator system identifiers used on data load. (This is the same as the master_keys parameter used for the Update Data Change Request API.)
The integrator system must differentiate between add requests and change requests to better manage the resolution between existing and non-existing records on the system. This can be done in two ways:
- Recommended: Use the task_type provided on every change request response. If the task_type is ADD_REQUEST, no further action is required and the change request can be pushed to the integrator system for processing. If the task_type is CHANGE_REQUEST, the integrator system should use the '…' in the result to find the cross-reference custom_key and use it for processing.
- Make different Change Request Search API calls and filter by task_type. When you filter by task_type of CHANGE_REQUEST, the integrator system should use the Retrieve HCP, Retrieve HCO, or Batch Retrieve Entities API to check the custom_key table on the entity to find the cross-reference and use it for processing.

Transfer files into Network

After you extract the data change requests, apply them to the third-party system, and generate incremental files for Network consumption, you transfer the files into the Network FTP.

This file transfer and location in the Network FTP site varies by project. Network provides an inbound/outbound FTP structure for customers to use and enhance as needed with additional subfolders.

Most commonly, customers would add subfolders to the Inbound folder to store third-party files provided by the integrator system. The following is a common Network FTP setup.

Run the third-party source subscription

Use the following command to create a source subscription job:

GET https://my.veevanetwork.com/api/v31.0/systems/TEST/source_subscriptions/TEST_1/job

If the command is successful, you'll receive a response similar to the following:

{
  "responseStatus": "SUCCESS",
  "job_id": 26  
}

After the third-party incremental files have been transferred to the correct path on the Network FTP site, the integrator system must upload the data using the Create Source Subscription Job API for the specific third-party system defined in Network.

The job_id is essential for the next step of the process. The integrator system should store the returned job_id for future API calls when updating the data change requests with responses.

Retrieve the source subscription job

Use the following command to retrieve a source subscription job:

GET https://my.veevanetwork.com/api/v31.0/systems/TEST/source_subscriptions/TEST_1/job/26

If the request is successful, you'll receive a response similar to the following:

{
  "responseStatus": "SUCCESS",
  "subscriptionId": 46,
  "subscriptionName": "TEST_1",
  "durationInMilliseconds": 55000,
  "type": "MANUAL",
  "errorCount": 292,
  "badRecordCount": 292,
  "recordCount": 10073,
  "filesProcessed": 3,
  "dataLoadSummary": {
    "HCO": {
      "rowsRead": 1299,
      "rowsParsed": 1299
    },
    "CHILDACCOUNT": {
      "rowsRead": 2590,
      "rowsParsed": 2590
    },
    "HCP": {
      "rowsRead": 1635,
      "rowsParsed": 1635
    },
    "ADDRESS": {
      "rowsRead": 4549,
      "rowsParsed": 4549
    }
  },
  "processedDataSummary": {
    "HCP": 1635,
    "HCO": 1299,
    "ADDRESS": 2902,
    "LICENSE": 0,
    "PARENTHCO": 1747,
    "CUSTOMKEYS": 0
  },
  "matchSummary": {
    "HCP": {
      "notMatched": 0,
      "ACT": 1635,
      "ASK": 0
    },
    "HCO": {
      "notMatched": 0,
      "ACT": 1299,
      "ASK": 0
    }
  },
  "jobResultSummary": {
    "HCP": {
      "total": 265,
      "newRecordsAdded": 0,
      "recordsMerged": 265
    },
    "HCO": {
      "total": 185,
      "newRecordsAdded": 0,
      "recordsMerged": 185
    },
    "ADDRESS": {
      "total": 434,
      "newRecordsAdded": 0,
      "recordsMerged": 434
    },
    "LICENSE": {
      "total": 0,
      "newRecordsAdded": 0,
      "recordsMerged": 0
    },
    "PARENTHCO": {
      "total": 124,
      "newRecordsAdded": 0,
      "recordsMerged": 124
    }
  },
  "job_id": 26,
  "job_status": "COMPLETE",
  "created_date": "2015-09-21T06:24:18.000-07:00",
  "completed_date": "2015-09-21T06:25:13.000-07:00"
}

The integrator system should verify that the job status is COMPLETE before it moves to the next step of the process and updates the data change request with responses. You can check the job status using the Retrieve Source Subscription Job API.

Update data change request responses

Use the following command to update change requests:

PUT https://my.network.com/api/v31.0/change_requests/batch

The following PUT data is used for this request:

{
  "change_requests": [
    {
      "metadata": {
        "creator": "tacz@my.veevanetwork.com",
        "note": "New AT HCP Test 1",
        "source": "Veeva CRM",
        "system": "TEST"
      },
      "entity": {
        "first_name__v": {
          "change_requested": "AT test1",
          "final_value": null,
          "result": "CHANGE_ACCEPTED"
        },
        "gender__v": {
          "change_requested": "M",
          "final_value": null,
          "result": "CHANGE_ACCEPTED"
        },
        "hcp_type__v": {
          "change_requested": "D",
          "final_value": null,
          "result": "CHANGE_ACCEPTED"
        },
        "last_name__v": {
          "change_requested": "vad AT test",
          "final_value": null,
          "result": "CHANGE_MODIFIED"
        },
        "prefix__v": {
          "change_requested": "MR",
          "final_value": null,
          "result": "CHANGE_ACCEPTED"
        },
        "primary_country__v": {
          "change_requested": "AT",
          "final_value": null,
          "result": "CHANGE_ACCEPTED"
        },
        "specialty_1__v": {
          "change_requested": "a2HK0000000x3fXMAQ",
          "final_value": null,
          "result": "CHANGE_REJECTED"
        },
        "master_keys": [
          "TEST:HCP:997200012"
        ],
        "addresses__v": [
          {
            "vid_key": "VCRM-00DJ0000003O0PrMAK:Data_Change
               _Request_vod__c:a23K0000000ys9GIAQ",
            "vid__v": null,
            "object_id": "710056091609829377",
            "administrative_area__v": {
              "change_requested": "AT-6",
              "final_value": null,
              "result": "CHANGE_ACCEPTED"
            },
            "address_line_1__v": {
              "change_requested": "Add test1",
              "final_value": null,
              "result": "CHANGE_ACCEPTED"
            },
            "country__v": {
              "change_requested": "AT",
              "final_value": null,
              "result": "CHANGE_ACCEPTED"
            },
            "locality__v": {
              "change_requested": "city tst1",
              "final_value": null,
              "result": "CHANGE_MODIFIED"
            },
            "primary_address_2__c": {
              "change_requested": "Y",
              "final_value": null,
              "result": "CHANGE_ACCEPTED"
            },
            "postal_code__v": {
              "change_requested": "54654",
              "final_value": null,
              "result": "CHANGE_ACCEPTED"
            },
            "address_line_2__v": {
              "change_requested": null,
              "final_value": null,
              "result": "CHANGE_ACCEPTED"
            },
            "master_keys": [
              "TEST:ADDRESS:997200013"
            ]
          }
        ]
      },
      "taskCountry": "AT",
      "task_type": "ADD_REQUEST",
      "original_task_type": "ADD_REQUEST",
      "change_request_id": "710056091685326848",
      "status__v": "CHANGE_PARTIALLYPROCESSED",
      "result__v": null,
      "entity_type": "HCP",
      "vid_key": "VCRM-00DJ0000003O0PrMAK:Data_Change
         _Request_vod__c:a23K0000000ys9BIAQ",
      "vid__v": null,
      "resolution_notes": [
        {
          "comment": "System Rejected - Invalid change requested value",
          "fields": [
            "specialty_1__v"
          ],
          "created_date": "2015-08-03T04:09:59.817-07:00"
        }
      ],
      "created_date": "2015-08-03T04:09:59.000-07:00",
      "completed_date": null,
      "job_ids": [
        "26"
      ]
    },
    {
      "metadata": {
        "creator": "tacz@my.veevanetwork.com",
        "note": "AT Edit HCP DCR test1",
        "source": "Veeva CRM",
        "system": "VCRM-00DJ0000003O0PrMAK"
      },
      "entity": {
        "prefix__v": {
          "change_requested": "DR",
          "final_value": null,
          "result": "CHANGE_ACCEPTED"
        },
        "specialty_1__v": {
          "change_requested": "a2HK0000000x3fRMAQ",
          "final_value": null,
          "result": "CHANGE_ACCEPTED"
        },
        "specialty_2__v": {
          "change_requested": "a2HK0000000x3fWMAQ",
          "final_value": null,
          "result": "CHANGE_REJECTED"
        },
        "master_keys": [
          "TEST:HCP:997200021"
        ]
      },
      "taskCountry": "AT",
      "task_type": "CHANGE_REQUEST",
      "original_task_type": "CHANGE_REQUEST",
      "change_request_id": "710062754328842240",
      "status__v": "CHANGE_PENDINGREVIEW",
      "result__v": null,
      "entity_type": "HCP",
      "vid_key": "Network:Entity:709630173695283201",
      "vid__v": "709630173695283201",
      "resolution_notes": [
        {
          "comment": "System Rejected - Invalid change requested value",
          "fields": [
            "specialty_2__v"
          ],
          "created_date": "2015-08-03T04:23:12.867-07:00"
        }
      ],
      "created_date": "2015-08-03T04:23:13.000-07:00",
      "completed_date": null,
      "job_ids": [
        "26"
      ]
    }
  ]
}

You will receive a response similar to the following:

{
  "responseStatus": "SUCCESS",
  "change_requests": [
    {
      "responseStatus": "SUCCESS",
      "change_request_id": "710056091685326848"
    },
    {
      "responseStatus": "SUCCESS",
      "change_request_id": "710062754328842240"
    }
  ]
}

After the third-party subscription runs, the next step is to update the data change request. The Update Change Request and Batch Update Change Request APIs enable the integrator system to update the data change requests with information from the responses generated by the third-party application.

In this example, the integrator system is updating the two data change requests extracted from the source subscription, providing necessary information from the third-party application as well as the jobs in Network.

Notes

The integrator system should update the data change requests with responses using the batch API to avoid multiple calls and make the integration more efficient.
Not all fields in the data change requests can be updated by the integrator system. Updatable fields during the update process are:
- Required: The system parameter in the metadata array.
- Required: The master_keys parameter in each entity array for every object (HCP, HCO, ADDRESS, LICENSE, and PARENTHCO) being updated.
- Recommended: The job_ids parameter in the change_requests array.
- The final_value parameter for each field in the entity array. If job_ids values are provided, this value is not required (as Network calculates it). Recommended if not.
- Recommended: The comment parameter in the change_requests array. Feedback about the data change request resolution by third-party data stewards is important to end users. The comment is transferred to the resolution_notes, which are consumed by downstream systems (such as Veeva CRM).
- The integrator system must provide the original change_request_id extracted during the Extract Data Change Request step in order for Network to match the records. All the other attributes in the original extraction can remain during the update and will not produce any errors unless they change.
The integrator system should establish a process for storing and retrying any unsuccessful data change request updates (responseStatus not equal to SUCCESS).

Process data change requests

Use the following command to process data change requests:

PUT https://my.network.com/api/v31.0/change_requests/process/batch

The following PUT data is used for this request:

{
  "change_requests": [
    {
      "change_request_id": "710056091685326848"
    },
    {
      "change_request_id": "710062754328842240"
    }
  ],
  "systemName": "TEST"
}

If the request is successful, you'll receive the following response:

{
    "responseStatus": "SUCCESS"
}

The final step of the integration is to process the data change requests. The Process Change Request and Batch Process Change Request APIs enable the integrator system to close unprocessed data change requests after all the updates have been completed.

In this example, the integrator system processes the two data change requests extracted on the Extract Data Change Request step and updated on the Update Data Change Request Response step, providing the Network change_request_id and the third-party master systemName.

Notes

If the third-party source subscription job does not complete and the integrator system moves to the final steps of the integration, updating and processing the data change request with responses, the Network application automatically checks every five minutes until the job is complete to calculate the final_value of the fields in the data change request.
If the integrator system has no control over the incremental file transfer process and therefore does not know the job_id, it can still continue with the final steps of the integration by updating and processing the data change requests with responses. However, the final_value of the fields in the data change requests is not calculated automatically by Network, resulting in inconsistencies between the actual data and the data change request responses unless the integrator system provides the final_value for all changes.

Was this helpful?

Tell us more

Select all that apply. More to say? Send a message to our writers.

Parameters are missing

API usage is not clear

The examples aren't helpful

Additional feedback?

Name Role Email Message** denotes a required field

Thanks, we appreciate your feedback!

If the information on this page is unclear, consider sending a message to our writers.

Thanks, we appreciate your feedback!

Bulk exports

This tutorial details the steps required to perform and retrieve a bulk export from Veeva Network using the Network API.

The basic steps required are as follows

Authenticate with Network.
Create a target subscription job.
Check the status of the subscription job (optionaL).
Retrieve the results of the subscription job.

When initiating a bulk export, you'll need to know the system and subscription names in the Network instance you're calling.

Authenticating with Network

The Authenticate API enables user authentication. After the user is authenticated, a sessionId is returned by Network that must be used on subsequent API calls. The sessionId is valid for 20 minutes.

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d \
'username=john.smith@my.veevanetwork.com&password=12345' \
"https://my.veevanetwork.com/api/v31.0/auth"

If the authentication is successful, the response will appear like this:

{
   "networkId" : "500",
   "sessionId" : "26154CB7CEC2C55EE9CD62048C4ECF896E8BF5F3671D040DB7BAF596DD5CF5F960E2C10DBF7D71EBF030C6E1269292F65E700E1361560F7D9EC6108091CBD2A2AB39BC60A23B72BB85F811E8F57B8BB4",
   "networkIds" : [
      {
         "name" : "MYVEEVA",
         "url" : "https://my.veevanetwork.com/api",
         "id" : 500
      }
   ],
   "userId" : 552,
   "responseStatus" : "SUCCESS"
}

Running the target subscription job

Once you've authenticated with Network, you use the session ID received from that call to start a bulk export job.

Here's the request:

curl -X POST -H "Authorization: 26154CB7CEC2C55EE9CD62048C4ECF896E8BF5F3671D040\
DB7BAF596DD5CF5F960E2C10DBF7D71EBF030C6E1269292F65E700E1361560F7D9EC6108091CBD2\
A2AB39BC60A23B72BB85F811E8F57B8BB4" https://my.veevanetwork.com/api/v31.0/systems\
/verteo/target_subscriptions/FullExport/job?export_archive=split

The export_archive option specifies that export files should be split to avoid job timeouts. The maximum file size with this option set is 1GB.

The result provides the job ID required for later steps:

{
    "job_id" : 1126,
    "responseStatus" : "SUCCESS"
}

The export job is now running.

Retrieving the target subscription job status

Depending on the size and type of the job, you might want to check the target job's status.

For this step, you'll need the system name, subscription name, and the job ID produced in the previous step.

curl -X GET -H "Authorization: 26154CB7CEC2C55EE9CD62048C4ECF896E8BF5F3671D040\
DB7BAF596DD5CF5F960E2C10DBF7D71EBF030C6E1269292F65E700E1361560F7D9EC6108091CBD2\
A2AB39BC60A23B72BB85F811E8F57B8BB4" https://my.veevanetwork.com/api/v31.0/systems\
/verteo/target_subscriptions/FullExport/job/1126

This produces the following result:

{
   "responseStatus":"SUCCESS",
   "job_id":1126,
   "job_status":"COMPLETE",
   "created_date":"2020-02-12T12:04:03.000-08:00",
   "data_revision_first":"0",
   "data_revision_last":"937744301078642687",
   "export_package_path":"outbound/verteo/FullExport/FullExport_210212T200403429",
   "total_records_exported":"45484",
   "subscriptionId":15,
   "subscriptionName":"FullExport",
   "completed_date":"2020-02-12T12:04:15.000-08:00",
   "durationInMilliseconds":120000,
   "type":"MANUAL",
   "errorCount":0,
   "badRecordCount":0,
   "exportReferenceCount":0,
   "exportFull":true,
   "exportIncludeReference":false,
   "exportUpdatedChildOnly":false,
   "exportSetSubscriptionStateOnFull":false,
   "exportFormat":"CSV",
   "exportReferenceVersion":"4",
   "exportActiveOnly":false,
   "exportPackageName":"FullExport_${timestamp}",
   "jobExportCount":{
      "PARENTHCO":2302,
      "HCP":499,
      "HCO":44985,
      "ADDRESS":46025
   },
   "exportFormatDelimiter":"\t",
   "exportFormatTextQualifier":"\"",
   "export_archive":"split",
   "jobExportLinks":[
      {
         "object":"parenthco",
         "href":"/artifact/job/1126/parenthco_0000.csv",
         "method":"GET",
         "accept":"text/csv"
      },
      {
         "object":"hcp",
         "href":"/artifact/job/1126/hcp_0000.csv",
         "method":"GET",
         "accept":"text/csv"
      },
      {
         "object":"hcp",
         "href":"/artifact/job/1126/hcp_0001.csv",
         "method":"GET",
         "accept":"text/csv"
      },
      {
         "object":"hco",
         "href":"/artifact/job/1126/hco_0000.csv",
         "method":"GET",
         "accept":"text/csv"
      },
      {
         "object":"address",
         "href":"/artifact/job/1126/address_0000.csv",
         "method":"GET",
         "accept":"text/csv"
      }
   ]
}

The status indicates that the job has completed successfully, and returns summaries for exported records.

Files for each entity are split automatically at 1GB intervals, and file names in turn are incremented by one; for example, hcp_0000.csv, hcp_0001.csv, and so on.

Retrieve the target subscription job results

Once your target subscription job has completed successfully, you can retrieve the contents of the files, or artifacts, for each entity exported in the job.

For this call, you'll need the job ID and file name produced in the previous steps; for example, to retrieve the HCPs from the target subscription job, you use the file name hcp_0000.csv produced in the previous step:

curl -X GET -H "Authorization: 2C2EE0B28E170EFEFEE94EC86F632CA01918905AC2E5E8\
F1914F36E0B532E59C6925DE52CC6EBB01C8DE35F355B9AF89E7B735437C8BB1AAA8212F35F6E17\
3737D7DF47DC6A9DC1D0229C5C2B17EDD94" https://my.veevanetwork.com/api/v31.0/artifact\
/job/68230/hcp_0000.csv > verteo_hcp_export.csv

This call outputs the contents of the export for HCPs to a local file named verteo_hcp_export.csv which you can open and view.

Repeat this step for each artifact as needed.

Was this helpful?

Tell us more

Select all that apply. More to say? Send a message to our writers.

Parameters are missing

API usage is not clear

The examples aren't helpful

Additional feedback?

Name Role Email Message** denotes a required field

Thanks, we appreciate your feedback!

If the information on this page is unclear, consider sending a message to our writers.