> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/files-and-tables/json.md). # JSON Connect to any REST API with JSON source — pull data from custom endpoints, SaaS platforms, and microservices into Google Sheets or BigQuery via Coupler.io. 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 {% hint style="success" %} 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. {% endhint %} ## How to connect {% stepper %} {% step %} **Create a new data flow** and select **JSON** as your source. {% endstep %} {% step %} **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`). {% endstep %} {% step %} **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. {% endstep %} {% step %} **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`. {% endstep %} {% step %} **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. {% endstep %} {% step %} **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](https://www.json2yaml.com/). For example: `customer_id: 1` and `customer_email: email@example.com` on separate lines. {% endstep %} {% step %} **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. {% endstep %} {% step %} **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`). {% endstep %} {% step %} **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. {% endstep %} {% step %} **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. {% endstep %} {% endstepper %} ## 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 | {% hint style="info" %} 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. {% endhint %} ## 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. {% hint style="info" %} 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](https://www.coupler.io/sources). You can additionally submit a request to add official support for a connection you need in our [Featurebase](https://couplerio.featurebase.app/). {% endhint %} ## 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. ## 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 {% hint style="warning" %} Never paste your actual API key or token in test messages or screenshots. Always keep credentials secure in Coupler.io's header field. {% endhint %}
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](/sources/category/files-and-tables/json/how-to-define-the-path-for-selecting-json-objects.md) — 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**](https://docs.coupler.io/functionality/data-set/combining-data/append-data) 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](/sources/category/files-and-tables/json/how-to-define-the-path-for-selecting-json-objects.md) 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. {% hint style="info" %} Never share your API keys or tokens publicly. Keep them secure in Coupler.io. {% endhint %}
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](https://www.json2yaml.com/). **JSON example:** ```json { "customer_id": 1, "customer_email": "email@example.com" ```
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.coupler.io/sources/category/files-and-tables/json.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.