Skip to main content

How do I connect a REST API source?

Overview

The REST API connector lets you pull data from any external system that exposes a REST API — ERPs, CRMs, HRMS 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 sync automatically on a schedule, so your dashboards always reflect the latest data without manual re-uploads.

Vantage connects to the API using a Connection → Dataset → Run model. You set up the connection once (base URL, credentials), then define one or more datasets (each 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.
  • 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 execution of a dataset sync. Vantage records the status of every run (running, success, partial, or failed) so you can track sync history and diagnose issues.

Sync Schedule – How often a dataset pulls 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-water mark that tracks the last successfully synced record. On each sync, Vantage sends the cursor value to the API so it returns only new or changed records. The cursor advances only on a successful sync — a failed run does not skip any data.

Date Tokens – Placeholders like {today}, {yesterday}, {today-7d}, or {month_start} that you can use in request parameters. Vantage resolves them to actual dates at sync time, so your API call always fetches the right time window.

Pagination – The method Vantage uses to walk through multi-page API responses. Supported styles include page number, offset, cursor, link header (RFC 5988), and no pagination.

Import Strategy – How new data is written into the data 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 – After 5 consecutive failed 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. Open the Data Sources screen — In the Vantage sidebar, click 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.
  5. Save the connection — Click Save. The connection is now created and ready for datasets.
  6. Add a dataset — Click + Add Dataset within the connection. Enter 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 a cron expression. Select your time zone. You can also leave it on manual-only and click Run Now whenever you want to sync.
  9. Choose the import strategy — Select Append, Replace, or Upsert. If using Upsert, specify the key field that identifies each record.
  10. Review column mapping — After the first sync runs, Vantage detects the columns and data types from the API response. Review and adjust as needed.
  11. Save the dataset — Click Save. The first sync runs automatically, and the data source is ready for use in dashboards.

From here you can:

  • Monitor sync history and retry failed runs from the Sync Failures page
  • Create dashboards using this data source
  • Define relationships to join API data with other sources

Best Practices

Use a cursor or date token for incremental sync so each run pulls only new data instead of re-downloading everything. Set 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 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 and Upsert for APIs that return only changed records. Keep the base URL and credentials at the connection level — if the API key rotates, you update it once and all datasets pick up the change. Monitor the Sync Failures page regularly — after 5 consecutive failures the dataset auto-disables and dashboards stop updating. If the API returns large data sets, enable pagination and set a reasonable page size to avoid timeouts.

  • 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 does the API connector support? JSON, NDJSON (newline-delimited JSON), 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? The connector supports API key, bearer token, and basic auth. OAuth flows that require a browser redirect are not supported directly — use a token from your OAuth provider.

What happens if a sync fails? The run is recorded as failed and the cursor is not advanced, so no data is skipped. After 5 consecutive failures the dataset is automatically disabled. You can fix the issue, re-enable the dataset, and retry.

Can I have multiple datasets on one connection? Yes. Each dataset points to a different endpoint and has its own schedule, pagination, and import strategy, but they all share the same base URL and credentials.

What are date tokens? Placeholders like {today}, {yesterday}, {today-7d}, {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

Back to top