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.

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": "[email protected]" },
  { "id": 2, "name": "Bob", "email": "[email protected]" }
]

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

Operations & Business Analysts

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.