Skip to main content

integrator.io REST API resources

Tom Santiago
  • Updated
Follow

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 in any integrator.io account. Integration Apps typically include an installer, an uninstaller, licensing controls, and settings pages. Integration Apps receive ongoing enhancements and updates.
  • 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.

Related articles

Comments

0 comments

Please sign in to leave a comment.