The integrator.io API is RESTful, uses JSON, and is secured by bearer tokens. API 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 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 well defined events 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 something. Then, use your API client – or a browser pointing to https://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" } ] } }
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.
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" }
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. |
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. |
Within the /errors endpoint, you can add the following query parameters to this API 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
For the /resolved endpoint, send the error object in the request body with the following format:
Request body: { "errors": ["<_errorId1>", ... , "<_errorIdn>"]}
For the /retry endpoint, send the retry keys in the request body with the following format:
Request body: { "retryDataKeys": ["<_retryDataKey1>", ... , "<_retryDataKeyn>"]}
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
0 comments
Please sign in to leave a comment.