How do I connect a REST API source?

The REST API connector lets you pull data from anany external HTTPsystem endpointthat intoexposes Vantage.a YouREST provideAPI — 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 URL,latest authenticationdata details,without andmanual are-uploads.

Vantage pathconnects 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 arrayfrom 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 responseright andtime ingests the results into ClickHouse like any other source.window.

The API connector currently supports manual sync only. You trigger each pull by clicking "Sync now" in the source settings. Scheduled or automatic API polling is not yet available.

2. When to Use

• When you have an internal or third-party API that returns tabular data in JSON format.
• When you want to bring CRM records, ERP data, or other system data into Vantage for analysis.
• When you need a structured alternative to downloading CSVs and re-uploading them manually.

3. Concepts

• Authentication – Vantage supports three auth methods for API connections: Bearer token, API key, and Basic (username/password).
• Data PathPagination – The JSON path that tellsmethod Vantage whereuses 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 arraysource. livesAppend inadds rows to existing data. Replace clears the table and reloads from the API response. ForUpsert example,updates ifexisting rows by a key field and inserts new ones.

  Auto-Disable – After 5 consecutive failed syncs, Vantage automatically disables the responsedataset isto {"results":prevent [{...},repeated {...}]},errors. You can review the datafailures, pathfix wouldthe beissue, "results"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. ManualStart Synca – Each sync is triggered by an admin clicking "Sync now". The connector fetches the latest data from thenew API and replaces the previous dataset. There is no automatic or scheduled sync.

4. Set Up Guide

Step 1: Add a New Source

1. In Vantage, click Sourcesconnection from— the navigation.
2. Click + Add Source.
3. Selectand select API Connection as the connector type. The API connection setup wizard opens.

Step 2:

Enter the Endpointbase URL

—
1. ProvideType the fullbase URL of the API endpoint that returns your data.

Step 3: Configure Authentication

1. Choose your auth method:
   • Bearer token
   • API key
   • Basic auth (username/password)
2. Enter the credentials.

Step 4: Set the Data Path

1. Specify the JSON path pointing to the data array in the response.

Step 5: Sync

1. Click Sync now to pull the data.
2. Vantage fetches the response, extracts data at the specified path, and ingests it into ClickHouse.

Step 6: Verify

1. Confirm the row count in the Sources listing.
2. Spot-check column values in the source view.

5. Best Practices

• Test yourexternal API endpoint independently (e.g., https://api.example.com/v1). This is the root address that all datasets in Postmanthis connection will share.
• 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.
• Save the connection — Click Save. The connection is now created and ready for datasets.
• 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.
• Configure pagination — Select the pagination style the API uses (page number, offset, cursor, link header, or none). Set the page size if applicable.
• Set the sync schedule — Choose how often this dataset should sync — an interval in minutes or a browser)cron expression. Select your time zone. You can also leave it on manual-only and click Run Now whenever you want to sync.
• Choose the import strategy — Select Append, Replace, or Upsert. If using Upsert, specify the key field that identifies each record.
• Review column mapping — After the first sync runs, Vantage detects the columns and data types from the API response. Review and adjust as needed.
• 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 configuringenabling 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 inonce Vantage.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 yourthe API returns paginatedlarge results,data pointsets, Vantageenable atpagination and set a single-reasonable page or bulk export endpoint.
• Remember to sync manually whenever the upstream data changes — there is no automatic refresh.
• If your API credentials rotate, update them in the source settings promptlysize to avoid failedtimeouts.
  syncs.

6.

Related Links / FAQs

• How do I scheduleconnect automatican APIExcel syncs?
  Notor currently.CSV APIfile sources requireas a manualdata "Syncsource?
now"
• How actiondo eachI time.connect Scheduledinternal pullsConverse areforms planned foras a futuredata release.source?
• How do I view and edit data in a source?
• How do I create a relationship between data sources?

FAQs

Last Updated: 04 SepOct 2026