JSON

JSON is a universal data format used by thousands of APIs and web services. With Coupler.io's JSON source, you can connect to any REST API endpoint that returns JSON data—no coding or special tools required. Whether you're pulling data from a custom API, a SaaS platform's REST endpoint, or your own server, JSON gives you complete flexibility.

Why connect to Coupler.io?

• Work with any REST API — Connect to APIs that don't have a pre-built Coupler.io connector, or use multiple endpoints from the same service

• No coding required — Configure HTTP methods, headers, query parameters, and request bodies through a simple form

• Support for all HTTP methods — Use GET, POST, PUT, PATCH, or DELETE depending on your API's requirements

• Flexible data extraction — Target specific nested objects with path expressions, select specific columns, and handle complex JSON structures

• Send data anywhere — Deliver your JSON data to Google Sheets, Excel, BigQuery, Looker Studio, or AI destinations like Claude, ChatGPT, and Gemini

Prerequisites

• A REST API endpoint that returns JSON data (public URL or with authentication)

• API authentication credentials if your endpoint requires them (API keys, OAuth tokens, etc.)

• Basic understanding of your API's requirements (HTTP method, headers, parameters)

Quick start

Before you start, gather your API documentation. You'll need the endpoint URL and any authentication details (headers, API keys, or OAuth tokens). Have your API docs handy so you can reference the exact HTTP method and any required parameters.

How to connect

1

Create a new data flow and select JSON as your source.

2

Enter the JSON URL — Paste the REST API endpoint URL where you want to fetch data from (e.g., https://api.example.com/v1/users).

3

Select the HTTP method — Choose the method your API requires: GET (most common), POST, PUT, PATCH, or DELETE. Check your API documentation if you're unsure.

4

Add authentication headers (if needed) — If your API requires authentication, add headers like Authorization: Bearer YOUR_TOKEN or X-API-Key: YOUR_KEY in the Request headers field. Format each header on a new line as HeaderName: HeaderValue.

5

Add URL query parameters (if needed) — If your API requires query parameters like ?filter=active&limit=100, add them in the URL query parameters field. Format as key=value pairs, one per line.

6

Add a request body (if needed) — If you're using POST, PUT, or PATCH, and your API requires a body, add it in YAML format. Convert JSON examples from your API docs to YAML using a tool like JSON2YAML. For example: customer_id: 1 and customer_email: [e-mail] on separate lines.

7

Set the path (optional) — If your JSON response has nested objects and you only want data from a specific part, use dot notation (e.g., data.users or results.items). Leave blank to import all data from the root level.

8

Select columns (optional) — By default, all columns are imported. To import only specific columns, list their names separated by commas (e.g., id,name,email,created_at).

9

Choose your destination — Select where you want the data to go: Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like Claude or ChatGPT.

10

Run the data flow — Click Run to execute the data flow and test the connection. A successful run is required before you can schedule regular updates.

Common use cases

JSON works with any REST API. Here are typical scenarios:

Use case	HTTP method	Authentication
Fetch user or product data	GET	API key or OAuth token in headers
Submit webhook data or custom requests	POST	API key or OAuth token
Update records from an external system	PUT / PATCH	API key or OAuth token
Sync data from a custom internal API	GET / POST	Bearer token or custom headers
Pull data from multiple API endpoints	GET (multiple data flows)	API key or OAuth token

If you're pulling data from multiple endpoints or combining data from different API calls, create separate data flows for each endpoint and use Append or Join transformations to combine them in your destination.

JSON data overview

JSON is a flexible source—it doesn't have predefined entities or reports. Instead, you define the data structure by specifying the API endpoint, HTTP method, and any authentication or parameters required. The data you import depends entirely on what your API returns.

If your data source is not directly supported you can use the JSON source to get the data you need if your source has a REST API. You can check the list of all available integrations on our available source page. You can additionally submit a request to add official support for a connection you need in our Featurebase.

How JSON data mapping works

When you connect to a JSON API:

1. URL — The API endpoint that returns JSON data

2. HTTP method — How the API processes your request (GET, POST, PUT, PATCH, DELETE)

3. Authentication — Headers or parameters needed to authenticate (API keys, OAuth tokens, etc.)

4. Path — Optional: Navigate nested JSON structures using dot notation (e.g., data.users selects the users array inside the data object)

5. Columns — Optional: Import all columns by default, or specify which columns to include

Data structure examples

Flat JSON array

If your API returns an array of objects at the root level:

[
  { "id": 1, "name": "Alice", "email": "[e-mail]" },
  { "id": 2, "name": "Bob", "email": "[e-mail]" }
]

Leave the Path field empty, and Coupler.io will import all rows with columns: id, name, email.

Nested JSON objects

If your API returns nested data like:

{
  "status": "success",
  "data": {
    "users": [
      { "id": 1, "name": "Alice" },
      { "id": 2, "name": "Bob" }
    ]
  }
}

Set Path to data.users to extract the users array.

Paginated responses

If your API returns paginated data with a results array:

{
  "page": 1,
  "total": 100,
  "results": [
    { "id": 1, "name": "Alice" }
  ]
}

Set Path to results to extract the data array. For pagination, use URL query parameters like page=1&limit=50 and create separate data flows for each page, then use Append to combine them.

Working with different HTTP methods

GET (most common)

Fetch data from an API endpoint. No request body is needed. Use URL query parameters to filter or paginate.

Example: https://api.example.com/v1/users?limit=100&offset=0

POST

Submit data to retrieve results. Use a request body to specify what data you want. Common for search APIs or webhooks.

Example body:

query: "active users"
filter: "created_after:2024-01-01"

PUT / PATCH

Update records and retrieve the updated data. PUT replaces an entire resource, PATCH updates specific fields. Usually requires a request body.

Example body:

id: 123
status: "updated"

DELETE

Delete a record or request. May return the deleted object or a confirmation.

Authentication methods

Method	Header format	Example
API Key (in header)	X-API-Key: YOUR_KEY	X-API-Key: abc123xyz
Bearer token	Authorization: Bearer YOUR_TOKEN	Authorization: Bearer eyJhbGc...
Basic auth (in header)	Authorization: Basic BASE64_ENCODED	Authorization: Basic dXNlcjpwYXNz
Custom header	HeaderName: value	X-Custom-Auth: mytoken123

Check your API documentation to find the correct authentication header format.

Common workflows

Extracting a single array from a nested response

If your API returns data inside a nested object, use Path to target it:

• API response has structure: { "meta": {...}, "data": [{...}] }

• Set Path to: data

• Result: Coupler.io imports only the array inside data

Filtering data by columns

If your API returns many columns but you only need a few:

• Set Columns to a comma-separated list: id,name,email,created_date

• Coupler.io imports only these columns, making your destination sheet cleaner and reducing data transfer

Combining data from multiple API endpoints

If you need data from two different API endpoints:

1. Create a first data flow for the first endpoint

2. Create a second data flow for the second endpoint

3. In your destination, use Append transformation to combine both data flows

4. Or use Join if the data flows share a common ID column

Retry configuration

For unreliable APIs, configure automatic retries:

• Retries Count — Number of attempts if the API fails (e.g., 3 for 3 retry attempts)

• Retries Delay — Wait time between retries in milliseconds (e.g., 1000 = 1 second)

Example: 3 retries with 2-second delay between each = if the first request fails, retry 3 times, waiting 2 seconds between each attempt.

Use cases by role

Developers & Integrators

You can use JSON to:

• Connect to custom internal APIs and pull operational data into Google Sheets or BigQuery

• Test API endpoints before building full integrations

• Automate data syncing from microservices, webhooks, or third-party REST APIs

• Use POST requests to trigger API actions and capture response data

• Combine data from multiple microservices using Append or Join transformations

• Deliver processed data to Claude or ChatGPT for analysis or summarization

Example: Pull user activity data from a custom API every hour, filter by columns, and append to a BigQuery table.

Data Analysts

You can use JSON to:

• Connect to REST APIs that don't have pre-built Coupler.io connectors

• Pull raw data directly into Google Sheets or BigQuery for analysis

• Extract specific nested objects using path expressions to simplify complex API responses

• Create multiple data flows for different API endpoints and combine them with Append or Join

• Automate data collection without building custom scripts

• Send API data to Claude or Perplexity for quick analysis or insights

Example: Fetch customer metrics from an internal API, select specific columns, and append to an analytics sheet alongside CRM data.

Operations & Business Analysts

You can use JSON to:

• Pull real-time data from business tools' REST APIs into Google Sheets dashboards

• Monitor operational metrics by importing from custom internal systems

• Combine data from multiple sources into a single view using transformations

• Automate reports by pulling fresh data on a schedule

• Send summarized data to ChatGPT or Gemini for quick business insights

Example: Import daily revenue and customer counts from an internal API, combine with other sources, and auto-refresh your executive dashboard.

Platform-specific notes

• Google Sheets — JSON data flows work seamlessly with the Coupler.io Google Sheets add-on. Create the data flow, run it, and it imports directly into your sheet.

• BigQuery — Use JSON for continuous data ingestion into BigQuery tables. Set up scheduling for automated daily or hourly syncs.

• Excel — JSON data flows can export to Excel files, but scheduling is most reliable with cloud destinations (Google Sheets, BigQuery).

• Multiple API endpoints — Create one data flow per endpoint. Use Append or Join transformations in your destination to combine them.

• Pagination — If your API paginates results, create separate data flows for each page or use query parameters to fetch all data in one request. Then use Append to combine pages.

• Rate limiting — Some APIs have rate limits. Use Retries Count and Retries Delay to handle temporary failures gracefully. Space out scheduled refreshes to avoid hitting limits.

• AI destinations — Send JSON data to Claude, ChatGPT, Cursor, Gemini, Perplexity, or OpenClaw for instant analysis, summarization, or insight generation.

JSON common issues

Connection issues

401 Unauthorized or 403 Forbidden error

Your API authentication is missing or incorrect.

Fix:

1. Check your API documentation for the correct authentication header format (API Key, Bearer token, Basic auth, etc.)

2. Verify your authentication credentials (API key, token, username/password) are correct and not expired

3. In Request headers, add the authentication header exactly as specified by your API (e.g., Authorization: Bearer YOUR_TOKEN)

4. If using Basic auth, encode your credentials as base64 and use: Authorization: Basic BASE64_ENCODED_CREDENTIALS

5. Test your API with a tool like Postman to confirm authentication works before retrying in Coupler.io

Never paste your actual API key or token in test messages or screenshots. Always keep credentials secure in Coupler.io's header field.

404 Not Found error

The URL or endpoint path is incorrect.

Fix:

1. Double-check the URL in JSON URL — verify the endpoint path matches your API documentation

2. If the API requires query parameters, add them in URL query parameters (e.g., api_version=v2&filter=active)

3. Test the URL in your browser or with Postman to confirm it's accessible and returns data

4. Some APIs require specific headers to work correctly — check your API docs and add any required headers in Request headers

Connection timeout or slow response

The API is taking too long to respond.

Fix:

1. If the API has pagination, use query parameters to limit results: ?limit=100&offset=0 instead of requesting all data at once

2. Add Retries Count and Retries Delay to automatically retry failed requests: try 3 retries with 2000 ms (2-second) delay

3. Check if the API has rate limits — space out your data flow runs or use a filter to request only recent data

4. Test the URL directly in Postman to see response time and confirm the API is responding normally

5. If the API consistently times out, check with your API provider if there are performance issues or service limits

SSL certificate or HTTPS error

There's an issue with the API's SSL certificate.

Fix:

1. Verify the URL uses https:// (not http://)

2. Confirm the API endpoint is publicly accessible and has a valid SSL certificate

3. Test the URL in your browser — if your browser shows a security warning, contact the API provider

4. If you're using a self-signed certificate or internal API, contact Coupler.io support for assistance

Missing data

No data imported or empty result

The API returned data, but Coupler.io didn't import anything.

Fix:

1. Check the Path setting — if your JSON response has nested objects (e.g., { "data": { "users": [...] } }), set Path to data.users to extract the array

2. If the API returns an object instead of an array, Coupler.io may not import it correctly — contact support with a sample of the API response

3. Verify the API is returning data by testing the URL with Postman or your browser

4. Check that your authentication headers are correct (see Connection issues above)

5. If using POST or PUT, confirm your Request body is in valid YAML format and matches what the API expects

Only partial data imported

You're getting some data but not all rows.

Fix:

1. If the API paginates results, you're likely only getting the first page. Check the API response for page, offset, next, or similar pagination fields

2. Create multiple data flows, one for each page (e.g., ?page=1, ?page=2, etc.) &#xNAN;Note: You can use the duplicate button to make this process faster. This will allow you to get a new source with the same settings. All you need is to edit the name and the page number in the duplicated source.

   
3. Use the Append transformation to combine them

4. Or, check if the API supports a limit or per_page parameter to return all results in one request (e.g., ?limit=10000)

5. If you set Columns to specific column names, verify the spelling matches the API response exactly (column names are case-sensitive)

Columns are missing or data looks truncated

Some columns from the API response are not appearing in your destination.

Fix:

1. If you manually set Columns, you may have omitted some columns. Leave Columns blank to import all available columns

2. Check if the Columns field has a typo or case mismatch — JSON column names are case-sensitive

3. Use Postman or your browser to inspect the raw API response and confirm all columns are present

4. If the API returns very long text in a column, it may be truncated in Google Sheets — this is a sheet limitation, not a Coupler.io issue

Permission errors

Cannot access the destination (Google Sheets, BigQuery, etc.)

Coupler.io can't write data to your destination.

Fix:

1. Verify you've authenticated Coupler.io with your destination (Google Sheets, BigQuery, etc.)

2. Check that your destination account has write permissions to the specific sheet or table

3. If using a shared sheet, ensure you have edit access, not just view access

4. For BigQuery, confirm your account has the bigquery.dataEditor role on the target dataset

5. Re-authenticate your destination by disconnecting and reconnecting it in Coupler.io settings

Data discrepancies

Data types are incorrect (numbers as text, dates formatted wrong, etc.)

Coupler.io or your destination is interpreting columns as the wrong data type.

Fix:

1. In Google Sheets, use Format > Number to set the correct format for each column (Number, Currency, Date, etc.)

2. Check the API response in Postman — if the API returns numbers as strings (e.g., "123" instead of 123), this is an API issue

3. Some APIs return dates as timestamps (Unix time) — convert them in your destination sheet using formulas or post-import transformations

4. If a column should be numeric but appears as text, check for leading spaces or special characters in the API response

Duplicate rows appearing

Your destination contains multiple copies of the same rows.

Fix:

1. Check if you're running multiple data flows to the same destination — if so, they may both be appending the same data

2. If pagination is involved, verify each page query is unique (e.g., ?page=1, ?page=2) so you're not fetching the same rows twice

3. If scheduled runs are stacking data, use Replace mode instead of Append to overwrite previous data

4. Check if the API itself is returning duplicates by testing with Postman

Data is not refreshing or showing stale results

Your destination shows old data even after running the data flow.

Fix:

1. Confirm the data flow ran successfully — check the Run history in Coupler.io

2. If using Append mode, old data won't be removed. Clear the destination manually or use Replace mode to overwrite

3. If scheduled, verify the schedule is set up correctly and hasn't been paused

4. Check if the API itself is returning fresh data by testing with Postman

5. Some data sources have cache delays — if the API caches responses, wait a few minutes before checking for updates

Rate limits

429 Too Many Requests or rate limit error

You're hitting the API's rate limit.

Fix:

1. Check your API documentation for rate limit details (requests per minute/hour)

2. Add Retries Count and Retries Delay to auto-retry: use 5 retries with 5000 ms (5-second) delay between retries

3. Space out scheduled data flow runs — if you have multiple flows hitting the same API, stagger their schedules

4. Use query parameters to request smaller batches of data, or use pagination with longer intervals between pages

5. If you're testing frequently, reduce test runs — every manual run counts against your rate limit

6. Contact the API provider to request a higher rate limit if your use case requires frequent syncs

Request gets blocked or returned as "forbidden"

The API is rejecting your requests, possibly due to rate limiting or suspicious activity detection.

Fix:

1. Add a User-Agent header in Request headers to identify your requests: User-Agent: Coupler.io/1.0

2. Increase Retries Delay to add longer wait times between retries, signaling you're a legitimate client

3. Space out your data flow schedules so you're not hammering the API with rapid requests

4. Check if the API uses IP whitelisting — if so, contact support to get Coupler.io's IP addresses whitelisted

5. Some APIs require additional headers or rate-limit-specific settings — check their docs

JSON FAQ

Can I use JSON to connect to any REST API?

Yes, JSON works with virtually any REST API that returns JSON data. This includes:

• Third-party SaaS platforms with REST APIs

• Custom internal APIs

• Microservices and webhooks

• Any endpoint that supports GET, POST, PUT, PATCH, or DELETE

If the API requires authentication (API key, OAuth token, etc.), add it to the Request headers field.

How do I extract nested data from a JSON response?

Use the Path field with dot notation to navigate nested objects.

Examples:

• If your API returns { "data": { "users": [{...}] } }, set Path to data.users

• Leave Path blank if your API returns data at the root level (e.g., a direct array of objects).

What's the difference between GET, POST, PUT, PATCH, and DELETE?

• GET — Fetch (retrieve) data. No request body needed. Most common for APIs.

• POST — Create new data or submit queries. Usually requires a request body.

• PUT — Replace an entire record. Requires a request body with complete data.

• PATCH — Update specific fields of a record. Requires a request body with only the fields to update.

• DELETE — Delete a record or request. May or may not require a request body.

Check your API documentation to see which method is required.

How do I add authentication to a JSON data flow?

Add authentication in the Request headers field. The format depends on your API:

• API Key: X-API-Key: YOUR_API_KEY or Authorization: YOUR_API_KEY

• Bearer token: Authorization: Bearer YOUR_TOKEN

• Basic auth: Authorization: Basic BASE64_ENCODED_CREDENTIALS

• Custom header: Any header your API specifies

Add each header on a new line. Check your API documentation for the exact format required.

Never share your API keys or tokens publicly. Keep them secure in Coupler.io.

Can I use a request body with GET requests?

No, GET requests do not support request bodies. If your API requires a body, use POST, PUT, or PATCH instead.

For GET requests, use URL query parameters to pass filtering or pagination parameters (e.g., ?limit=100&filter=active).

How do I format a request body in YAML?

Convert your JSON request body to YAML format using a tool like JSON2YAML.

JSON example:

{
  "customer_id": 1,
  "customer_email": "[e-mail]"