Import data into GraphQL

Kathyana Queeman

Updated June 01, 2026 20:26

Use this article to configure a GraphQL import in integrator.io — including the HTTP method, query, variables, and advanced settings. GraphQL is a query language for APIs that lets you request only the fields you need, reducing response size compared to REST API calls.

Additional resources: GraphQL documentation

Prerequisites

Before you begin, confirm the following:

You have a working GraphQL connection. See Set up a GraphQL connection for setup steps.

Create GraphQL imports

Important

To run an import to GraphQL, you need a working GraphQL connection.

Start creating an import to your application using GraphQL in either of the following ways:

From the Build menu, select Flow builder. Then, select Add destination.
From the Resources menu, select Imports. Then, select + Create import.
From the Application drop-down menu, select GraphQL and your available GraphQL connection.

General

Field	Description	Accepted values	Required
Name your import	A descriptive name for this import, used to identify it in the flow builder and Resources list.	Any string	Yes
Description	An optional description of what this import does.	Any string	No
Connection	The GraphQL connection used to authenticate requests to the destination application.	GraphQL connection	Yes
One to many	Use when a single source record needs to create multiple destination records — for example, when a parent record contains child records to process. Cannot be used when importing a CSV file.	`Yes (advanced)`, `No`	No

Configure import settings

Field	Description	Accepted values	Required
HTTP method	Determines how records are imported to the destination application. Consult your destination application's API documentation to determine which method to use.	`Composite`, `DELETE`, `PATCH`, `POST`, `PUT`	Yes
Query	Defines the request the GraphQL server is processing. If you use the query shorthand syntax (omitting the operation type and name), you can't supply a name or variable definitions for your operation. You can build a query during a connection, export, or import — the query structure stays the same across all three.	GraphQL query string	Yes
Operation name	A meaningful name for your operation, required only if your query contains two or more operations (a request can only execute one operation at a time). Useful for debugging and server-side logging — it's easier to identify a named query in your logs than to decipher its contents.	Any string	Only if query has 2+ operations
Variables	Defines the JSON variables used in your query. For example, for `query GetProduct($id: ID)`, define the variable as `{'id':'12345'}`. Use single quotes inside Handlebars functions to prevent parsing errors.	JSON object	No

Note

Use single quotes for string arguments inside the Variables field when using Handlebars functions (such as dateFormat or if) . GraphQL variables are converted to JSON before being sent, so double quotes inside Handlebars functions break the JSON structure and cause a parsing failure. This requirement applies specifically to the Variables field. If parsing fails, the resource will return an error in the flow run history.

Fails to parse:

{
  "query": "updated_at:>='{{dateFormat \"YYYY-MM-DDTHH:mm:ss[Z]\" lastExportDateTime \"YYYY-MM-DDTHH:mm:ss.SSS[Z]\"}}'"
}

Parses correctly:

{
  "query": "updated_at:>='{{dateFormat 'YYYY-MM-DDTHH:mm:ss[Z]' lastExportDateTime 'YYYY-MM-DDTHH:mm:ss.SSS[Z]'}}'"
}

HTTP method options

Value	Description
Composite	Makes changes depending on the existence or absence of records in the destination application. Selecting Composite reveals a Composite type field — see Composite type options below.
DELETE	Deletes records from the destination API based on your criteria.
PATCH	Sends the destination API instructions on how to modify existing records.
POST	Adds new records to the destination application.
PUT	Replaces existing records with new record data.

Composite type options

When HTTP method is set to Composite, a Composite type field appears with the following options:

Value	Description
Create new records & ignore existing records	Creates new records only. Existing records in the destination are left unchanged. Reveals a Create new records sub-section where you configure the HTTP method, Query, Operation name, and Variables for record creation.
Create new records & update existing records	Creates new records and updates records that already exist. Reveals both a Create new records and an Update existing records sub-section, each with their own HTTP method, Query, Operation name, and Variables fields.
Ignore new records & update existing records	Updates existing records only. New records are ignored. Reveals an Identify existing records and an Update existing records sub-section — see below.

Identify existing records

When Composite type is set to Ignore new records & update existing records or Create new records & update existing records, an Identify existing records sub-section appears.

Field	Description	Accepted values	Required
How would you like to identify existing records?	Determines how integrator.io locates existing records in the destination application.	`Records have a specific field populated`, `Run a dynamic lookup`	Yes
Which field?	Specifies the field used to identify existing records. Appears when How would you like to identify existing records? is set to Records have a specific field populated.	Field name string	Only if identifying by field
Lookup	The lookup resource used to find existing records. Appears when How would you like to identify existing records? is set to Run a dynamic lookup.	Existing lookup resource	Only if identifying by lookup

Update existing records

When Composite type includes updating existing records, an Update existing records sub-section appears. It contains the same fields as the main configuration — HTTP method, Query, Operation name, and Variables. See Configure import settings for field descriptions.

Preview & send

Tab	Description
Preview	Runs the import and displays the constructed request and a sample record that represents what integrator.io will send to the destination application. Select Send to execute.
Mock output	Lets you define a sample response manually, without making a live API call. Use this to test downstream mapping when live data isn't available. See Provide mock response data for imports for details.

Non-standard API response patterns

Some APIs may have response patterns that are unusual when compared to most APIs. Use the settings below to accommodate outlying response codes.

Field	Description
Path to records in HTTP response body	Use this field if the records returned by the API are not located at the root level of the HTTP response body. For example, an API could return records inside a container object like `results.customers`.
Path to id field in HTTP response body	Specifies where in the HTTP response body to find the id field for the submitted record. For batch requests, this path is relative to each individual record returned. If left blank, integrator.io will automatically attempt to identify an id field.
Path to error field in HTTP response body	Set this only if the API always returns a successful HTTP status code but uses a response body field to indicate failure — for example, returning `200` but signaling errors via `error.message`.
Error values	Limits which values in the error field are treated as failures. To provide multiple values, use a comma-separated list.
Path to success field in HTTP response body	Set this only if the API always returns a successful HTTP status code but uses a response body field to indicate success — for example, returning `200` with a `success` boolean.
Success values	Limits which values in the success field are treated as successful responses. To provide multiple values, use a comma-separated list.
Path to detailed error message field in HTTP response body	Specifies which field in the response body contains the detailed error message shown in the error management dashboard. If left blank, integrator.io uses the full HTTP response body as the error message.

Advanced

Field	Description
Data URI template	When your flow runs with data errors, this setting lets you verify that all errors have a link to the original data in the import application. Enter a Handlebars template to generate dynamic links based on the imported data. For example: `https://your-store.myshopify.com/admin/customers/{{{id}}}`