Best Practices

Recommended setup

Test with Postman first

Before creating a data flow, test your API endpoint in Postman or your browser. Verify the URL works, authentication is correct, and the response format is what you expect. This saves troubleshooting time in Coupler.io.

Use path to extract nested data

If your API response has nested objects, always use the **Path** field to target the specific array or object you need (e.g., `data.results` or `payload.users`). This keeps your import clean and avoids flattening unrelated data.

Select only columns you need

In the **Columns** field, list only the columns you'll actually use. This reduces data transfer time, keeps your destination sheet or table cleaner, and is especially helpful for large APIs with many fields.

Data refresh and scheduling

Space out scheduled runs for rate-limited APIs

If your API has rate limits, schedule data flows at intervals that stay well within the limit. For example, if the API allows 1000 requests/hour, run your flow every 30+ seconds to be safe. Stagger multiple flows hitting the same API.

Run a successful manual test before scheduling

Always execute a manual run and confirm the data arrives correctly before setting up a schedule. This ensures your configuration is correct and your destination is properly connected.

Configure retries for unreliable APIs

If your API occasionally fails or times out, set **Retries Count** to 3–5 and **Retries Delay** to 2000–5000 ms. This helps your data flow recover from temporary network or API glitches without manual intervention.

Performance optimization

Use query parameters to filter at the source

If your API supports filtering (e.g., `?status=active&created_after=2024-01-01`), add these in **URL query parameters**. Filtering at the source reduces data transfer and speeds up your flow.

Handle pagination in separate flows

If your API returns paginated results, create one data flow per page (e.g., `?limit=500&offset=0`, `?limit=500&offset=500`). Then use **Append** transformation to combine them. This is faster than requesting all data in a single large query.

Use Replace mode for complete refreshes

If your destination doesn't need historical data, use **Replace** mode to overwrite old data instead of **Append**. This keeps your sheet or table smaller and faster to work with.

Common pitfalls

Do

• Test your API endpoint before creating a data flow

• Use Path to extract nested objects from API responses

• Select only the columns you actually need

• Add Retries Count and Retries Delay for flaky APIs

• Space out scheduled runs if the API has rate limits

• Verify authentication works (test in Postman first)

• Use query parameters to filter data at the source

Don't

• Import every column if you only need a few (wastes time and space)

• Schedule multiple flows to hit the same API simultaneously

• Skip the manual test run — always verify before scheduling

• Ignore API rate limits (it will cause failures and blocks)

• Paste your actual API key or credentials in test messages

• Hardcode pagination offsets if the API supports bulk requests

• Assume the API response structure without checking with Postman first

Never commit API keys to version control or share them in unencrypted messages. Store authentication credentials securely in Coupler.io's Request headers field only.

Avoid creating data flows without testing the API first. A broken configuration will fail silently on schedule and waste time troubleshooting. Always run a manual test and confirm data appears in your destination before scheduling.