Skip to content
Developers
Get an API token

Moving from v3

What changes when you move from the v3 REST API or bulk export to Novi UDM Data (v4).

View MarkdownOpen in Claude(opens in a new tab)

v4 uses Novi’s unified data model and is queried with SQL. v3 and v4 run side by side, so you can move one integration at a time. New datasets and enhancements land in v4.

v3 v4
Interface REST API at /api/v3, one endpoint per resource, JSON responses SQL against views in Snowflake, in the web interface, a driver or BI tool, or over HTTPS through Snowflake’s SQL API
Authentication Access token from the /api/v3/sessions endpoint Snowflake login, programmatic access token, or key pair. See Delivery options
Choosing data A scope parameter selects the dataset on each call You filter, join, and aggregate in SQL and return only the rows and columns you need
Bulk files /api/v3/bulk and /api/v3/bulk-diffs The DOWNLOADS_FULL and DOWNLOADS_DIFF views. See Bulk files
New-file emails Sent when bulk files are ready Not sent yet. Check the views
Canada Available Planned Keep using v3 for Canadian data until then

Each well has a WELL_KEY and each wellbore a WELLBORE_KEY, both built from the regulatory ID, for example US:API10:4212340567 and US:API10:4212340567:0. Production, completions, tests, spacing, and forecasts are per wellbore. See Well identifiers.

Two wellbore columns replace the single v3 well type:

Column Answers Examples
WELLBORE_TYPE_NORMALIZED What the wellbore does PRODUCER, INJECTOR, DISPOSAL, CYCLIC, STORAGE, OBSERVATION_TEST
PRIMARY_STREAM What it produces or handles OIL, GAS, OIL_AND_GAS, WATER, CO2, STEAM, DRY

Both are built from each state’s filed code where Novi recognizes it. The filed code is in WELLBORE_TYPE_REPORTED. Slant is in DIRECTION, for example HORIZONTAL or U_TURN_HORIZONTAL.

Permit, spud, total depth, completion, first production, and plugging dates are events in WELL_EVENT, one timeline per well. WELLBORE_HEADER and WELL_DETAIL still give one row per wellbore with SPUD_DATE, TD_DATE, COMPLETION_DATE, FIRST_PRODUCTION_DATE, and PA_DATE derived from those events.

Forecast volumes are monthly. Forecast cumulative columns add up forecast volumes only, from the first forecast period, and exclude earlier production. To compare with a lifetime cumulative, add historical production from PRODUCTION.

  • STATE is the two-letter USPS code.
  • COUNTY is the county or parish name. COUNTY_CODE is the five-digit FIPS code.
  • Normalized status, type, and slant columns such as STATUS, WELLBORE_TYPE_NORMALIZED, and DIRECTION hold uppercase codes from controlled vocabularies. The _REPORTED columns keep the source’s wording.

All 29 base views have SOURCE_ID, which joins to SOURCE. 22 of them also have CREATED_AT and UPDATED_AT. Use them to trace a value or pick up only what changed.

Planned

A guide that maps each v3 column to its v4 equivalent. Until it is published, ask your Customer Success Advisor for help mapping an existing integration.