How do I connect a REST API source?

Overview

The REST API connector letsLets you pull data from any external system that exposeswith a REST API —(ERP, ERPs,CRM, CRMs,HRMS, HRMSIoT). platforms, IoT feeds, or any web service that returns JSON, CSV, XML, or NDJSON responses. Unlike a one-time file upload, an API connection can syncSyncs automatically on a schedule, so— your dashboards always reflect the latest data withoutno manual re-uploads.

uploads

Vantageneeded. connects to the API usingUses a Connection → Dataset → Run model. You set up the connection once (base URL, credentials), then definemodel: one connection, multiple datasets, each sync tracked as a run.

When to Use

Use this feature when:

• You want live data from a CRM, ERP, HRMS, or moreIoT datasetsplatform
• You need dashboards to update automatically on a schedule
• The API supports incremental updates (eachcursor aor date filter)
• You want to combine external data with Converse forms

Concepts

• Connection – Saved link to an external API with base URL and encrypted credentials
• Dataset – A specific API endpoint with its own schedule, pagination, and column mapping). Each sync creates a run record so you can track history, spot failures, and retry if needed.

  When to Use

  Set up a REST API connection when you need to:

  • Pull live data from an external system — Your data lives in a CRM, ERP, HRMS, or IoT platform that provides a REST API, and you want it in Vantage without exporting files.mapping
  • Keep dashboards up to date automatically — The data changes frequently (daily, hourly) and you need Vantage to sync on a schedule rather than relying on manual uploads.
  • Bring in incremental updates — The API supports a cursor or date-based filter, so each sync pulls only new or changed records instead of re-downloading everything.
  • Combine external data with internal forms — You want to join API-sourced data with Converse form submissions or other Vantage sources using relationships.

  Concepts

  Connection – A saved link to an external API, storing the base URL and encrypted credentials (API key, token, or basic auth). One connection can have multiple datasets.

  Dataset – A specific API endpoint within a connection. Each dataset has its own URL path, request parameters, sync schedule, pagination settings, and column mapping. Each dataset becomes a separate data source in Vantage.

  Run – A single executionsync ofexecution; atracked datasetas sync. Vantage records the status of every run (running, success, partial, or failed)failed

so you can track sync history and diagnose issues.
• Sync Schedule – How often a dataset pullssyncs fresh data. You can set an— interval in minutes (minimum 5 minutes) or a cron expression
for precise timing (e.g., every weekday at 8 AM). You can also choose a time zone for your schedule.
• Cursor – A high-High-water mark that tracks the last successfully synced record.record Onfor each sync, Vantage sends the cursor value to the API so it returns only new or changed records. The cursor advances only on a successfulincremental sync
— a failed run does not skip any data.
• Date Tokens – Placeholders like {today}, {yesterday}, {today-7d}, or {month_start}yesterday} that you can use in request parameters. Vantage resolves them to actual datesresolved at sync time,time
so your API call always fetches the right time window.
• Pagination – The methodHow Vantage uses to walk throughwalks multi-page API responses.responses Supported styles include page number,(page, offset, cursor, link headerheader)
(RFC 5988), and no pagination.
• Import Strategy – HowAppend, Replace, or Upsert — how new data is written into the datasource
source. Append adds rows to existing data. Replace clears the table and reloads from the API response. Upsert updates existing rows by a key field and inserts new ones.
• Auto-Disable – AfterDataset disables itself after 5 consecutive failed syncs,syncs
Vantage automatically disables the dataset to prevent repeated errors. You can review the failures, fix the issue, and re-enable the dataset.

Set Up Guide

Open Vantage from the Vantage Dashboard widget on the Home Page.

1. OpenGo the Data Sources screen — In the Vantage sidebar, clickto Data Sources.
2. Start a new API connection — Click + Add Source and→ select API Connection as the connector type. The API connection setup wizard opens.
3. Enter the base URL — Type the base URL of the external API (e.g., https://api.example.com/v1). This is the root address that all datasets in this connection will share.
4. Add credentials — Enter the authentication details the API requires — (API key, bearer token, or basic auth (username and password). Credentials are encrypted and stored securely. You will not be able to view them again after saving, only update them.auth)
5. Save the connection — Click Save. Theto create the connection is now created and ready for datasets.
6. Add a dataset — Click + Add Dataset within→ the connection. Enterenter the endpoint path (e.g., /sales/daily), request method (GET or POST), and any query parameters or request body. Use date tokens like {today} or {yesterday} in parameters if the API supports date filtering.
7. Configure pagination — Select the pagination style the API uses (page number, offset, cursor, link header, or none). Set the page size if applicable.
8. Set the sync schedule — Choose how often this dataset should sync — an (interval in minutes or acron) cron expression. Select yourand time zone. You can also leave it on manual-only and click Run Now whenever you want to sync.zone
9. Choose the import strategy — Select (Append, Replace, or Upsert. If using Upsert, specify the key field that identifies each record.Upsert)
10. Review the column mapping
11. Click Save — After the first sync runs, Vantage detects the columns and data types from the API response. Review and adjust as needed.
12. Save the dataset — Click Save. The first sync runs automatically, and the data source is ready for use in dashboards.automatically

Best Practices

• Use a cursor or date token for incremental sync
so each run pulls only new data instead of re-downloading everything. Set
• Match the sync schedule to match how often the source data actually changes
— syncing every 5 minutes for data that updates daily wastes resources. Always test
• Test with a Run Now before enabling a schedule
to confirm the API responds correctly and columns map as expected.
• Use Replace for full-snapshot APIs andAPIs, Upsert for APIs that return changed-records-only changedAPIs
records.
• Keep the base URL and credentials at the connection level —so ifrotation the API key rotates, you update it once andupdates all datasets
pick up the change.
• Monitor the Sync Failures page regularly — after 5 consecutive failures auto-disables the dataset
auto-disables and dashboards stop updating. If the API returns large data sets, enable
• Enable pagination and setwith a reasonable page size tofor avoidlarge timeouts.
  responses

Related Links / FAQs

Related pages in this book:

• How do I connect an Excel or CSV file as a data source?
• How do I connect internal Converse forms as a data source?
• How do I view and edit data in a source?
• How do I create a relationship between data sources?

FAQs

What response formats doesare the API connector support? supported?
JSON, NDJSON (newline-delimited JSON),NDJSON, XML, CSV, and TSV. Vantage can also auto-detect the format from the Content-Type header.

Can I connect to an API that requires OAuth?
TheOnly connectorvia supportsa APItoken key,— bearer token, and basic auth.browser-redirect OAuth flows thataren't require a browser redirect are not supported directly — use a token from your OAuth provider.supported.

What happens if a sync fails?
The run is recorded asmarked failed and the cursor isdoesn't notadvance; advanced, so no data is skipped. Afterafter 5 consecutive failures the dataset is automatically disabled. You can fix the issue, re-enable the dataset, and retry.auto-disables.

Can I have multiple datasets on one connection?
Yes.Yes Each— datasetthey pointsshare tothe abase different endpointURL and credentials but each has its own schedule, pagination,schedule and import strategy, but they all share the same base URL and credentials.settings.

What are date tokens?
Placeholders like {today}, {yesterday}, {today-7d},or {month_start} that resolve to real dates at sync time. Use them in query parameters so each sync automatically fetches the correct time window.

Version Notes

Last Updated: Oct 2026