Veeva Vault API Guide (v26.2): EDC, CTMS, eTMF, Limits
CTO & Co-Founder
CTO & Co-Founder at Nirmitee.io. Architects healthcare integrations across FHIR, SMART on FHIR, ABDM and NHCX, writing from production experience taking hospital software from sandbox to go-live.

The Veeva Vault API is a public REST API that reads and writes documents, object records, users and workflows in every Vault application, including CTMS, eTMF, RIM and Quality. Veeva EDC has its own clinical data API on a second portal. Veeva documents both in the open, and v26.2 is the current GA version.
This guide is for the buyer who has to connect a clinical system to Veeva, and for the engineer who builds it. It covers what you can connect, the ten ways to connect it, a step by step build with curl, Python and Java, data exports, multi-system designs, reliability, the blockers you will meet and how to clear them. If you want a team to build it, see our EHR and EMR integration services. Last checked: Nov 21, 2026.
Veeva Vault API at a glance
| Question | Short answer |
|---|---|
| Who grants access? | The customer's Vault admin. The integration user needs the API Access permission in that Vault. |
| Who signs? | The Veeva customer, usually the sponsor or CRO. Veeva publishes no separate API contract for vendors. |
| Are there public documents? | Yes. Vault API at general.veevavault.dev and the EDC API at developer-cdms.veevavault.com. |
| Which routes exist? | REST API, VQL, Vault Loader, Direct Data API, Vault Java SDK with Spark, Vault Connections, the EDC API, Vault AI MCP and certified middleware. |
| What does it cost? | Veeva publishes no API fee. Direct Data API is included with Vault Platform at no extra license fee. |
| How long does it take? | Veeva publishes no approval or onboarding time. |
| What is the biggest limit? | The burst limit per 5-minute window, and small batch sizes on EDC writes (25 forms per call). |
What can you build with the Veeva Vault API?
Most Veeva integrations fall into eight jobs. Each one links to a row in the read and write table in the next section (rows R1 to R12). Build complexity is our own rating.
1. Load lab or vital values into Veeva EDC forms
- Who it is for: site systems, lab data vendors and eSource tools.
- The value: values arrive in the casebook without double entry at the site.
- Build complexity: high.
- How well it works: well, once the study design is known.
POST /api/{version}/app/cdm/forms/actions/setdatareopens a form, adds item groups, sets values and can submit the form in one call. Values are marked as owned by another system by default. See row R6.
2. Create EDC casebooks from an enrollment or randomization system
- Who it is for: IRT and randomization vendors, and site enrollment tools.
- The value: a new subject in your system becomes a casebook in Veeva EDC.
- Build complexity: medium.
- How well it works: well.
POST /api/{version}/app/cdm/subjectscreates up to 100 subjects per call and also creates the first event group and event. Veeva asks you to call it on a single thread. See row R5.
3. Work EDC queries from a data review tool
- Who it is for: data review, risk-based monitoring and analytics tools.
- The value: reviewers open, answer and close queries without switching screens.
- Build complexity: medium.
- How well it works: well. The EDC API lists queries changed since a date, and has endpoints to open, answer, close and reopen them. See row R7.
4. Feed Vault and EDC data into a data warehouse
- Who it is for: sponsors, CROs and analytics platforms.
- The value: study data in one place for reporting and models.
- Build complexity: medium.
- How well it works: well. Direct Data API publishes a full file each day and an incremental file every 15 minutes for Vault Clinical. Veeva EDC data comes out through the Study Data Extract job instead. See rows R10 and R11.
5. Sync CTMS studies, sites and milestones to finance or ERP
- Who it is for: finance teams, site payment tools and portfolio systems.
- The value: budgets and site payments follow the real study status.
- Build complexity: medium.
- How well it works: well. VQL reads study, site and milestone objects, and the object record endpoint upserts up to 500 records per call. See rows R2 and R9.
6. File documents into eTMF from another document system
- Who it is for: CROs, site document tools and partner systems.
- The value: documents reach the trial master file with their metadata.
- Build complexity: medium.
- How well it works: well. The documents API creates one document up to 4GB, or up to 500 per batch call. Expected Document Lists can be built through a Clinical Operations endpoint. See rows R1 and R9.
7. Move a legacy CTMS or eTMF into Vault Clinical
- Who it is for: sponsors and CROs changing systems.
- The value: history moves in bulk without hand entry. See our healthcare data migration service.
- Build complexity: high.
- How well it works: well. Veeva recommends Study Migration Mode for all Veeva CTMS migrations, and Vault Loader takes up to 10 data objects per request in chunks of 500 records. See rows R2 and R9.
8. Notify an outside system when a Vault record changes
- Who it is for: any product that must react to a change in Vault.
- The value: your system hears about a change without polling all day.
- Build complexity: high.
- How well it works: well, with code inside Vault. The Vault Java SDK runs record triggers in Vault and can send Spark messages or HTTP callouts. See row R12.
The eight Veeva Vault use cases compared
| Use case | Who it is for | Complexity |
|---|---|---|
| 1. Load lab or vital values into EDC | Site systems, lab vendors | High |
| 2. Create EDC casebooks | IRT and enrollment tools | Medium |
| 3. Work EDC queries | Data review tools | Medium |
| 4. Feed a data warehouse | Sponsors, CROs, analytics | Medium |
| 5. Sync CTMS to finance or ERP | Finance, site payments | Medium |
| 6. File documents into eTMF | CROs, document tools | Medium |
| 7. Move a legacy CTMS or eTMF | Sponsors, CROs | High |
| 8. Notify an outside system | Any connected product | High |
What data can you integrate with Veeva Vault?
You can integrate five kinds of Vault data: documents, object records, users, workflows and, in Veeva EDC, clinical study data. CTMS, eTMF, RIM and Quality are Vault applications built on the same documents and objects, plus a few application endpoints of their own. Start by listing every record you read and every record you write, because that list decides the route.
Documents
A Vault document carries a file, its renditions and metadata fields, and moves through a lifecycle. eTMF content, Quality SOPs and RIM submission documents are all documents. You create one document with POST /api/{version}/objects/documents (file up to 4GB) or up to 500 with the batch endpoint. Vault Loader can also extract documents, versions and relationships to CSV.
Object records
Everything that is not a file is an object record: a CTMS study (study__v), a study site, a milestone, a monitoring visit, a product, a Quality event. You read them with VQL and create or upsert them with POST /api/{version}/vobjects/{object_name}, up to 500 per call. Object names end in __v for Veeva standard objects, __c for customer objects and __sys for system objects.
Users
The Users API creates and updates Vault users and their Vault membership. A new user defaults to the document_user__v security profile and a full license unless you set them. EDC has its own user upload endpoints that also set the study role.
Workflows
Workflows route documents and records for review and approval. Direct Data API exports workflow data, and the Vault Java SDK can run custom actions in a workflow. Check which workflow actions the customer's Vault allows through the API before you design around them.
EDC study data
Veeva EDC has its own API under /api/{version}/app/cdm/. The main records are studies, sites, subjects (each subject has a casebook), event groups and events (visits), forms, item groups and items (the data points), queries, protocol deviations and coding requests. Study design (event, form and item definitions) is readable through /app/cdm/design/.
CTMS and eTMF
Veeva CTMS and eTMF live in a Vault Clinical Operations Vault. Their data is object records and documents, so the platform API reads and writes them. Veeva adds 17 Clinical Operations endpoints for actions such as creating Expected Document Lists, creating milestones from a template, sending safety letters through Site Connect, populating site fee definitions and switching Study Migration Mode.
RIM and Quality
RIM and Quality Vaults use the same documents and objects, plus a short list of application endpoints. Examples are the RIM Submissions Archive import (POST /api/{version}/vobjects/submission__v/{submission_id}/actions/import), QMS team assignments and Batch Release disposition (POST /api/{version}/app/quality/batch_release/disposition).
What can you read and write with the Veeva Vault API?
| Row | Data | Read | Write | Example endpoint |
|---|---|---|---|---|
| R1 | Documents (eTMF, Quality, RIM) | Yes | Create, version, batch of 500 | POST /api/{version}/objects/documents and /objects/documents/batch |
| R2 | Object records (CTMS study, site, milestone) | Yes, through VQL | Create and upsert, 500 per call | POST /api/{version}/vobjects/{object_name}?idParam=external_id__v |
| R3 | Users and Vault membership | Yes | Create, update, add to a Vault | POST /api/{version}/objects/users |
| R4 | EDC study design | Yes | Design writes on the latest casebook version | GET /api/{version}/app/cdm/design/form_def |
| R5 | EDC subjects (casebooks) | Yes, changed since a date | Create, update, set status | POST /api/{version}/app/cdm/subjects |
| R6 | EDC events and forms | Yes, one subject and event at a time | Set event date, set data, submit, reopen | POST /api/{version}/app/cdm/forms/actions/setdata |
| R7 | EDC queries and coding | Yes, changed since a date | Open, answer, close, reopen | POST /api/{version}/app/cdm/queries/actions/answer |
| R8 | Any Vault data through VQL | Yes | No | POST /api/{version}/query |
| R9 | Clinical Operations actions | No | EDLs, milestones, site fees, migration mode | POST /api/{version}/vobjects/study__v/{study_id}/actions/etmfcreateedl |
| R10 | Direct Data files | Yes | No | GET /api/{version}/services/directdata/files |
| R11 | EDC Study Data Extract | Yes | No | POST /api/{version}/app/cdm/jobs/start_now |
| R12 | Outbound change events | Not by API | Java SDK triggers, Spark, HTTP callout | Vault Java SDK |
What are the ways to integrate with Veeva Vault?
Veeva offers ten routes. The REST API and VQL cover most two-way work, Direct Data API covers the warehouse, Loader covers bulk, the Java SDK covers push, and the EDC API covers trial data. Pick by the job, then add a second route only when the first cannot do part of it.
| Route | What it is | Pick it when | Avoid it when |
|---|---|---|---|
| Vault REST API | Object records, documents, users, jobs | You read and write live, record by record or in batches of 500 | You need a full copy of the Vault every day |
| VQL | A SQL-like query language over POST /query | You read filtered records, for example everything changed since a time | You need to write |
| Vault Java SDK and Spark | Your Java code runs inside the customer's Vault | Vault must push a change out, or enforce a rule as data arrives | The customer will not deploy and validate custom code |
| Vault Connections | Productized links between Veeva Vaults | Both ends are Veeva, for example EDC to CTMS | One end is not a Veeva Vault |
| Direct Data API | Read-only files: full daily, incremental every 15 minutes, log daily | You feed a warehouse or lake | You need real time, or the data is in Veeva EDC |
| Vault Loader | Bulk load and extract of CSV through the API or a command line tool | Migrations and scheduled batch jobs | Load order matters, since chunks run in parallel |
| Veeva EDC API | /app/cdm/ endpoints for trial data | You read or write subjects, forms, events or queries | The data is CTMS or eTMF |
| Vault AI MCP | An MCP server exposing Vault AI agent actions as tools | An AI assistant must act in Vault, and the customer has Vault AI | The customer does not have Vault AI |
| Certified middleware | Veeva technology partners with tested connectors | You already run an integration platform | The connector does not cover the endpoints you need |
| VAPIL and Postman | Veeva's Java library and a Postman collection per GA version | Java builds, and trying calls before you code | You need EDC calls in Postman (not included) |
REST API and VQL
Every call goes to https://{vaultDNS}/api/{version}/.... Reads of many records use VQL: you send a query such as SELECT id, name__v FROM study__v WHERE modified_date__v > '2026-11-01T00:00:00.000Z' as the form field q. Writes use the object, document and user endpoints. Results come back as JSON or CSV.
Vault Java SDK and Spark messaging
The Vault Java SDK runs your Java code inside the customer's Vault: record, document type and role triggers, record and document actions, custom APIs, job processors and message processors. Spark messaging is Veeva's asynchronous, near real-time message system. A trigger places a signed message in an outbound queue, and the queue delivers it in first-in, first-out order over a Connection, either to another Vault or to an outside HTTPS URL. Failures show up as User Exception Messages in the Vault. Veeva does not publish a delivery guarantee, so the receiving side must accept the same message twice without harm.
Vault Connections
Standard Veeva Connections link Vault applications in the same domain, for example Clinical Operations to EDC, Safety to EDC, Quality to RIM and RIM to Clinical Operations. Veeva describes them as near real time, ideally about ten minutes. If both ends of your flow are Veeva, check for a standard connection before you build one.
Direct Data API
Direct Data API publishes read-only files of objects, documents, picklists, workflows and audit logs. It is off by default, it is not configurable, and Veeva says it is not designed for real-time integration. Section 7 shows the full export loop.
Vault Loader
Vault Loader loads and extracts CSV files through POST /api/{version}/services/loader/load and /services/loader/extract, up to 10 data objects per request. Veeva recommends the Loader API or the Loader command line tool for bulk work because it handles batching and error reports.
Veeva EDC API
The EDC API is a separate reference with its own limits: 1,000 records per retrieve page, 100 subjects created per call, 25 forms with up to 100 items each per set data call, and 20 logins per minute. It needs the CDMS application in the Vault.
Vault AI MCP
The Vault AI MCP server takes JSON-RPC 2.0 calls at POST /api/ai/mcp and exposes each agent action the user is allowed to run as a tool. It accepts API access tokens only and needs the API Access and Agents: Execute permissions. Veeva recommends Claude Code as the client.
iPaaS and middleware
Veeva lists certified middleware technology partners. A middleware platform saves you the plumbing (scheduling, retries, mapping screens). It still calls the same Vault API and lives under the same limits, so the rules in section 9 apply.
How do you get access to the Veeva Vault API?
The Veeva customer gives you access. Its Vault admin creates an integration user with the API Access permission, and you authenticate against that customer's Vault host. There is no developer key that works across customers.
Who does what
| Party | What they do |
|---|---|
| Sponsor or CRO (the Veeva customer) | Owns the Vault and the data, approves the integration, signs off validation |
| Customer Vault admin | Creates the integration user, security profile, permission set and study roles, and creates sandboxes |
| Your integration team | Builds against a sandbox, runs retries, logs and alerts |
| Customer quality or validation team | Tests in the sandbox and approves each release |
| Veeva | Runs the platform and ships three releases a year |
Three ways to authenticate
- API access token. Veeva recommends it. The value starts with
veeva-vault-and goes in anAuthorization: Bearerheader. It works for one Vault only and gives no UI access. A user can hold up to 25 active tokens, and the value is shown once. - User name and password.
POST /api/{version}/authreturns a session ID. - OAuth 2.0 / OpenID Connect. Used where the Vault requires single sign-on, and Veeva says SSO rules apply to integration users too. The call goes to
login.veevavault.com.
If you sell to many sponsors
Every customer has its own Vault, host and users, so you repeat the set-up per customer. Veeva runs an AI Partner Program that gives select partners a Vault, Direct Data API access, training and support. Veeva publishes no general partner application process for API vendors.
How do you build a Veeva Vault API integration, step by step?
The build runs in nine steps: integration user, permissions, authentication, version pinning, sandbox, first calls, validation, deployment and go-live. The code below is our own example unless it says it is Veeva's sample.
Step 1. Ask for a dedicated integration user
Ask the customer's Vault admin for one user per integration, not a person's login. Give it a Client ID name you will send on every call. Veeva logs calls by Client ID, and calls without one are logged as unknown.
For Veeva EDC, Veeva's best practice is a security policy with no password expiration and the setting "Ignore LMS Status, Assume Trained" on the user. Without that setting the user does not see the study.
Step 2. Set the security profile and permissions
The security profile and permission set decide what the user can do. API Access lets the user call the API. Without it, login still works but every other call returns INSUFFICIENT_ACCESS. Grant read and write on the objects and document types you listed in section 3, and nothing else.
For EDC, the CDMS API Read Write role grants API Access, View Casebook and Data Entry, which the form data endpoints need. The user also needs a study role on each study.
Step 3. Authenticate and check the Vault
Use an access token where you can. If you use a session, here is Veeva's sample request and response from the v26.2 reference:
curl -X POST https://myvault.veevavault.com/api/v26.2/auth \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "username={username}&password={password}"
{
"responseStatus": "SUCCESS",
"sessionId": "3B3C45FD240E26F0C3DB4F82BBB0C15C7EFE4B29...",
"userId": 12021,
"vaultIds": [
{ "id": 1776, "name": "PromoMats", "url": "https://promomats-veevapharm.veevavault.com/api" },
{ "id": 1777, "name": "eTMF", "url": "https://etmf-veevapharm.veevavault.com/api" },
{ "id": 1779, "name": "QualityDocs", "url": "https://qualitydocs-veevapharm.veevavault.com/api" }
],
"vaultId": 1776
}
Compare vaultId with the Vault you meant. If the host is wrong for the user, Vault logs you in to the user's most relevant Vault instead of failing. Store the session ID in a field that holds 1,024 characters, reuse it, and call POST /api/{version}/keep-alive while you work. A session lasts 48 hours at most.
Step 4. Pin the API version
Call GET /api/ for the supported versions and pin a GA version in config. Only the newest version, the Beta, changes. Older versions stay fixed, and new features need a newer version. Never pin the Beta in production.
Step 5. Work in a sandbox
Sandbox Vaults are Veeva's place for development, UAT and validation testing. The customer admin creates or refreshes one with POST /api/{version}/objects/sandbox, choosing a size from Small to Full. Access tokens are not copied into a new sandbox, so generate a fresh one there. Beta versions only run on pre-release or limited release Vaults.
Step 6. Make the first calls
Read reference data first. Here is a VQL read with an access token and a Client ID:
curl -X POST "https://myvault.veevavault.com/api/v26.2/query" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "X-VaultAPI-ClientID: acme-clinops-ctms-server-sitesync" \
-H "Accept: application/json" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "q=SELECT id, name__v, modified_date__v FROM study__v"
The response holds responseStatus, a responseDetails block with pagesize, pageoffset, size and total, and the data array.
The same read in Python, following every page. Veeva recommends the next_page URL over PAGEOFFSET, and calls it with POST:
import requests
BASE = "https://myvault.veevavault.com"
S = requests.Session()
S.headers.update({
"Authorization": "Bearer " + ACCESS_TOKEN,
"X-VaultAPI-ClientID": "acme-clinops-ctms-server-sitesync",
"Accept": "application/json",
})
def vql(q):
r = S.post(f"{BASE}/api/v26.2/query", data={"q": q}).json()
while True:
if r["responseStatus"] != "SUCCESS":
raise RuntimeError(r.get("errors"))
yield from r["data"]
nxt = r["responseDetails"].get("next_page")
if not nxt:
break
r = S.post(BASE + nxt).json()
for study in vql("SELECT id, name__v FROM study__v ORDER BY id"):
print(study["id"], study["name__v"])
And in Java with the JDK's own HTTP client. Veeva also points Java teams to its Vault API Library (VAPIL).
HttpClient http = HttpClient.newHttpClient();
String q = "q=" + URLEncoder.encode("SELECT id, name__v FROM study__v", StandardCharsets.UTF_8);
HttpRequest req = HttpRequest.newBuilder(URI.create("https://myvault.veevavault.com/api/v26.2/query"))
.header("Authorization", "Bearer " + accessToken)
.header("X-VaultAPI-ClientID", "acme-clinops-ctms-server-sitesync")
.header("Content-Type", "application/x-www-form-urlencoded")
.header("Accept", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(q))
.build();
HttpResponse<String> res = http.send(req, HttpResponse.BodyHandlers.ofString());
// Vault answers HTTP 200 even on failure. Parse responseStatus before using data.
For EDC, read the study design and check that the subject and form exist before you write. GET /api/{version}/app/cdm/design/form_def returns form definitions, and GET /api/{version}/app/cdm/forms returns forms for one subject and event.
Step 7. Write records
For CTMS and other Vault objects, upsert on an external ID so a retry cannot create a duplicate. Section 9 shows the full pattern. For eTMF, create documents with POST /api/{version}/objects/documents.
For EDC, the combination call sets form data. Veeva's sample request:
curl -L -X POST 'https://my-vault.veevavault.com/api/{version}/app/cdm/forms/actions/setdata' \
-H 'Content-Type: application/json' \
-H 'Authorization: {SESSION_ID}' \
-d '{
"study_name": "ABC-XYZ-001_DEV1",
"reopen": true,
"submit": true,
"change_reason": "Integration Update",
"form": {
"site": "001",
"subject": "101-103",
"eventgroup_name": "egSCR",
"eventgroup_sequence": 1,
"event_name": "evSCR",
"form_name": "DM",
"form_sequence": 1,
"itemgroups": [
{
"itemgroup_name": "igBASE_DM",
"itemgroup_sequence": 1,
"items": [
{ "item_name": "BIRTHYR", "value": "1976" },
{ "item_name": "SEX", "value": "M" }
]
}
]
}
}'
And the shortened response:
{
"responseStatus": "SUCCESS",
"externally_owned": true,
"form": {
"id": "OPT000000000507",
"form_status": "submitted__v",
"itemgroups": [
{
"responseStatus": "SUCCESS",
"itemgroup_name": "igBASE_DM",
"items": [
{ "responseStatus": "SUCCESS", "item_name": "BIRTHYR", "value": "1976" },
{ "responseStatus": "SUCCESS", "item_name": "SEX", "value": "M" }
]
}
]
}
}
Set data does not create events. If the visit does not exist yet, create it first with POST /api/{version}/app/cdm/events or the event group endpoints, then set its date with POST /api/{version}/app/cdm/events/actions/setdate. Veeva's failure sample shows a bad codelist value: the status is FAILURE with "[Codelist Item Definition] with name [MM] not found", and the form is left in in_progress_post_submit__v.
Step 8. Validate and package
Test every flow in the sandbox against the customer's test scripts, and keep the evidence. Configuration and Java SDK code move between Vaults as a Vault package (VPK). The endpoints: export POST /api/{version}/services/package, import PUT /api/{version}/services/package, validate POST /api/{version}/services/package/actions/validate (up to 2 GB, without importing) and deploy POST /api/{version}/vobject/vault_package__v/{package_id}/actions/deploy. A failed deploy stops but does not roll back what it already changed, so validate first. An SDK package holds at most 1,000 Java source files or 50 MB. Vault Compare and the Configuration Report help you show that sandbox and production match.
Step 9. Go live
Generate a new access token in production, since tokens do not follow a promotion. Run a small first batch, check every inner status, then turn on the schedule. Watch the burst headers and your error counts for the first two weeks. Tell the customer's admin the Client ID so they can find your calls in their logs.
How do you export data from Veeva Vault?
Use Direct Data API for a full copy of a Vault, VQL for filtered reads, Vault Loader for CSV extracts of chosen objects, and the Study Data Extract job for Veeva EDC. All four are read-only and none is real time.
Direct Data API: full, incremental and log files
Turn it on in the customer's Vault under Admin > Settings > General Settings. Then:
| File | When Veeva publishes it | Kept for |
|---|---|---|
| Full | Once a day at 01:00 Vault time, everything since Jan 1, 2000 | 2 days |
| Incremental | Every 15 minutes, published 15 minutes after its stop time (96 a day) | 10 days |
| Log | Once a day | 2 days |
The loop is: list files with GET /api/{version}/services/directdata/files?extract_type=incremental_directdata&start_time=..., download each part with GET /api/{version}/services/directdata/files/{name}, check each part's MD5, read manifest.csv and metadata.csv, apply the update files, then apply the _deletes.csv files. Files over 1 GB come in numbered parts. Skip files with record_count 0. A row in a delete file means the row should no longer exist in your copy, which is not always a delete in Vault. Upversioning a document, for example, puts the old version row in document_version__sys_deletes.csv.
import hashlib, pathlib
def pull_incremental(since, until):
r = S.get(f"{BASE}/api/v26.2/services/directdata/files",
params={"extract_type": "incremental_directdata",
"start_time": since, "stop_time": until}).json()
for f in r["data"]:
if f.get("record_count") == 0:
continue
for part in f["filepart_details"]:
blob = S.get(BASE + part["url"]).content
if hashlib.md5(blob).hexdigest() != part["md5checksum"]:
raise RuntimeError("checksum mismatch " + part["name"])
pathlib.Path("landing", part["name"]).write_bytes(blob)
save_checkpoint(until) # only after every part landed
The checkpoint is the stop time of the last file you applied in full. If a run fails, the next run starts from the same checkpoint and loads the same files again, so load into staging tables keyed on the record ID. The incremental files are kept 10 days, which is your outage budget before you must reload from a Full file.
VQL paging for filtered reads
VQL returns at most 1,000 object records or 200 documents per page. Follow next_page, which stays active for about 72 hours from the last call, though Veeva does not guarantee it. Add ORDER BY for a fixed order. Vault can shrink the page size for large results, so never compute offsets yourself. For change tracking, filter on modified_date__v and handle deletes on their own path, as Veeva's integration patterns say.
Vault Loader extract
POST /api/{version}/services/loader/extract takes up to 10 objects, each with its fields and an optional vql_criteria__v. It returns a job ID. Poll GET /api/{version}/services/jobs/{job_id} no more than once every 10 seconds, then fetch each task's CSV from /services/loader/{job_id}/tasks/{task_id}/results. A blank result means the task failed.
Veeva EDC: Study Data Extract
Direct Data API does not cover Veeva EDC. Start a Study Data Extract with POST /api/{version}/app/cdm/jobs/start_now and job_type: study_data_extract__v, choose CSV, SAS or XPT, and pick the datasets you need, such as SYS_SUB and SYS_FORM. The job can deliver to FTP or S3. Poll GET /api/{version}/app/cdm/jobs/{job_id}, then download /file/content. The download link lasts 30 days. Only one job of a type runs at a time, and Veeva warns that a completed job can still have problems, so read the job log too.
The extract has no "changed since" option. For near-live EDC changes, read subjects and queries with last_modified_date, and keep the extract for full snapshots.
Scheduling
A pattern that fits the published timings (our guidance): incremental Direct Data every 15 to 30 minutes, a Full file once a week to check row counts, VQL deltas every few minutes for the handful of objects that need fresher data, and an EDC extract nightly. Keep every schedule inside the burst limit, which all of these calls share.
How do you connect Veeva Vault to an EHR, other EDCs and a warehouse?
Put one integration hub in the middle. Each system connects once to the hub, the hub keeps the ID map, and Vault is one of several endpoints. This is our engineering guidance. Veeva's documents cover the Vault side only.
Hub architecture
The hub has four parts: an inbound adapter per system, a queue, an ID map table and an audit log. Adapters translate each system's record into a shared shape, the queue absorbs bursts and outages, and the audit log records every call and every inner status for the validation team.
ID mapping
Each system keeps its own IDs. A Veeva CTMS site has a Vault record ID, the EDC site has a site number, the EHR has a facility code and Medidata Rave has its own site ID. Store all of them in one map row. On the Vault side, write your ID into external_id__v and upsert on it, so the map survives a lost response. Veeva's integration patterns name external_id__v for this.
EHR to Veeva EDC
Veeva's developer documents describe no EHR connector for Veeva EDC. Veeva describes Veeva eSource as a FHIR-based way to move EHR data to the sponsor EDC, and publishes no API or launch date for it. Today, a site-side system that holds EHR data writes to EDC forms through the EDC API, as in step 7. Map each FHIR resource field to an EDC item name from the study design, and keep the mapping per casebook version. For the FHIR side, see our FHIR integration services.
Veeva EDC next to Medidata Rave and REDCap
Many sponsors run more than one EDC across a portfolio. Each vendor has a different API and data model, so give each one its own adapter and map them to one study data shape in the hub. Our Medidata Rave EDC integration guide and REDCap API guide cover the other two sides.
Veeva CTMS with a non-Veeva EDC
If the EDC is Veeva, use the standard Clinical Operations to EDC connection: EDC creates the matching subject in CTMS and sends subject milestones, visit definitions and SDV data, and site closeout PDFs go to eTMF. If the EDC is not Veeva, your hub does that job: read subjects and visits from the EDC and upsert subject and visit records into CTMS on external IDs.
Warehouse
Land Direct Data files and EDC extracts in raw form, then build modelled tables. Keep metadata.csv with each load, because the Vault data model changes when the customer changes configuration.
Many Vaults
One user can reach several Vaults in a domain, and the auth response lists them in vaultIds. Standard Veeva Connections need the Vaults to share a domain. Across domains, or for your own flows between Vaults, use Spark messaging with a Vault to Vault connection, or treat each Vault as its own endpoint in the hub. A domain admin can list the domain's Vaults with GET /api/{version}/objects/domain.
How do you make a Veeva Vault integration reliable?
Read the burst headers, upsert on an external ID, check every inner status, retry only what failed with backoff, poll jobs no faster than Veeva allows, and refresh sessions before they expire. Veeva's own best practice names exponential backoff and idempotency keys.
Burst limits and headers
Vault counts calls in a fixed 5-minute window. Veeva's example limit is 2,000, and each Vault's real limit can differ. Every response carries X-VaultAPI-BurstLimit and X-VaultAPI-BurstLimitRemaining. Past the limit, Vault slows responses and sends X-VaultAPI-ResponseDelay in milliseconds. Since v21.1, Vault sets no daily limit. Auth calls have their own per-minute limit, and EDC locks the account after too many logins, which only an admin password reset clears.
A simple rule (our guidance): when BurstLimitRemaining drops under 10% of the limit, pause new work until the window resets, and never log in per request.
Vault returns HTTP 200 on failure
Vault answers HTTP 200 and reports the result in responseStatus: SUCCESS, WARNING, FAILURE or EXCEPTION. Bulk calls also return a status per record in input order, and an outer SUCCESS can hold record failures. Key your logic on the error type, because Veeva says error messages are not contractual.
| Error type | What it means | What to do (our guidance) |
|---|---|---|
INVALID_SESSION_ID | Session expired or bad | Log in again once, then retry the call |
API_LIMIT_EXCEEDED | Over a limit, such as job polling | Wait, then retry with backoff |
RACE_CONDITION | Another call updated the same record at the same time | Retry with backoff |
OPERATION_IN_PROGRESS | A conflicting operation is running | Retry later |
INVALID_DATA, PARAMETER_REQUIRED | Your payload is wrong | Do not retry. Fix and send to a review queue |
INSUFFICIENT_ACCESS, OPERATION_NOT_ALLOWED | Permissions or state | Do not retry. Raise with the Vault admin |
Idempotent creates with upsert
Add idParam=external_id__v (or any field marked unique) to the object endpoint. Vault creates the record if the ID is new and updates it if it exists, and tells you which in event: created__sys or updated__sys. A record with no changes returns WARNING. Two rows with the same ID in one request fail the whole batch, so dedupe before you send.
import random, time
def upsert(obj, rows, attempt=0):
r = S.post(f"{BASE}/api/v26.2/vobjects/{obj}",
params={"idParam": "external_id__v"},
json=rows).json()
if r["responseStatus"] == "FAILURE":
if r["errors"][0]["type"] in ("API_LIMIT_EXCEEDED", "RACE_CONDITION") and attempt < 5:
time.sleep(min(60, 2 ** attempt) + random.random())
return upsert(obj, rows, attempt + 1)
raise RuntimeError(r["errors"])
retry, review = [], []
for row, res in zip(rows, r["data"]): # same order as the input
if res["responseStatus"] == "FAILURE":
kind = res["errors"][0]["type"]
(retry if kind == "RACE_CONDITION" else review).append(row)
if retry and attempt < 5:
time.sleep(min(60, 2 ** attempt) + random.random())
upsert(obj, retry, attempt + 1)
send_to_review_queue(review)
Partial batch failures
Veeva EDC is stricter about this. Its best practice says not to resend an uninspected bulk payload, because that re-executes data that already saved. Queue and retry only the records that returned a failure. With EDC Audit 2.0 Live Capture, phased in from 26R2, valid subjects commit and only the failed subject rolls back. Subjects have no upsert, and creating one that exists returns "[Subject] with name [subject] exists", so treat that error as success after a timeout.
Job polling
Poll GET /api/{version}/services/jobs/{job_id} no more than once every 10 seconds, or you get API_LIMIT_EXCEEDED. Treat SUCCESS as done and ERRORS_ENCOUNTERED, CANCELLED, TIMEOUT and MISSED_SCHEDULE as alerts. Then read the job's results and log, since a finished job can still hold failed rows.
Session expiry
The Vault admin sets the idle timeout, and a session lasts 48 hours at most. EDC sessions default to 20 minutes. Reuse one session, call keep-alive while busy, and log in again only on INVALID_SESSION_ID.
Monitoring
Track, per Vault and per flow: calls per window against the burst limit, inner failure counts by error type, records waiting in the review queue, the age of the last applied Direct Data file, and job durations. Log X-VaultAPI-ExecutionId with every failure, because Veeva support asks for it. During a Vault upgrade, responses carry X-VaultAPI-DowntimeExpectedDurationMinutes, so pause and resume after it.
What is not possible with the Veeva Vault API?
- One key for all customers. Each Vault has its own host, users and tokens. Set up access per customer.
- Real-time reads from Direct Data API. Veeva says it is not designed for real-time integration. Use the REST API for live reads.
- Direct Data API for Veeva EDC. EDC uses the Study Data Extract job instead.
- Webhooks from the REST API. Veeva documents no webhook feature for outside systems. Outbound notices need Vault Java SDK code with Spark or an HTTP callout, or a scheduled pull on
modified_date__v. - Rollback across combined EDC steps. Earlier steps stay done when an item fails inside
setdata, and the form can be left reopened. - Locking, freezing or releasing EDC data by API. Veeva says these are human decisions by design.
- Creating EDC sites by API. The EDC API reads sites but has no create endpoint.
- A published EHR-to-EDC route. See section 8.
What are the Veeva Vault API limits?
| Limit | Value Veeva publishes |
|---|---|
| Burst limit | Calls per fixed 5-minute window. Veeva's example is 2,000. Responses slow down once you reach it. |
| Auth calls | Counted per 1-minute window. Veeva's example is 20. Delays start at 50%, then auth calls fail. |
| EDC logins | 20 per minute. The account can be locked out. |
| Job status polling | Once every 10 seconds, else API_LIMIT_EXCEEDED. |
| Daily limit | None since v21.1. |
| Object records | 500 per create or upsert call, 50 MB input file. |
| Documents | 4GB per single upload, 500 per batch call. |
| VQL | Query text up to 50,000 characters. 1,000 objects or 200 documents per page. |
| Vault Loader | 10 data objects per request, processed in chunks of 500. |
| Direct Data files | Incremental kept 10 days, Full and Log kept 2 days. |
| EDC retrieve | 1,000 records per page. |
| EDC writes | 100 subjects created, 10 updated, 25 forms with up to 100 items each per call. |
| EDC concurrency | 20 threads at most per integration. |
| Session | Idle timeout set by the Vault admin, 48 hours at most. |
What are the common Veeva Vault blockers, and how do you clear them?
Access, releases, limits, validation, sandboxes and permissions are the blockers that Veeva's own documents point to. Each one has a fix.
No access to the customer's Vault
You cannot start without the customer's admin. Fix: send the admin a one-page request on day one with the integration user name, Client ID, the objects and document types with read or write, the EDC study roles, and a sandbox request. Ask whether the Vault uses single sign-on, because then you need OAuth.
Three releases a year
Veeva ships three general releases a year, each with a new API version, and limited release features land in the Beta API first. Fix: pin a GA version, run your regression suite on the customer's pre-release Vault in the weeks before each release, and plan one version upgrade a year.
Version retirement
Veeva publishes no end-of-life date for old API versions. Fix: record the pinned version per customer, check GET /api/ each release, and move up before your version falls far behind.
Limits
Busy Vaults share the burst limit with every other integration. Fix: batch to 500, read the burst headers, spread schedules, and ask the admin for the Vault's real limit.
GxP validation
Clinical and quality Vaults are usually under GxP rules, and the customer validates changes before production (our guidance, from how regulated customers work). Veeva names sandboxes as the place for validation testing. Fix: write test scripts per flow, run them in the sandbox, keep the evidence, and move code by VPK so the same package reaches production.
Sandbox drift
A sandbox that is months old no longer matches production configuration, and tokens do not carry over when it is refreshed. Fix: ask for a refresh before each test cycle, generate new tokens after it, and compare configuration with Vault Compare.
Permissions
Missing permissions show up as INSUFFICIENT_ACCESS, or as an EDC study that seems not to exist because of LMS training rules. Fix: test every endpoint with the real integration user in the sandbox, and set "Ignore LMS Status, Assume Trained" for EDC.
How do you handle mid-study amendments, migrations and other scenarios?
Mid-study amendments in Veeva EDC
A subject gets the casebook version that is active at its site, and during an amendment a subject, a site or the whole study can move to the next version. Design writes only apply to the latest version. Fix: re-read the design endpoints on every run, key your item mapping on casebook version, and hold writes for any form that is not in the subject's version.
Migrating from another EDC or CTMS
For CTMS, Veeva recommends Study Migration Mode for every migration: set study_migration__v to m__v before loading other data, or switch many studies with POST /api/{version}/app/clinical/studies/actions/enable_migration_mode. Standard Vault Connections skip studies in migration, so switch it off when you finish. For objects, the X-VaultAPI-MigrationMode header lets you load records in later lifecycle states and needs the Record Migration permission. Documents have a matching Document Migration permission. Load with Vault Loader and keep the old system's ID in external_id__v.
For EDC migrations, check the EDC user upload and design endpoints before you plan, since sites cannot be created by API.
A Vault release breaks an integration
Pinned versions do not change, so a break usually comes from configuration changes, new required fields or new validation rules. Fix: run your sandbox suite on the pre-release Vault, alert on new error types, and read the release notes for each application you touch.
Multi-region
Each Vault has its own host, and Veeva publishes nothing on regional API differences. Fix (our guidance): treat each regional Vault as its own endpoint in the hub, with its own token, limits and schedule, and keep data residency rules in the hub's routing.
Data corrections
When a value is wrong in EDC, write the correct value through setdata with a change_reason, so the audit trail shows why. Locked or frozen forms cannot be changed by API. Ask the study team to lift the lock. In CTMS, upsert the corrected record on its external ID. For a warehouse, the next Direct Data incremental carries the change.
How much does Veeva Vault integration cost, and how long does it take?
Veeva publishes no fee for Vault API access, sandboxes or a partner program. Direct Data API is included for no additional license fee as part of Vault Platform, as Veeva announced on Feb 27, 2025. In the same announcement Veeva says Direct Data API makes Vault data accessible up to 100 times faster than traditional APIs.
Veeva publishes no timeline for access, partner approval or go-live. Each customer runs its own user set-up and validation. Ask the customer who creates the API user, whether LMS rules apply to it, and when a sandbox can be refreshed for your tests.
Which Veeva Vault API quirks should you know?
These come from Veeva's own pages. Check each one in the customer's Vault.
A wrong host still logs you in
Auth falls back to the user's most relevant Vault, so always check vaultId.
HTTP 200 on failure
Read responseStatus and each record's status.
Old versions never change
New features need a newer version, so plan an upgrade.
Outer SUCCESS can hide inner FAILURE
EDC bulk calls return a status per entry. Check every one.
EDC commit rules changed in 26R2
With Audit 2.0 Live Capture, valid subjects commit and only failed subjects roll back.
Values become read-only at the site
externally_owned defaults to true in setdata.
Training blocks the API user
Without "Ignore LMS Status, Assume Trained" the user cannot see the study.
Tokens do not follow sandboxes
A new sandbox and a promotion to production both drop access tokens.
Delete files are not always deletes
A Direct Data delete row can be an old document version.
Single thread for subjects
Create Subjects takes a study-level lock.
Loader order is not fixed
Records load in parallel chunks of 500.
Duplicate upsert IDs fail the batch
One repeated idParam value fails all 500 rows.
What should you check before you sign a Veeva integration?
- Is API use and a sandbox part of the customer's Vault license?
- Which API version does the customer's validation cover?
- Is Direct Data API on, and which files do we get?
- Does a standard Veeva Connection already cover our flow?
- Who creates the API user, and which permission set and study role does it get?
- Does the Vault use single sign-on, so we need OAuth?
- What is this Vault's burst limit, and what else shares it?
- Can our Java SDK code be deployed and validated in this Vault?
What is the next step for a Veeva Vault integration?
A Veeva integration usually spans more than one Vault application and more than one source system. If you are scoping one, start with the Vault applications in scope and where the data starts. See our EHR and EMR integration services.
Ready to scale?
Talk to our healthcare engineering team about building, integrating, and shipping faster.
Frequently Asked Questions
Does Veeva Vault have an API?
What is the current Veeva Vault API version?
How do I authenticate to the Vault API?
What is the Veeva Vault API rate limit?
How do I avoid duplicate records when I retry?
Can I write data into Veeva EDC forms through the API?
Does the Vault API cover Veeva CTMS and eTMF?
How do I export Veeva EDC data?
What is Veeva Direct Data API?
What is VQL in Veeva Vault?
Does Veeva Vault send webhooks?
Does Veeva Vault have an MCP server for AI agents?
Can EHR data go straight into Veeva EDC?


