How do I connect a REST API source?

Overview

Lets you pull data from any external system with a REST API (ERP, CRM, HRMS, IoT). Syncs automatically on a schedule — no manual re-uploads needed. Uses a Connection → Dataset → Run model: 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 IoT platform
• You need dashboards to update automatically on a schedule
• The API supports incremental updates (cursor or 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 mapping
• Run – A single sync execution; tracked as running, success, partial, or failed
• Sync Schedule – How often a dataset syncs — interval in minutes or a cron expression
• Cursor – High-water mark that tracks the last synced record for incremental sync
• Date Tokens – Placeholders like {today} or {yesterday} resolved at sync time
• Pagination – How Vantage walks multi-page API responses (page, offset, cursor, link header)
• Import Strategy – Append, Replace, or Upsert — how new data is written into the source
• Auto-Disable – Dataset disables itself after 5 consecutive failed syncs

Set Up Guide

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

1. Go to Data Sources
   
2. Click Connect API
   
   
3. Click New 
   
4. Enter the base URL
5. Add credentials (API key, token, or basic auth)
6. Click Save to create the connection
7. Click + Add Dataset → enter the endpoint path and parameters
8. Configure pagination
9. Set the sync schedule (interval or cron) and time zone
10. Choose the import strategy — Append, Replace, or Upsert (Upsert needs a key field, so pick which column uniquely identifies each row)
11. Review the column mapping [TODO: confirm this screen exists — not found in the audit]
12. Click Save — the first sync runs at the next scheduled check (within 5 minutes), or click Run Now to sync immediately

Best Practices

• Use a cursor or date token for incremental sync
• Match the sync schedule to how often the data actually changes
• Test with Run Now before enabling a schedule
• Use Replace for full-snapshot APIs, Upsert for changed-records-only APIs
• Keep credentials at the connection level so rotation updates all datasets
• Monitor Sync Failures — 5 consecutive failures auto-disables the dataset
• Enable pagination with a reasonable page size for large 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 are supported?
JSON, NDJSON, XML, CSV, and TSV.

Can I connect to an API that requires OAuth?
Only via a token — browser-redirect OAuth flows aren't supported.

What happens if a sync fails?
The run is marked failed and the cursor doesn't advance; after 5 consecutive failures the dataset auto-disables.

Can I have multiple datasets on one connection?
Yes — they share the base URL and credentials but each has its own schedule and settings.

What are date tokens?
Placeholders like {today} or {month_start} that resolve to real dates at sync time.

Version Notes

Last Updated: Oct 2026