Import record data into an HTTP destination app

This article describes the options available for importing data into an HTTP destination application.

Create HTTP imports
Edit general import details
How would you like the records imported?
- Composite method required fields
Non-standard API response patterns
- Non-standard API response patterns for composite HTTP methods
  - Create new records
  - Update existing records
Mock response
Advanced

Create HTTP imports

Start creating an import to an HTTP destination in either of the following ways:

From the Tools menu, select Flow builder. Then, click Add destination / lookup. From the Application drop-down list, select HTTP.
Select Import records into destination application from the What would you like to do? list.

– or –

From the Resources menu, select Imports. Then, click + Create import. From the Application drop-down list, select HTTP.

Select your preferred HTTP connection.

Edit general import details

Name (required): Provide a clear and distinguishable name. You will have the option to choose this import throughout integrator.io, and a unique identifier will prove helpful later when selecting among a list of imports that you’ve created.

Description (optional): Describe your resource so that you and others can quickly understand its purpose. Be sure to highlight any nuances that a user should be aware of before using this import in a flow. As you make changes to the resource, be sure to keep this description up to date.

Connection (required): The HTTP connection you would like to use for your import. You can create your connections in the Resources menu > Connections or click the + icon to create a new connection. Each connection contains credentials and other related information needed to access your HTTP application.

One to many (required): One to many is used when you have a single record that internally needs to create multiple records. You would use this setting if, for example, your parent record contains child records you need to process. This setting cannot be used when importing a CSV file.

How would you like the records imported?

This section only displays for imports created from the Resources menu or if you select Import records into destination application when creating your import in Flow builder. See Where would you like the files-transferred? For transfer import options.

HTTP method (required): Choose one of the following methods to import your records:

Composite: makes changes depending on the existence or absence of records in the destination application. Composite requests require you to define how to create new records, identify existing records, and update existing records.
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.

The most common HTTP method used by APIs for the creating resources is POST. Updates typically use PUT. In some cases, RPC style or SOAP/XML APIs will always use the POST HTTP method. Consult your destination application's API documentation to determine which method is best to use for your import.

All HTTP methods provide the following optional fields:

Relative URI: The typical value of this field is the resource path portion of an API endpoint. Some examples are: /product or /bulkUpdate/orders. This relativeURI value is combined with the baseURI defined in the connection resource associated with this import. The baseURI and relativeURI together complete a fully qualified URL that describes an API endpoint. Query string parameters can sometimes be used to pass extended information to an API endpoint.

Configure HTTP headers: In some cases, it may be necessary to include custom HTTP headers with your API requests. As with the body field, any value from the connection or import models can be referenced using {{placeholders}} with a complete path matching either the connection or import field you require.

Override request media type: If the HTTP request requires a different media type than what is configured on the connection, select one of the following alternate media types:

CSV
Multipart / form-data
URL encoded
XML
Octet stream – only for Blob endpoints using Transfer files into destination application option

Number of records per HTTP request: This field only needs to be set if the API endpoint supports receiving batches of records in a single HTTP request. If left blank, this field defaults to 1.

HTTP request body: The field is used to define the exact HTTP request body that will get sent to the destination application endpoint.

Composite method required fields

Use the composite method to dynamically change the behavior of an import depending on the existence or absence of records in the destination application.

Composite type (required): Choose one of the following types:

Create new records & update existing records: dynamically create new records or update existing records in the import application. If you choose this type, you must define the Create new records, Identify existing records, and Update existing records criteria.
Create new records & ignore existing records: ignore existing records, and only create new records. If you choose this type, you must define the Create new records and Identify existing records criteria.
Ignore new records & update existing records: update existing records, and ignore records that can't be found. If you choose this type, you must define the Identify existing records and Update existing records criteria.

Create new records

HTTP method (required): Select the method integrator.io will use to create new records: PATCH, POST, or PUT.

HTTP request body: This field defines the exact HTTP request body that will get sent to the destination application endpoint.

See the non-standard API response patterns for Create new records.

Identify existing records

Note: These settings are required for all composite methods.

How would you like to identify existing records? (required): Choose one of the following options to identify if a source record already exists in the destination application:

Records have a specific field populated: This option checks if a specific field in the source record already has a value, and then if so, the source record will be considered an existing record. Enter the path to the field in the source record that should be used to identify existing records in Which field?. If a value is found for this field, then the source record will be considered an existing record.

Run a dynamic lookup: This option runs a search in the destination application to find a record on the fly, and then if a record is found, the source record will be considered an existing record. Use the Lookup field to choose an existing lookup from the list or click + to define a new lookup. Lookups provide a way to dynamically search the destination application on the fly to find existing records.

Update existing records

HTTP method (required): Select the method integrator.io will use to update existing records: PATCH, POST, or PUT.

HTTP request body: This field defines the exact HTTP request body that will get sent to the destination application endpoint.

See the non-standard API response patterns available for Update existing records.

Non-standard API response patterns

Path to id field in HTTP response body: Use this field to tell integrator.io where in the HTTP response body to find the id field for the record submitted. For batch requests, this path field is relative to each individual record returned. If this field is left blank, then integrator.io will automatically try to pick an id field for you.

Path to error field in HTTP response body: This field only needs to be set if the API always returns a successful HTTP status code, but then uses a field in the HTTP response body to indicate a failed request. For example, if the API always returns a 200 success HTTP status code, but then indicates errors via an error.message field in the HTTP response body.

Error values: Use this field to limit the exact values in the HTTP response body field that should be used to determine if the request failed. To provide multiple values, please use a comma-separated list.

Path to success field in HTTP response body: This field only needs to be set if the API always returns a successful HTTP status code, but then uses a field in the HTTP response body to indicate a successful request. For example, if the API always returns a 200 success HTTP status code, but then indicates success via a success boolean field in the HTTP response body.

Success values: Use this field to limit the exact values in the HTTP response body field that should be used to determine if the request succeeded. To provide multiple values, use a comma-separated list.

Path to detailed error message field in HTTP response body: This optional field is used to specify which field in the HTTP response body contains the detailed error message for the purpose of displaying the error on the error management dashboard. If this field is not set, then the full HTTP response body will be used as the error message in the error management dashboard.

Override media type for success responses: Use this field to handle the use case where a successful HTTP response returns a different media type than the original HTTP request body sent.

Override media type for error responses: Use this field to handle the use case where an unsuccessful HTTP response returns a different media type than the original HTTP request body sent.

Non-standard API response patterns for composite HTTP methods

The following non-standard API response patterns are available for composite HTTP methods:

Create new records

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.

Update existing records

Mock response

You can add mock response data to imports in the Mock response section of the Edit import page as simulated response data when configuring a flow.

Advanced

Remove empty fields from HTTP request body: Check this box if you want integrator.io to remove empty fields from the HTTP request body before submitting to the API.

Concurrency ID lock template: This field prevents integrator.io from sending duplicate records simultaneously if the connection associated with this import is using a concurrency level greater than 1. The connection associated with your import can be configured to limit the number of concurrent requests that can be made at any one time. If you are allowing more than 1 request at a time then it is possible for imports to overlap each other if multiple messages/updates for the same record are being processed at the same time. This field allows you to enforce an ordering across concurrent requests such that imports for a specific record id will queue up and be processed one at a time (while still allowing imports for different record ids to process in parallel). Enter a handlebars template that generates a unique id for each exported record. integrator.io uses the raw exported data to generate the ids (before any import or mapping logic is invoked), and uses the id to verify that no two records with the same id are submitted for import at the same time. For example, if you are exporting Zendesk records and importing them into NetSuite, then you would most likely use {{id}} (the field Zendesk uses to identify unique records). In this case no two records with the same Zendesk id value would import into NetSuite at the same time.

Data URI template: When your flow runs but has data errors this field can be really helpful in that it allows you to make sure that all the errors in your job dashboard have a link to the target data in the import application (where possible). This field uses a handlebars template to generate the dynamic links based on the data being imported. The template you provide will run against your data after it has been mapped, and then again after it has been submitted to the import application, to maximize the ability to link to the right place. For example, if you are updating a customer record in Shopify, you would most likely set this field to the following value https://your-store.myshopify.com/admin/customers/{{{id}}}.

Configure async helper: Check this box to configure an async helper.

Contents

Create HTTP imports

Edit general import details