Skip to main content

integrator.io REST API resources

Tom Santiago
  • Updated

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.

Note: Users of shared accounts (meaning users who are not account owners) are unable to view a flow's JSON data from within the user interface. If you need to view a flow's JSON data, you can download the flow and view it from within the ZIP file, or request a full access API token from the account owner, and access the flow's JSON data using Postman requests to the integrator.io API. If you attempt to retrieve a flow's JSON without a full access API token, you will receive the following error: 
{
  "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.

Related articles

Comments

9 comments

Date Votes
  • Don Conrad
    Engaged

    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

    0
  • Merik Ducker
    • Edited
    Awesome Follow-up
    Celigo University Level 4: Legendary
    Engaged

    Could you please add an example of an Export Clone? I'm getting the response:

    {
        "errors": [
            {
                "code": "invalid_connectionMap",
                "message": "The resource which you are trying to create requires a connectionMap."
            }
        ]
    }
     
    Update, below did the trick where connection id is the id of the connection:
     
    {
        "connectionMap": {
        "connection id": "connection id"
        }
    }
     
    0
  • viliandy leonardo

    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

    0
  • Don Conrad
    Engaged

    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.

    0
  • viliandy leonardo

    Don Conrad That's correct. If you could share, what scenarios/tasks are you planning to automate with these error APIs?

    Thanks

    0
  • Don Conrad
    Engaged

    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.

    0
  • Christoffer Sinnbeck
    Engaged

    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).

    0
  • Stephen Brandt Documentation Manager Community moderator
    Engaged
    Great Answer
    Top Contributor
    Celigo University Level 3: Master

    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. 

    0
  • Christoffer Sinnbeck
    Engaged

    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.

    0

Please sign in to leave a comment.