REST API setup

The REST API connector lets you pull data from any HTTP endpoint that returns JSON. Configure the URL, authentication, and schedule, and Genuics fetches your data automatically. This is ideal for proprietary APIs, internal tools, and services that don't support webhooks. Available on Starter plan and above.

When to use REST API vs webhooks

Use REST API when...	Use webhooks when...
The external tool doesn't support webhooks	The external tool can push data on events
You want to pull data on a schedule	You need data in real time
You need to paginate through historical data	Each event sends a single payload
You're connecting to an internal or custom API	You're connecting to a SaaS tool with webhook support

Create a REST API connector

1. Go to Setup > Connectors and click Add connector.
2. Select REST API.
3. Give your connector a name (e.g., "Internal CRM Tickets" or "Product Usage Stats").
4. Choose an existing dataset or create a new one.

Configure the request

Base URL

Enter the full URL of the API endpoint that returns your data. For example:

https://api.yourservice.com/v1/responses

Authentication

Choose the authentication method that matches your API:

Method	How it works
None	No authentication. Use for public APIs.
API key	Sends a key as a query parameter or header. Enter the parameter name (e.g., api_key) and your key value.
Bearer token	Sends an Authorization: Bearer <token> header. Paste your token.

Custom headers

If your API requires additional headers (e.g., Accept: application/json or a custom header like X-Org-Id), add them in the Custom headers section. Click Add header for each one and enter the name and value.

JSON path to data

Most APIs return a JSON object with metadata and a nested array of records. Tell Genuics where to find the data array using a dot-notation path:

API response structure	JSON path
{ "data": [ ... ] }	data
{ "results": { "items": [ ... ] } }	results.items
[ ... ] (top-level array)	Leave blank

Genuics uses this path to extract the array of records and map each object to a dataset row.

Pagination

If your API returns data across multiple pages, configure pagination so Genuics fetches everything:

Pagination type	How to configure
Page number	Genuics increments a page query parameter starting from 1. Set the page size parameter name (e.g., per_page) and value (e.g., 100).
Cursor-based	Genuics reads a next_cursor field from each response and passes it in the next request. Set the cursor parameter name and the JSON path to the cursor in the response.
Offset	Genuics increments an offset parameter by the page size on each request. Set the offset parameter name and the limit parameter name and value.
None	The API returns all data in a single response.

Set a sync schedule

Choose how often Genuics calls the API:

Schedule	Frequency
Manual	Only when you click Sync now
Every hour	Once per hour
Every 6 hours	Four times per day
Every 12 hours	Twice per day
Daily	Once per day at a time you choose
Weekly	Once per week on a day you choose

Choose a sync strategy

Strategy	What it does
Replace	Clears the dataset and loads the full API response each time
Append	Adds new rows without removing existing data
Upsert	Matches rows by a key column, updates existing rows, and inserts new ones

For Append and Upsert, consider adding query parameters to your URL that filter by date - for example, ?updated_since=2026-04-01 - so you only fetch new or changed data each sync.

Map your fields

After the first sync (or a test fetch), Genuics shows the fields it found in the API response. Map them to dataset columns, set types, and skip any fields you don't need.

See Field mapping for the full guide.

Test the connection

1. After completing the configuration, click Test connection.
2. Genuics makes a single request to your API and shows the response - including status code, headers, and a preview of the data.
3. If the test succeeds, click Save and sync to run the first full sync.

If the test fails, check the error message. Common issues include incorrect URLs, expired tokens, and firewall rules that block outbound requests from Genuics.

Troubleshooting

Issue	Solution
401 Unauthorized or 403 Forbidden	Your API key or token may be wrong or expired. Update it in connector settings.
404 Not Found	Double-check the URL. Make sure the endpoint path is correct and the resource exists.
429 Too Many Requests	The API is rate-limiting Genuics. Try reducing the sync frequency or contact the API provider about rate limits.
Empty dataset after sync	Check the JSON path setting. If it doesn't match the response structure, Genuics won't find any records. Use the test connection preview to inspect the raw response.
Pagination never stops	The API may not return an empty page when data runs out. Switch to a different pagination type or set the JSON path for the total count so Genuics knows when to stop.

Next steps

With your API connected, visit Sync status and troubleshooting to monitor sync health, or Field mapping to adjust how data is stored.