# 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:

```json
[
  { "id": 1, "name": "Alice", "email": "alice@example.com" },
  { "id": 2, "name": "Bob", "email": "bob@example.com" }
]
```

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:

```json
{
  "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:

```json
{
  "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:**

```yaml
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:**

```yaml
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

{% tabs %}
{% tab title="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.
{% endtab %}

{% tab title="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.
{% endtab %}

{% tab title="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.
{% endtab %}
{% endtabs %}

## 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.