The integrator.io API is RESTful, performs requests in JSON formatting, and is secured by bearer tokens. (Generate a bearer token for integrator.io by selecting API tokens from the Resources menu). The base URL depends on your account location:
- North America:
https://api.integrator.io/v1/
- European Union:
https://api.eu.integrator.io/v1/
Developers can submit requests to build one or more of the following:
- Integration Apps: You can install fully managed, standalone integrations listed in the integrator.io Marketplace (NA | EU) to any integrator.io account. Integration Apps typically include an installer, an uninstaller, licensing controls, and settings pages. Integration Apps receive ongoing enhancements and updates. (Also see Publish Integration Apps and templates.)
- Embedded integrations: You can incorporate fully managed integrations where integrator.io remains completely invisible to the end user. You can use embedded integrations to operate within an external app’s user interface, with server calls to the integrator.io API dynamically deploying and customizing integration functionality.
- Hooks: You can write custom code in hooks, which are JavaScript event handlers within a flow. In most cases, this code customizes the flow of data beyond the options built into the standard user interface.
- Wrappers: You can connect apps that are not natively supported by integrator.io.
Tip: The integrator.io user interface also accesses the API. If you ever get stuck with the API you can always revert back to the browser app to create or modify a resource. Then, use your API client – or a browser pointing to https://[eu.]integrator.io/api/<relative_uri> – to see the resulting JSON.
Contents
Connections
Connections securely store credentials, along with any other information needed to access the applications you are integrating.
This API is typically needed for embedded integration development – for example, to expose a form in your app to collect a user’s credentials for another app being integrated. Once the customer’s credentials are stored in integrator.io, you can use other integrator.io API resources to enable any sort of integration with that application.
Connection API endpoints
Relative URI | Method | Success code | Description |
/connections | GET | 200 | Get all connections. |
POST | 201 | Create a connection. | |
/connections/<_id> | GET | 200 | Get a specific connection. |
PUT | 200 | Update a specific connection. | |
DELETE | 204 | Delete a specific connection. | |
/connections/<_id>/ping | GET | 200 | Test that a specific connection is operational. |
/connections/ping | POST | 200 | Test a virtual connection where all details for the connection are submitted in the POST body but not saved. |
/connections/<_id>/debug/<_resourceId> | GET | 200 | Get debug logs for a given connection by _id. Use optional _resourceId to filter logs by a specific import or export. |
/connections/<_id>/export | POST | 200 | Execute a virtual export using a connection identified by _id by posting the export model to this endpoint. |
/connections/<_id>/export/pages | POST | 200 | Alternative virtual export execution with paging support. |
/connections/<_id>/import | POST | 200 | Execute a virtual import using a connection identified by _id by posting the import model to this endpoint. |
/connections/<_id>/import/map | POST | 200 | Evaluate only the mapping step in a virtual import and return the set of post-mapped records. |
Connection API examples
GET /v1/connections/554••••••••••••••••••00d HTTP/1.1
Host: api.integrator.io
Authorization: Bearer my_api_token
Sample response
{ "_id":"554••••••••••••••••••00d", "lastModified":"2015-05-02T05:13:43.736Z", "type":"rest", "name":"Slack API", "rest": { "baseURI":"https://slack.com/api", "bearerToken":"•••••••", "tokenLocation":"url", "tokenParam":"token", "mediaType":"urlencoded", "authType":"token", "encryptedFields":[ ], "unencryptedFields":[ ], "scope":[ ], "pingRelativeURI":"api.test" }, "queues":[ { "name":"554••••••••••••••••••00d", "size":8 } ] }
GET /v1/connections/554••••••••••••••••••00d/ping HTTP/1.1
Host: api.integrator.io
Authorization: Bearer my_api_token
Sample response
{
"code": 200
}
POST /v1/connections/554••••••••••••••••••009/export/pages HTTP/1.1
Host: api.integrator.io
Authorization: Bearer my_api_token
{ "export": { "asynchronous":true, "pageSize":5, "netsuite": { "type":"search", "searches":[ { "recordType":"customRecord", "savedSearchId":"131298" } ], "skipGrouping":true } } }
Sample response
{ "data":[ { "recType":"813", "Trial Start":"2017-09-15T14:02:00.000-07:00", "custrecord_license2_trial_end_date":"2017-10-19T07:00:00.000+00:00", "custrecord_usage_diy_phone":"555-555-5555", "custrecord_usage_diy_ms":65894782, "custrecord_usage_diy_year":2017, "custrecord_usage_diy_company":"Acme Products", "custrecord_usage_diy_userid":"63fv1h4c7390c457ak1d20v2", "custrecord_usage_diy_name":"John Doe", "custrecord_usage_diy_hours":18, "custrecord_usage_diy_role":"Consultant", "custrecord_usage_diy_email":"jdoe@example.com", "custrecord_usage_diy_month_s":"November" }, { "recType":"813", "Trial Start":"2016-11-22T12:26:00.000-08:00", "custrecord_license2_trial_end_date":"2017-06-22T07:00:00.000+00:00", "custrecord_usage_diy_phone":"7777777777", "custrecord_usage_diy_ms":44439899, "custrecord_usage_diy_year":2017, "custrecord_usage_diy_company":"Widgets Inc.", "custrecord_usage_diy_userid":"999abc67k58941275f9910", "custrecord_usage_diy_name":"Jane Doe", "custrecord_usage_diy_hours":12, "custrecord_usage_diy_role":"Technology", "custrecord_usage_diy_email":"JDoe2@example.com", "custrecord_usage_diy_month_s":"November" }, { "recType":"813", "Trial Start":"2017-11-13T01:31:00.000-08:00", "custrecord_license2_trial_end_date":"2017-12-13T08:00:00.000+00:00", "custrecord_usage_diy_phone":"+5555555555", "custrecord_usage_diy_ms":33199382, "custrecord_usage_diy_year":2017, "custrecord_usage_diy_company":"Example Services", "custrecord_usage_diy_userid":"999abc67k58941275f991x", "custrecord_usage_diy_name":"Joe Smith", "custrecord_usage_diy_hours":9, "custrecord_usage_diy_role":"Manager", "custrecord_usage_diy_email":"Joe.Smith@example.com", "custrecord_usage_diy_month_s":"November" }, }, "dataURIs":{ null, null, null, null, null ], "pagedExportState": { "searchId":"WEBSERVICES_589861_11292017182391545425518660_73666d20757aff", "pageIndex":2, "pageSize":5, "totalPages":165, "totalRecords":822, "done":false, "issuedAt":1512010880, "sig":"ac7463cf6160937468e5cc575f541d438763719f5985c0ee85642e0de4d75d0d" } }
This example builds on the previous one to demonstrate how to get the next page of data for the same virtual export. It includes the exact pagedExportState object that was returned by the first API response. To get the next page after this, you can submit the pagedExportState returned by this API response.
POST /v1/connections/554••••••••••••••••••009/export/pages HTTP/1.1
Host: api.integrator.io
Authorization: Bearer my_api_token
{ "pagedExportState":{ "searchId":"WEBSERVICES_589861_11292017182391545425518660_73666d20757aff", "pageIndex":2, "pageSize":5, "totalPages":165, "totalRecords":822, "done":false, "issuedAt":1512010880, "sig":"ac7463cf6160937468e5cc575f541d438763719f5985c0ee85642e0de4d75d0d" }, "export":{ "asynchronous":true, "pageSize":5, "netsuite":{ "type":"search", "searches":[ { "recordType":"customRecord", "savedSearchId":"131298" } ], "skipGrouping":true } } }
Sample response
{ "data":[ { "recType":"813", "Trial Start":"2017-06-14T09:02:00.000-07:00", "custrecord_license2_trial_end_date":"2017-09-30T07:00:00.000+00:00", "custrecord_usage_diy_year":2017, "custrecord_usage_diy_hours":4, "custrecord_usage_diy_month_s":"November" }, { "recType":"813", "Trial Start":"2016-03-09T08:18:00.000-08:00", "custrecord_license2_trial_end_date":"2017-09-02T07:00:00.000+00:00", "custrecord_usage_diy_year":2017, "custrecord_usage_diy_hours":2, "custrecord_usage_diy_month_s":"November" }, { "recType":"813", "Trial Start":"2016-11-17T12:25:00.000-08:00", "custrecord_license2_trial_end_date":"2017-12-04T08:00:00.000+00:00", "custrecord_usage_diy_year":2017, "custrecord_usage_diy_hours":2, "custrecord_usage_diy_month_s":"November" }, { "recType":"813", "Trial Start":"2017-10-31T11:30:00.000-07:00", "custrecord_license2_trial_end_date":"2017-12-02T08:00:00.000+00:00", "custrecord_usage_diy_year":2017, "custrecord_usage_diy_hours":1, "custrecord_usage_diy_month_s":"November" }, { "recType":"813", "Trial Start":"2017-09-16T16:02:00.000-07:00", "custrecord_license2_trial_end_date":"2017-12-25T08:00:00.000+00:00", "custrecord_usage_diy_year":2017, "custrecord_usage_diy_hours":1, "custrecord_usage_diy_month_s":"November" } ], "dataURIs":[ null, null, null, null, null ], "pagedExportState":{ "searchId":"WEBSERVICES_589861_11292017182391545425518660_73666d20757aff", "pageIndex":3, "pageSize":5, "totalPages":165, "totalRecords":822, "done":false, "issuedAt":1512010952, "sig":"de523935aa3831a8d4ab49e788b22ba5c1be021a60db597b7c5a0033a669af9f" } }
The import object in the request defines how integrator.io should import the data, and the data array contains all the records that you want to import.
POST /v1/connections/5a1••••••••••••••••••77b/import HTTP/1.1
Host: api.integrator.io
Authorization: Bearer my_api_token
{ "import":{ "mapping":{ "fields":[ { "extract":"timestamp", "generate":"timestamp" }, { "generate":"key", "hardCodedValue":"sqs_flow" } ] }, "rest":{ "relativeURI":[ "/system/v1/heartbeat" ], "method":[ "PUT" ] } }, "data":[ { "timestamp":1512012818751 }, { "timestamp":1512012818751 }, { "timestamp":1512012818751 }, { "timestamp":1512012818751 } ] }
Sample response
[ { "statusCode":200, "id":"5a1••••••••••••••••••ab6", "_json":{ "_id":"5a1••••••••••••••••••ab6", "lastModified":"2017-11-30T03:33:51.703Z", "createdAt":"2017-11-21T21:37:10.497Z", "key":"sqs_flow", "timestamp":"2017-11-30T03:33:38.751Z", "__v":0 } }, { "statusCode":200, "id":"5a1••••••••••••••••••ab6", "_json":{ "_id":"5a1••••••••••••••••••ab6", "lastModified":"2017-11-30T03:33:51.704Z", "createdAt":"2017-11-21T21:37:10.497Z", "key":"sqs_flow", "timestamp":"2017-11-30T03:33:38.751Z", "__v":0 } }, { "statusCode":200, "id":"5a1••••••••••••••••••ab6", "_json":{ "_id":"5a1••••••••••••••••••ab6", "lastModified":"2017-11-30T03:33:51.700Z", "createdAt":"2017-11-21T21:37:10.497Z", "key":"sqs_flow", "timestamp":"2017-11-30T03:33:38.751Z", "__v":0 } }, { "statusCode":200, "id":"5a1••••••••••••••••••ab6", "_json":{ "_id":"5a1••••••••••••••••••ab6", "lastModified":"2017-11-30T03:33:51.701Z", "createdAt":"2017-11-21T21:37:10.497Z", "key":"sqs_flow", "timestamp":"2017-11-30T03:33:38.751Z", "__v":0 } } ]
Exports
Exports extract data from an application. They can run as standalone, via the API, or within the context of a flow.
This API is typically needed for Integration App development to create exports in your installer or dynamically configure exports based on settings that you expose in your app. You can also use the export API for embedded integration development when you want to automate deploying your exports via cloning or dynamically creating them from scratch.
Export API endpoints
Relative URI | Method | Success code | Description |
/exports | GET | 200 | Get all exports. |
POST | 201 | Create an export. | |
/exports/<_id> | GET | 200 | Get a specific export. |
PUT | 200 | Update a specific export. | |
DELETE | 204 | Delete a specific export. | |
/exports/<_id>/distributed | GET | 200 | Get the distributed configuration (the fields stored directly in the export application). This API is currently needed only for Salesforce and NetSuite real-time exports. |
PUT | 200 | Update the distributed configuration for a specific export. This API is currently needed for only Salesforce and NetSuite real-time exports. | |
/exports/<_id>/clone | POST | 201 | Clone a specific export. |
Export API examples
GET /v1/exports/55e••••••••••••••••••366 HTTP/1.1
Host: api.integrator.io
Authorization: Bearer my_api_token
Sample response
{ "_id":"55e••••••••••••••••••366", "lastModified":"2017-04-16T18:56:15.879Z", "name":"GitHub Event Listener", "type":"webhook", "hooks":{ "preSavePage":{ "_stackId":null, "function":null } }, "webhook":{ "provider":"github", "key":"••••••" } }
PUT /v1/exports/55e••••••••••••••••••366 HTTP/1.1
Host: api.integrator.io
Authorization: Bearer my_api_token
{ "_id":"55e••••••••••••••••••366", "lastModified":"2017-04-16T18:56:15.879Z", "name":"GitHub Event Listener (updated!)", "type":"webhook", "hooks":{ "preSavePage":{ "_stackId":null, "function":null } }, "webhook":{ "provider":"github", "key":"••••••" } }
Sample response
{ "_id":"55e••••••••••••••••••366", "lastModified":"2017-11-28T19:37:04.180Z", "name":"GitHub Event Listener (updated!)", "type":"webhook", "webhook":{ "provider":"github", "key":"•••••" } }
Imports
Imports insert data into an application; they can run as standalone via the API or in the context of a flow.
This API is typically needed for Integration App development to create imports in your installer or dynamically configure imports based on settings that you expose in your app. You can also use the import API for embedded integration development when you want to automate deploying your imports via cloning or dynamically creating them from scratch.
Import API endpoints
Relative URI | Method | Success code | Description |
/imports | GET | 200 | Get all imports. |
POST | 201 | Create an import. | |
/imports/<_id> | GET | 200 | Get a specific import. |
PUT | 200 | Update a specific import. | |
DELETE | 204 | Delete a specific import. | |
/imports/<_id>/clone | POST | 201 | Clone a specific import. |
Import API examples
GET /v1/imports/594••••••••••••••••••662 HTTP/1.1
Host: api.integrator.io
Authorization: Bearer my_api_token
Sample Response:
{ "_id":"594••••••••••••••••••662", "lastModified":"2017-11-28T18:38:19.851Z", "name":"Upload File to FTP Site", "_connectionId":"56f••••••••••••••••••77d", "distributed":false, "apiIdentifier":"ib8f75140f", "file":{ "skipAggregation":false, "type":"csv", "csv":{ "rowDelimiter":"\n", "columnDelimiter":",", "includeHeader":false, "wrapWithQuotes":false, "replaceTabWithSpace":false, "replaceNewlineWithSpace":false } }, "ftp":{ "directoryPath":"/test", "fileName":"file-{{timestamp}}.csv" }, "mapping":{ "fields":[ { "extract":"internal_id", "generate":"id" }, { "extract":"item_id", "generate":"sku" }, { "extract":"name", "generate":"name" }, { "extract":"sales_description", "generate":"description" }, { "extract":"rate", "generate":"price" }, { "extract":"qty_on_hand", "generate":"qty" } ] } }
This example demonstrates changes to the import shown above in the GET example.
PUT /v1/imports/594••••••••••••••••••662 HTTP/1.1
Host: api.integrator.io
Authorization: Bearer my_api_token
{ "_id":"594••••••••••••••••••662", "lastModified":"2017-06-23T17:31:04.446Z", "name":"Upload File to FTP Site (updated!)", "_connectionId":"56f••••••••••••••••••77d", "distributed":false, "apiIdentifier":"ib8f75140f", "file":{ "skipAggregation":false, "type":"csv", "lookups":[ ], "csv":{ "rowDelimiter":"\n", "columnDelimiter":",", "includeHeader":false, "wrapWithQuotes":false, "replaceTabWithSpace":false, "replaceNewlineWithSpace":false } }, "ftp":{ "directoryPath":"/test", "fileName":"file-{{timestamp}}.csv" }, "mapping":{ "fields":[ { "extract":"internal_id", "generate":"updated_id" }, { "extract":"item_id", "generate":"sku" }, { "extract":"name", "generate":"name" }, { "extract":"sales_description", "generate":"description" }, { "extract":"rate", "generate":"price" }, { "extract":"qty_on_hand", "generate":"qty" } ] } }
Sample response
{ "_id":"594••••••••••••••••••662", "lastModified":"2017-11-28T18:47:09.553Z", "name":"Upload File to FTP Site (updated!)", "_connectionId":"56f••••••••••••••••••77d", "distributed":false, "apiIdentifier":"ib8f75140f", "file":{ "skipAggregation":false, "type":"csv", "csv":{ "rowDelimiter":"\n", "columnDelimiter":",", "includeHeader":false, "wrapWithQuotes":false, "replaceTabWithSpace":false, "replaceNewlineWithSpace":false } }, "ftp":{ "directoryPath":"/test", "fileName":"file-{{timestamp}}.csv" }, "mapping":{ "fields":[ { "extract":"internal_id", "generate":"updated_id" }, { "extract":"item_id", "generate":"sku" }, { "extract":"name", "generate":"name" }, { "extract":"sales_description", "generate":"description" }, { "extract":"rate", "generate":"price" }, { "extract":"qty_on_hand", "generate":"qty" } ] } }
Flows
You can use flows to export data out of one or more applications and then import that data into one or more applications.
This API is typically needed for integration app development when you want to create flows in your installer or dynamically configure flows based on settings that you expose in your app. You can also use the flow API for embedded integration development when you want to automate deploying your flows via cloning or dynamically creating them from scratch.
{
"errors":[
{
"code":"missing_header",
"message":"An account is shared with you. Please send the Integrator-AShareId in the request header."
}
]
}
Flow API endpoints
Relative URI | Method | Success code | Description |
/flows | GET | 200 | Get all flows. |
POST | 201 | Create a flow. | |
/flows/<_id> | GET | 200 | Get a specific flow. |
PUT | 200 | Update a specific flow. | |
DELETE | 204 | Delete a specific flow. | |
/flows/<_id>/clone | POST | 201 | Clone a specific flow. |
/flows/<_id>/run | POST | 201 | Run a specific flow on demand. |
Flow API examples
GET /v1/flows/55e••••••••••••••••••367 HTTP/1.1
Host: api.integrator.io
Authorization: Bearer my_api_token
Sample response
{ "_id":"55e••••••••••••••••••367", "lastModified":"2017-06-19T21:27:09.945Z", "name":"Send GitHub Events to Slack", "disabled":false, "timezone":"America/Los_Angeles", "_exportId":"55e••••••••••••••••••366", "_importId":"55e••••••••••••••••••d14", "_integrationId":"58f••••••••••••••••••1bc", "skipRetries":false, "createdAt":"2017-06-19T21:27:09.900Z" }
GET /v1/flows/598••••••••••••••••••d9a HTTP/1.1
Host: api.integrator.io
Authorization: Bearer my_api_token
Sample response
{ "_id":"598••••••••••••••••••d9a", "lastModified":"2017-08-19T17:04:54.005Z", "name":"Update Usage Stats for all Trialers", "disabled":false, "schedule":"? 0 2 ? * *", "timezone":"America/Los_Angeles", "_integrationId":"593••••••••••••••••••74e", "skipRetries":false, "pageProcessors":[ { "type":"export", "_exportId":"598••••••••••••••••••428", "responseMapping":{ "lists":[], "fields":[ { "extract":"data", "generate":"numConnections" } ] } }, { "type":"export", "_exportId":"598••••••••••••••••••d32", "responseMapping":{ "lists":[], "fields":[ { "extract":"data", "generate":"dlSuccessAndErrors" } ] } }, { "type":"export", "_exportId":"598••••••••••••••••••6c6", "responseMapping":{ "lists":[], "fields":[ { "extract":"data", "generate":"lastSignIn" } ] } }, { "type":"export", "_exportId":"598••••••••••••••••••638", "responseMapping":{ "lists":[], "fields":[ { "extract":"data", "generate":"numDataLoaders" } ] } }, { "type":"export", "_exportId":"598e0c", "responseMapping":{ "lists":[], "fields":[ { "extract":"data", "generate":"numFlows" } ] } }, { "type":"export", "_exportId":"598••••••••••••••••••54b", "responseMapping":{ "lists":[], "fields":[ { "extract":"data", "generate":"numPasswordChanges" } ] } }, { "type":"export", "_exportId":"598••••••••••••••••••e22", "responseMapping":{ "lists":[], "fields":[ { "extract":"data", "generate":"numPasswordResets" } ] } }, { "type":"export", "_exportId":"598e29", "responseMapping":{ "lists":[], "fields":[ { "extract":"data", "generate":"numSignIns" } ] } }, { "type":"export", "_exportId":"598e37", "responseMapping":{ "lists":[], "fields":[ { "extract":"data", "generate":"successAndErrors" } ] } }, { "type":"import", "_importId":"598••••••••••••••••••615", "proceedOnFailure":true, "responseMapping":{ "lists":[], "fields":[] } }, { "type":"import", "_importId":"598••••••••••••••••••9f9", "responseMapping":{ "lists":[], "fields":[] } } ], "pageGenerators":[ { "_exportId":"598••••••••••••••••••286", "_id":"599••••••••••••••••••b36" }, { "_exportId":"598••••••••••••••••••6dd", "_id":"599••••••••••••••••••b35" } ], "createdAt":"2017-08-01T20:43:42.156Z" }
File definitions
File definitions determine the output of a file processed by integrator.io. They are simple rules that dictate what integrator.io does with the data extracted from a file.
Integration API endpoints
Relative URI | Method | Success code | Description |
/filedefinitions | GET | 200 | Get all file definitions. |
POST | 201 | Create a file definition. | |
/integrations/<_id> | GET | 200 | Get the list of file definition metadata. |
PUT | 200 | Update a specific file definition. | |
DELETE | 204 | Delete a specific file definition. |
Integrations
Integrations group flows. All flows that belong to the same integration share the same permissions, and the same tile on the homepage contains stats for all flows within the integration.
This API is typically needed for Integration App development to work with Integration App-only fields or for embedded integration development to automate deploying your integration solution (either via cloning or dynamically creating everything from scratch. For more information, see Integration App-only fields.
Integration API endpoints
Relative URI | Method | Success code | Description |
/integrations | GET | 200 | Get all integrations. |
POST | 201 | Create an integration. | |
/integrations/<_id> | GET | 200 | Get a specific integration. |
PUT | 200 | Update a specific integration. | |
DELETE | 204 | Delete a specific integration. | |
/integrations/<_id>/clone | POST | 201 | Clone a specific integration. |
/integrations/<_id>/installSteps | GET | 201 | Display Integration App installation steps per provided JSON definitions. |
POST | 200 | Submit form, trigger the next Integration App installation steps after user interaction or code completion. | |
/integrations/<_id>/uninstallSteps | GET | 200 | Display Integration App uninstallation steps per provided JSON definitions. |
POST | 201 | Submit form, trigger the next Integration App uninstallation steps after user interaction or code completion. |
Audit
An audit extracts log data for all resource types (such as flow, import, or export) and user events.
API endpoints
This API is typically needed to monitor and provide insight into the history, success, or failure of the resource.
Relative URI | Method | Success code | Description |
/<modelPlural>/<_id>/audit | GET | 200 | Get a log for a specific resource type or user event. |
Enter the ID of the ModelPlural (from the URL) for the <_id>, above.
Depending on the resource type, enter one of the following values for /<modelPlural>:
- Flow: /flows
- Integration: /integrations
- Connection: /connections
- Import: /imports
- Export: /exports
- Script: /scripts
- MyAPI: /apis
- API token: /accesstokens
Example
Sample GET response
"audit": [ { "_id": "•••••••••••••", "resourceType": "export", "_resourceId": "••••••••••••••••••••••••••", "source": "UI", "fieldChanges": [
{
"newValue": {
"resource": "customers",
"version": "v2",
"operation": "getacountof_customergroups"
},
"fieldPath": "assistantMetadata"
},
{
"oldValue": "RESTExport",
"newValue": "RESTExport", } ]
Errors
If you have opted in to Error Management 2.0, you can access your flows’ errors using the integrator.io API and then take action programmatically. Full access tokens are required for authentication.
Relative URI | Method | Success code | Description |
/flows/<_flowid>/<_exportId>/errors | GET | 200 | Get all errors for an export. |
/flows/<_flowid>/<_importId>/errors | GET | 200 | Get all errors for an import. |
/flows/<_flowid>/<_importId>/resolved | PUT | 200 | Resolve specified errors for an import. |
/flows/<_flowid>/<_importId>/retry | POST | 200 | Retry specified errors for an import. |
/flows/<_flowid>/<_exportId>/<_retryDataKey>/data | GET | 200 | Get error retry data for an export. |
/flows/<_flowid>/<_importId>/<_retryDataKey>/data | GET | 200 | Get error retry data for an import. |
/flows/<_flowid>/<_exportId>/<_retryDataKey>/data | PUT | 200 | Update error retry data for an export. |
/flows/<_flowid>/<_importId>/<_retryDataKey>/data | PUT | 200 | Update error retry data for an import. |
/errors
Within the /errors endpoint, you can add the following query parameters when making a GET method call, to narrow down the results you want to see:
- occurredAt_lte (time value is UTC in ISO format)
- occurredAt_gte (time value is UTC in ISO format)
- Source
Sample GET response
"errors": [
{
"occurredAt": "2021-06-15T21:21:30.538Z",
"source": "application",
"code": "response_failure",
"message": "\"response failed using path: \\\"ok\\\". Value found: \\\"false\\\". Response body: {\\\"ok\\\":false,\\\"error\\\":\\\"channel_not_found\\\"}\"",
"traceKey": "53968",
"exportDataURI": "53968 Winifred Arathorn",
"oIndex": "1",
"retryDataKey": "332••••••••••••••••••••••••••81fe",
"errorId": "•••••••••",
"_flowJobId": "60c•••••••••••••••••e77",
"classification": "missing",
"classifiedBy": "autopilot",
"reqAndResKey": "5634326309435-9a2aeeaaec51494cb1ed2206f34116c8-200-POST"
}
]
/resolved
For the /resolved endpoint, send the error object in the request body with the following format:
Request body: { "errors": ["<_errorId1>", ... , "<_errorIdn>"]}
/retry
For the /retry endpoint, send the retry keys in the request body with the following format:
Request body: { "retryDataKeys": ["<_retryDataKey1>", ... , "<_retryDataKeyn>"]}
/data
The <_retryDataKey> value is available from the /errors endpoint (see sample data, above) for an export or import. A GET call to the /data endpoint with this key will return the error retry data.
Sample GET response
{ "data": { "_id": ••••, "role": "Student", "firstname": "Winifred", "lastname": "Arathorn", "age": 73 }, "files": { "fileMeta": { "fileName": "School_name_randomid.json", "modifiedTime": "2021-03-12T19:23:40.560Z", "id": "1A_UwQGRxSRX5BaMjpBeTRwrAxytARJnc", "type": "application/json" } }, "stage": "page_processor_import", "traceKey": "53968", "dataURI": "53968 Winifred Arathorn" }
Then, via the integrator.io API, you can attempt to retry the error with the same or modified fields. Place a PUT call to the /data endpoint, passing all of the data returned from the GET method in the request body.
Sample PUT response
{ "data": { "_id": 53968, "role": "Student", "firstname": "Winifred_updated_via_put", "lastname": "Arathorn_updated_via_put", "age": 73 }, "files": { "fileMeta": { "fileName": "School_name_randomid.json", "modifiedTime": "2021-03-12T19:23:40.560Z", "id": "1A_UwQGRxSRX5BaMjpBeTRwrAxytARJnc", "type": "application/json" } }, "stage": "page_processor_import", "traceKey": "53968", "dataURI": "53968 Winifred Arathorn" }
Do you know that, after opting in to Error Management 2.0, you can access your flows’ errors using the integrator.io API and then take action programmatically?
Check out this template that demonstrates error handling automation via the integrator.io error REST API. This template contains two example flows that use Error Management 2.0 features to automate retrying or resolving errors that meet certain conditions. This template is most useful for integration scenarios where errors do not need further resolution other than to retry the record as-is or for known issues that can be automatically resolved.
Comments
9 comments
Would it be possible to add a description of the error fields returned in the new error API? What I'm looking for is what field(s) make an error unique across all integrations and flows.
These are the fields we get back,
occurredAt
source
code
message
oIndex
retryDataKey
errorId
_flowJobId
There is an errorId field which sounds good but I have a suspicion that may not be unique across all integration flows.
Thanks
Could you please add an example of an Export Clone? I'm getting the response:
Don Conrad
The combination of "flowId + stepId + errorId" will be the unique identifier for all errors in an account. You cannot use _flowJobId because it may be blank in a specific error situation.
Thanks
Thanks! Just to clarify stepId is the same as import/export id?
/flows/<_flowid>/<_importId>/errors
So the unique key would be _flowid + _importId + errorId right?
Looking good so far, this is going to help us a lot.
Don Conrad That's correct. If you could share, what scenarios/tasks are you planning to automate with these error APIs?
Thanks
We use Celigo to import Amazon orders into Netsuite as Sales Orders. We want to switch to invoices which would half our transaction volume. The challenge is invoices error if there isn't enough inventory rather than go on back order like sales orders. Prior to EM2.0 we didn't have a way for our warehousing team to manage those errors.
Now we can build an interface in Netsuite for the warehouse team to manage the errors. They can stay in the tool they know and we can filter it so they only see the inventory errors they need to address.
A suggestion: You should update this article to show that the API base URL is
https://api.eu.integrator.io/v1/
if one is using the EU version of Celigo (the one located at https://eu.integrator.io).
Christoffer Sinnbeck: thanks for the correction, and please forgive our oversight and bias.
The requested update will surely help others. I hope you didn't lose too much time figuring out the right URL or bringing it to our attention.
Stephen Brandt: Thanks Stephen, no worries at all. I figured it out after a few minutes of "Unauthorized" messages, and just wanted to add my finding here. Have a great day.
Please sign in to leave a comment.