├── connection.md ├── connector.md ├── export.md ├── flow.md ├── iClient.md ├── import.md ├── integration.md ├── job.md ├── readme.md ├── state.md └── template.md /connection.md: -------------------------------------------------------------------------------- 1 | Connection API 2 | ========== 3 | >**Guidance**: this API is typically only needed for Embedded Integration development where you want to expose a form in your application's UI to collect a user's credentials to the application being integrated, and then once their credentials are stored in integrator.io you can then use the larger integrator.io API to enable any sort of integration with that application. 4 | 5 | ### Endpoints 6 | | Relative URI| Method | Success Code | Description| 7 | |:-------------------|:-------|:------------:|:------------------------------| 8 | |/connections|GET|200|Get all connections.| 9 | |/connections/{_id}|GET|200|Get a specific connection.| 10 | |/connections|POST|201|Create a new connection.| 11 | |/connections/{_id}|PUT|200|Update a specific connection.| 12 | |/connections/{_id}|DELETE|204|Delete a specific connection.| 13 | |/connections/{_id}/ping|GET|200|Test that a specific connection is operational.| 14 | |/connections/ping|POST|200|Test a virtual connection where all details for the connection are submitted in the POST body, but are not saved.| 15 | |/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.| 16 | |/connections/{_id}/export|POST|200|Execute a virtual export using a connection identified by _id by posting the export model to this endpoint.| 17 | |/connections/{_id}/export/pages|POST|200|Alternative virtual export execution with paging support.| 18 | |/connections/{_id}/import|POST|200|Execute a virtual import using a connection identified by _id by posting the import model to this endpoint.| 19 | |/connections/{_id}/import/map|POST|200|Evaluate only the mapping step in a virtual import and return the set of post-mapped records.| 20 | 21 | ## Examples 22 | 23 | #### 1. Get a specific connection. 24 | 25 | ``` 26 | GET /v1/connections/5541e17a1383a6ce6e00000d HTTP/1.1 27 | Host: api.integrator.io 28 | Authorization: Bearer my_api_token 29 | ``` 30 | 31 | Sample Response: 32 | 33 | ``` 34 | { 35 | "_id": "123ab456c789de1011fg12h13i", 36 | "lastModified": "2015-05-02T05:13:43.736Z", 37 | "type": "rest", 38 | "name": "Slack API", 39 | "rest": { 40 | "baseURI": "https://slack.com/api", 41 | "bearerToken": "******", 42 | "tokenLocation": "url", 43 | "tokenParam": "token", 44 | "mediaType": "urlencoded", 45 | "authType": "token", 46 | "encryptedFields": [], 47 | "unencryptedFields": [], 48 | "scope": [], 49 | "pingRelativeURI": "api.test" 50 | }, 51 | "queues": [ 52 | { 53 | "name": "123ab456c789de1011fg12h13i", 54 | "size": 8 55 | } 56 | ] 57 | } 58 | ``` 59 | 60 | #### 2. Ping a specific connection. 61 | 62 | ``` 63 | GET /v1/connections/5541e17a1383a6ce6e00000d/ping HTTP/1.1 64 | Host: api.integrator.io 65 | Authorization: Bearer my_api_token 66 | ``` 67 | 68 | Sample Response: 69 | 70 | ``` 71 | { 72 | "code": 200 73 | } 74 | ``` 75 | 76 | #### 3. Export data out of an external application using a virtual export, with paging (page size 5). 77 | 78 | ``` 79 | POST /v1/connections/5541489353bb53af29000009/export/pages HTTP/1.1 80 | Host: api.integrator.io 81 | Authorization: Bearer my_api_token 82 | 83 | { 84 | "export": { 85 | "asynchronous": true, // deprecating this field soon, but for now please set to true always. 86 | "pageSize": 5, 87 | "netsuite": { 88 | "type": "search", 89 | "searches": [{ 90 | "recordType": "customRecord", 91 | "savedSearchId": "123456" 92 | }], 93 | "skipGrouping": true 94 | } 95 | } 96 | } 97 | ``` 98 | Sample Response: 99 | ``` 100 | { 101 | "data": [ 102 | { 103 | "recType": "813", 104 | "Trial Start": "2017-09-15T14:02:00.000-07:00", 105 | "custrecord_license2_trial_end_date": "2017-10-19T07:00:00.000+00:00", 106 | "custrecord_usage_diy_phone": "5555555555", 107 | "custrecord_usage_diy_ms": 65894782, 108 | "custrecord_usage_diy_year": 2017, 109 | "custrecord_usage_diy_company": "Doej1", 110 | "custrecord_usage_diy_userid": "123ab456c789de1011", 111 | "custrecord_usage_diy_name": "John Doe", 112 | "custrecord_usage_diy_hours": 18, 113 | "custrecord_usage_diy_role": "Consultant", 114 | "custrecord_usage_diy_email": "jdoe@doej1.com", 115 | "custrecord_usage_diy_month_s": "November" 116 | }, 117 | { 118 | "recType": "813", 119 | "Trial Start": "2016-11-22T12:26:00.000-08:00", 120 | "custrecord_license2_trial_end_date": "2017-06-22T07:00:00.000+00:00", 121 | "custrecord_usage_diy_phone": "5555555555", 122 | "custrecord_usage_diy_ms": 44439899, 123 | "custrecord_usage_diy_year": 2017, 124 | "custrecord_usage_diy_company": "JDOE1", 125 | "custrecord_usage_diy_userid": "123ab456c789de1011", 126 | "custrecord_usage_diy_name": "Nicole Jimenez", 127 | "custrecord_usage_diy_hours": 12, 128 | "custrecord_usage_diy_role": "Technology", 129 | "custrecord_usage_diy_email": "jane.doe@jdoe1.com", 130 | "custrecord_usage_diy_month_s": "November" 131 | }, 132 | { 133 | "recType": "813", 134 | "Trial Start": "2017-11-13T01:31:00.000-08:00", 135 | "custrecord_license2_trial_end_date": "2017-12-13T08:00:00.000+00:00", 136 | "custrecord_usage_diy_phone": "5555555555", 137 | "custrecord_usage_diy_ms": 33199382, 138 | "custrecord_usage_diy_year": 2017, 139 | "custrecord_usage_diy_company": "SDOE1", 140 | "custrecord_usage_diy_userid": "123ab456c789de1011", 141 | "custrecord_usage_diy_name": "Peter Glebovskiy", 142 | "custrecord_usage_diy_hours": 9, 143 | "custrecord_usage_diy_role": "Manager", 144 | "custrecord_usage_diy_email": "sarah.doe@sdoe1.doe.com", 145 | "custrecord_usage_diy_month_s": "November" 146 | }, 147 | { 148 | "recType": "813", 149 | "Trial Start": "2016-03-02T16:20:00.000-08:00", 150 | "custrecord_license2_trial_end_date": "2017-08-01T07:00:00.000+00:00", 151 | "custrecord_usage_diy_ms": 24450156, 152 | "custrecord_usage_diy_year": 2017, 153 | "custrecord_usage_diy_userid": "123ab456c789de1011", 154 | "custrecord_usage_diy_name": "Ko Doe", 155 | "custrecord_usage_diy_hours": 7, 156 | "custrecord_usage_diy_email": "kd@ko.doe.com", 157 | "custrecord_usage_diy_month_s": "November" 158 | }, 159 | { 160 | "recType": "813", 161 | "Trial Start": "2016-12-20T04:26:00.000-08:00", 162 | "custrecord_license2_trial_end_date": "2017-12-31T08:00:00.000+00:00", 163 | "custrecord_usage_diy_ms": 20146954, 164 | "custrecord_usage_diy_year": 2017, 165 | "custrecord_usage_diy_company": "TheDOE", 166 | "custrecord_usage_diy_userid": "123ab456c789de1011", 167 | "custrecord_usage_diy_name": "Marcus Doe", 168 | "custrecord_usage_diy_hours": 6, 169 | "custrecord_usage_diy_email": "marc.doe@doedoe.m.com", 170 | "custrecord_usage_diy_month_s": "November" 171 | } 172 | ], 173 | "dataURIs": [ 174 | null, 175 | null, 176 | null, 177 | null, 178 | null 179 | ], 180 | "pagedExportState": { 181 | "searchId": "WEBSERVICES_589861_11292017182391545425518660_73666d20757aff", 182 | "pageIndex": 2, 183 | "pageSize": 5, 184 | "totalPages": 165, 185 | "totalRecords": 822, 186 | "done": false, 187 | "issuedAt": 1512010880, 188 | "sig": "ac7463cf6160937468e5cc575f541d438763719f5985c0ee85642e0de4d75d0d" 189 | } 190 | } 191 | ``` 192 | 193 | #### 4. Building on example #3, let's get the next page of data for the same virtual export by including the exact pagedExportState obj that was returned by the first API response. And then of course to get the next next page after this one you would just submit the pagedExportState returned by this API response. 194 | 195 | ``` 196 | POST /v1/connections/5541489353bb53af29000009/export/pages HTTP/1.1 197 | Host: api.integrator.io 198 | Authorization: Bearer my_api_token 199 | 200 | { 201 | "pagedExportState": { 202 | "searchId": "WEBSERVICES_589861_11292017182391545425518660_73666d20757aff", 203 | "pageIndex": 2, 204 | "pageSize": 5, 205 | "totalPages": 165, 206 | "totalRecords": 822, 207 | "done": false, 208 | "issuedAt": 1512010880, 209 | "sig": "ac7463cf6160937468e5cc575f541d438763719f5985c0ee85642e0de4d75d0d" 210 | }, 211 | "export": { 212 | "asynchronous": true, 213 | "pageSize": 5, 214 | "netsuite": { 215 | "type": "search", 216 | "searches": [{ 217 | "recordType": "customRecord", 218 | "savedSearchId": "123456" 219 | }], 220 | "skipGrouping": true 221 | } 222 | } 223 | } 224 | ``` 225 | 226 | Sample Response: 227 | ``` 228 | { 229 | "data": [ 230 | { 231 | "recType": "813", 232 | "Trial Start": "2017-06-14T09:02:00.000-07:00", 233 | "custrecord_license2_trial_end_date": "2017-09-30T07:00:00.000+00:00", 234 | "custrecord_usage_diy_year": 2017, 235 | "custrecord_usage_diy_hours": 4, 236 | "custrecord_usage_diy_month_s": "November" 237 | }, 238 | { 239 | "recType": "813", 240 | "Trial Start": "2016-03-09T08:18:00.000-08:00", 241 | "custrecord_license2_trial_end_date": "2017-09-02T07:00:00.000+00:00", 242 | "custrecord_usage_diy_year": 2017, 243 | "custrecord_usage_diy_hours": 2, 244 | "custrecord_usage_diy_month_s": "November" 245 | }, 246 | { 247 | "recType": "813", 248 | "Trial Start": "2016-11-17T12:25:00.000-08:00", 249 | "custrecord_license2_trial_end_date": "2017-12-04T08:00:00.000+00:00", 250 | "custrecord_usage_diy_year": 2017, 251 | "custrecord_usage_diy_hours": 2, 252 | "custrecord_usage_diy_month_s": "November" 253 | }, 254 | { 255 | "recType": "813", 256 | "Trial Start": "2017-10-31T11:30:00.000-07:00", 257 | "custrecord_license2_trial_end_date": "2017-12-02T08:00:00.000+00:00", 258 | "custrecord_usage_diy_year": 2017, 259 | "custrecord_usage_diy_hours": 1, 260 | "custrecord_usage_diy_month_s": "November" 261 | }, 262 | { 263 | "recType": "813", 264 | "Trial Start": "2017-09-16T16:02:00.000-07:00", 265 | "custrecord_license2_trial_end_date": "2017-12-25T08:00:00.000+00:00", 266 | "custrecord_usage_diy_year": 2017, 267 | "custrecord_usage_diy_hours": 1, 268 | "custrecord_usage_diy_month_s": "November" 269 | } 270 | ], 271 | "dataURIs": [ 272 | null, 273 | null, 274 | null, 275 | null, 276 | null 277 | ], 278 | "pagedExportState": { 279 | "searchId": "WEBSERVICES_589861_11292017182391545425518660_73666d20757aff", 280 | "pageIndex": 3, 281 | "pageSize": 5, 282 | "totalPages": 165, 283 | "totalRecords": 822, 284 | "done": false, 285 | "issuedAt": 1512010952, 286 | "sig": "de523935aa3831a8d4ab49e788b22ba5c1be021a60db597b7c5a0033a669af9f" 287 | } 288 | } 289 | ``` 290 | 291 | #### 5. Import 4 records into an external application using a virtual import. The 'import' obj in the request defines how the data should be imported, and the 'data' array contains all the records that you want to import. 292 | ``` 293 | POST /v1/connections/5a1498b3bc227369ab2aa77b/import HTTP/1.1 294 | Host: api.integrator.io 295 | Authorization: Bearer my_api_token 296 | 297 | { 298 | "import": { 299 | "mapping": { 300 | "fields": [ 301 | { 302 | "extract": "timestamp", 303 | "generate": "timestamp" 304 | }, 305 | { 306 | "generate": "key", 307 | "hardCodedValue": "sqs_flow" 308 | } 309 | ] 310 | }, 311 | "rest": { 312 | "relativeURI": [ 313 | "/system/v1/heartbeat" 314 | ], 315 | "method": [ 316 | "PUT" 317 | ] 318 | } 319 | }, 320 | "data": [ 321 | {"timestamp": 1512012818751}, 322 | {"timestamp": 1512012818751}, 323 | {"timestamp": 1512012818751}, 324 | {"timestamp": 1512012818751} 325 | ] 326 | } 327 | ``` 328 | Sample Response: 329 | 330 | ``` 331 | [ 332 | { 333 | "statusCode": 200, 334 | "id": "123ab456c789de1011fg12h13i", 335 | "_json": { 336 | "_id": "123ab456c789de1011fg12h13i", 337 | "lastModified": "2017-11-30T03:33:51.703Z", 338 | "createdAt": "2017-11-21T21:37:10.497Z", 339 | "key": "sqs_flow", 340 | "timestamp": "2017-11-30T03:33:38.751Z", 341 | "__v": 0 342 | } 343 | }, 344 | { 345 | "statusCode": 200, 346 | "id": "123ab456c789de1011fg12h13i", 347 | "_json": { 348 | "_id": "123ab456c789de1011fg12h13i", 349 | "lastModified": "2017-11-30T03:33:51.704Z", 350 | "createdAt": "2017-11-21T21:37:10.497Z", 351 | "key": "sqs_flow", 352 | "timestamp": "2017-11-30T03:33:38.751Z", 353 | "__v": 0 354 | } 355 | }, 356 | { 357 | "statusCode": 200, 358 | "id": "123ab456c789de1011fg12h13i", 359 | "_json": { 360 | "_id": "123ab456c789de1011fg12h13i", 361 | "lastModified": "2017-11-30T03:33:51.700Z", 362 | "createdAt": "2017-11-21T21:37:10.497Z", 363 | "key": "sqs_flow", 364 | "timestamp": "2017-11-30T03:33:38.751Z", 365 | "__v": 0 366 | } 367 | }, 368 | { 369 | "statusCode": 200, 370 | "id": "123ab456c789de1011fg12h13i", 371 | "_json": { 372 | "_id": "123ab456c789de1011fg12h13i", 373 | "lastModified": "2017-11-30T03:33:51.701Z", 374 | "createdAt": "2017-11-21T21:37:10.497Z", 375 | "key": "sqs_flow", 376 | "timestamp": "2017-11-30T03:33:38.751Z", 377 | "__v": 0 378 | } 379 | } 380 | ] 381 | ``` 382 | -------------------------------------------------------------------------------- /connector.md: -------------------------------------------------------------------------------- 1 | Connector API 2 | =========== 3 | >**Guidance**: the primary use case for using this API is to automate provisioning and de-provisioning of your SmartConnector product (i.e. based on your website sign ups, or web store purcahses, or a subscription management platform). For example, you might want to allow users to register on your website for a free trial, and then when they click submit then your server backend would use the API below to creates a 30 day trial license. Or, if you are using a formal subscription management platform, and a user's subscription ends, or a user does not submit a payment on time, then you can use the API below to automatically expire their license (thus shutting off their integration). 4 | 5 | ### Endpoints 6 | | Relative URI| Method | Success Code | Description| 7 | |:-----------|:-------|:------------:|:-------------| 8 | |/connectors|GET|200|Get all connectors.| 9 | |/connectors/{_id}|GET|200|Get a specific connector.| 10 | |/connectors|POST|201|Create a new connector.| 11 | |/connectors/{_id}|PUT|200|Update a specific connector.| 12 | |/connectors/{_id}|DELETE|204|Delete a specific connector.| 13 | |/connectors/{_id}/installBase|GET|200|Get the install base for a specific connector.| 14 | |/connectors/{_id}/update|PUT|200|Push update to _integrationIds[].| 15 | |/connectors/{_id}/licenses|GET|200|Get all licenses for a specific connector.| 16 | |/connectors/{_id}/licenses|POST|201|Create new license for a specific connector.| 17 | |/connectors/{_id}/licenses/{_id_of_license}|GET|200|Get a specific license.| 18 | |/connectors/{_id}/licenses/{_id_of_license}|PUT|200|Update a specific license.| 19 | |/connectors/{_id}/licenses/{_id_of_license}|DELETE|204|Delete a specific license.| 20 | 21 | ## Examples 22 | 23 | #### 1. Get a specific connector. 24 | 25 | ``` 26 | GET /v1/connectors/54fa0b38a7044f9252000036 HTTP/1.1 27 | Host: api.integrator.io 28 | Authorization: Bearer my_api_token 29 | ``` 30 | 31 | Sample Response: 32 | 33 | ``` 34 | { 35 | "_id": "123ab456c789de1011fg12h13i", 36 | "name": "Shopify - NetSuite Connector", 37 | "description": "Shopify - NetSuite Connector helps retailers combine the powerful Shopify eCommerce platform with the proven back-office features of NetSuite and keep the orders, customers, fulfillments, billings, items & inventory levels in sync.", 38 | "imageURL": "/images/company-logos/shopify-netsuite.png", 39 | "websiteURL": "http://www.celigo.com/products/netsuite-shopify-connector/", 40 | "contactEmail": "sales@celigo.com", 41 | "handle": "sc4n", 42 | "published": true, 43 | "managed": true, 44 | "_integrationId": "123ab456c789de1011fg12acab", 45 | "_stackId": "5593228187085d362c0444a455", 46 | "installerFunction": "installConnector", 47 | "updateFunction": "updateConnector", 48 | "preUninstallFunction": "preUninstallFunction", 49 | "uninstallerFunction": "uninstallConnector", 50 | "externalInstallerFunction": "installConnectorFromExternalApp", 51 | "lastModified": "2017-09-12T11:47:25.957Z", 52 | "_sharedImportIds": [], 53 | "_sharedExportIds": [], 54 | "_iClientIdMap": [ 55 | { 56 | "_id": false, 57 | "_iClientIds": [ 58 | "123f9dfc4a7d2ca3238e19c123" 59 | ], 60 | "connection": { 61 | "type": "netsuite" 62 | } 63 | } 64 | ], 65 | "applications": [ 66 | "netsuite", 67 | "shopify" 68 | ], 69 | "oAuthServerFlow": { 70 | "_iClientId": "123fa0c93a7044f9252000123" 71 | } 72 | } 73 | ``` 74 | 75 | #### 2. Get all licenses for a specific connector. 76 | 77 | ``` 78 | GET /v1/connectors/54fa0b38a7044f9252000036/licenses HTTP/1.1 79 | Host: api.integrator.io 80 | Authorization: Bearer my_api_token 81 | ``` 82 | 83 | Sample Response: 84 | 85 | ``` 86 | [ 87 | { 88 | "_id": "123ab456c789de1011fg12h13i", 89 | "expires": "2018-11-16T18:29:59.999Z", 90 | "created": "2017-10-24T09:10:59.408Z", 91 | "opts": { 92 | "addonLicenses": [ 93 | { 94 | "licenses": [ 95 | { 96 | "addOnEdition": "standard" 97 | } 98 | ], 99 | "type": "store" 100 | } 101 | ], 102 | "connectorEdition": "standard" 103 | }, 104 | "user": { 105 | "email": "sathvika.dogiparthi@celigo.com", 106 | "_id": "123ab456c789de1011fg12h13i", 107 | "name": "Sathvika Dogiparthi" 108 | }, 109 | "_integrationId": "123ab456c789de1011fg12acab" 110 | }, 111 | { 112 | "_id": "123ab456c789de1011fg12h13i", 113 | "expires": "2025-07-01T00:00:00.000Z", 114 | "created": "2017-10-10T05:01:14.178Z", 115 | "opts": { 116 | "addonLicenses": [ 117 | { 118 | "licenses": [ 119 | { 120 | "addOnEdition": "enterprise" 121 | } 122 | ], 123 | "type": "store" 124 | } 125 | ], 126 | "connectorEdition": "enterprise" 127 | }, 128 | "user": { 129 | "email": "ron.doe@doe.doe.com" 130 | } 131 | } 132 | ] 133 | ``` 134 | #### 3. Create a new license for a specific connector. 135 | **Important**: the API to create a new license (vs update an existing license) is somewhat unique in that you need to supply the email address of the integrator.io user in the post body, and then the integrator.io backend will use the email to dynamically find the correct user. Assuming the email is a valid user, you will see a read-only "user" property in the response, and then once the user clicks the install button from within their integrator.io account you will then see their "\_id" and "name" values as well if you do another GET on the license resource (or just view it in your integrator.io account UI). 136 | 137 | ``` 138 | POST /v1/connectors/54fa0b38a7044f9252000036/licenses HTTP/1.1 139 | Host: api.integrator.io 140 | Authorization: Bearer my_api_token 141 | 142 | { 143 | "email": "test@celigo.com", 144 | "expires": "2017-11-01T18:29:59.999Z", 145 | "opts": { 146 | "addonLicenses": [ 147 | { 148 | "licenses": [ 149 | { 150 | "addOnEdition": "standard" 151 | } 152 | ], 153 | "type": "store" 154 | } 155 | ], 156 | "connectorEdition": "standard" 157 | } 158 | } 159 | 160 | ``` 161 | 162 | Sample Response: 163 | 164 | ``` 165 | { 166 | "_id": "123ab456c789de1011fg12h13i", 167 | "expires": "2017-11-01T18:29:59.999Z", 168 | "created": "2017-10-24T16:22:11.448Z", 169 | "opts": { 170 | "connectorEdition": "standard", 171 | "addonLicenses": [ 172 | { 173 | "type": "store", 174 | "licenses": [ 175 | { 176 | "addOnEdition": "standard" 177 | } 178 | ] 179 | } 180 | ] 181 | }, 182 | "user": { 183 | "email": "test@celigo.com" 184 | } 185 | } 186 | ``` 187 | 188 | #### 4. Update the license created above to change the expires date and also provision the enterprise version of the connector. 189 | **Small note**: unlike the API to create new licenses (detailed above), you do NOT need to send "email" to update existing license records. 190 | ``` 191 | PUT /v1/connectors/54fa0b38a7044f9252000036/licenses/59ef68b384b38c7986d54549 HTTP/1.1 192 | Host: api.integrator.io 193 | Authorization: Bearer my_api_token 194 | 195 | { 196 | "expires": "2020-11-01T18:29:59.999Z", 197 | "opts": { 198 | "addonLicenses": [ 199 | { 200 | "licenses": [ 201 | { 202 | "addOnEdition": "enterprise" 203 | } 204 | ], 205 | "type": "store" 206 | } 207 | ], 208 | "connectorEdition": "enterprise" 209 | } 210 | } 211 | ``` 212 | 213 | Sample Response: 214 | 215 | ``` 216 | { 217 | "_id": "123ab456c789de1011fg12h13i", 218 | "expires": "2020-11-01T18:29:59.999Z", 219 | "created": "2017-10-24T16:22:11.448Z", 220 | "opts": { 221 | "connectorEdition": "enterprise", 222 | "addonLicenses": [ 223 | { 224 | "type": "store", 225 | "licenses": [ 226 | { 227 | "addOnEdition": "enterprise" 228 | } 229 | ] 230 | } 231 | ] 232 | }, 233 | "user": { 234 | "email": "test@celigo.com", 235 | "_id": "123ab456c789de1011fg12h13i", 236 | "name": "Celigo Tester" 237 | }, 238 | "_integrationId": "123ab456c789de1011fg12acab" 239 | } 240 | ``` 241 | 242 | #### 5. Create a license for someone that has not signed up for integrator.io yet. 243 | 244 | ``` 245 | POST /v1/connectors/54fa0b38a7044f9252000036/licenses HTTP/1.1 246 | Host: api.integrator.io 247 | Authorization: Bearer my_api_token 248 | 249 | { 250 | "email": "does_not_exist@celigo.com", 251 | "expires": "2017-11-01T18:29:59.999Z", 252 | "opts": { 253 | "addonLicenses": [ 254 | { 255 | "licenses": [ 256 | { 257 | "addOnEdition": "standard" 258 | } 259 | ], 260 | "type": "store" 261 | } 262 | ], 263 | "connectorEdition": "standard" 264 | } 265 | } 266 | ``` 267 | 268 | Sample Response: 269 | 270 | ``` 271 | { 272 | "errors": [ 273 | { 274 | "code": "invalid_user", 275 | "message": "We were not able to find any user with the provided email address. Please ask the user to first create an integrator.io account." 276 | } 277 | ] 278 | } 279 | ``` 280 | -------------------------------------------------------------------------------- /export.md: -------------------------------------------------------------------------------- 1 | Export API 2 | ========== 3 | >**Guidance**: this API is typically only needed for SmartConnector development (where you need to create exports in your installer, or dynamically configure exports based on settings that you expose in your app), or for Embedded Integration development (where you want to automate deploying your exports via cloning or dynamically creating them from scratch). 4 | 5 | ### Endpoints 6 | | Relative URI| Method | Success Code | Description| 7 | |:-------------------|:-------|:------------:|:------------------------------| 8 | |/exports|GET|200|Get all exports.| 9 | |/exports/{_id}|GET|200|Get a specific export.| 10 | |/exports|POST|201|Create a new export.| 11 | |/exports/{_id}|PUT|200|Update a specific export.| 12 | |/exports/{_id}|DELETE|204|Delete a specific export.| 13 | |/exports/:_id/distributed|GET|200|Get the distributed configuration for a specific export (i.e. the fields stored directly in the export application). Note that this API is currently only needed for Salesforce and NetSuite real-time exports.| 14 | |/exports/:_id/distributed|PUT|200|Update the distributed configuration for a specific export (i.e. the fields stored directly in the export application). Note that this API is currently only needed for Salesforce and NetSuite real-time exports.| 15 | |/exports/{_id}/clone|POST|201|Clone a specific export.| 16 | 17 | ## Examples 18 | 19 | #### 1. Get a specific export. 20 | 21 | ``` 22 | GET /v1/exports/55ea776bb751843c37b7b366 HTTP/1.1 23 | Host: api.integrator.io 24 | Authorization: Bearer my_api_token 25 | ``` 26 | 27 | Sample Response: 28 | 29 | ``` 30 | { 31 | "_id": "123ab456c789de1011fg12h13i", 32 | "lastModified": "2017-04-16T18:56:15.879Z", 33 | "name": "GitHub Event Listener", 34 | "type": "webhook", 35 | "hooks": { 36 | "preSavePage": { 37 | "_stackId": null, 38 | "function": null 39 | } 40 | }, 41 | "webhook": { 42 | "provider": "github", 43 | "key": "******" 44 | } 45 | } 46 | ``` 47 | 48 | #### 2. Update the name field for a specific export. 49 | 50 | ``` 51 | PUT /v1/exports/55ea776bb751843c37b7b366 HTTP/1.1 52 | Host: api.integrator.io 53 | Authorization: Bearer my_api_token 54 | 55 | { 56 | "_id": "123ab456c789de1011fg12h13i", 57 | "lastModified": "2017-04-16T18:56:15.879Z", 58 | "name": "GitHub Event Listener (updated!)", 59 | "type": "webhook", 60 | "hooks": { 61 | "preSavePage": { 62 | "_stackId": null, 63 | "function": null 64 | } 65 | }, 66 | "webhook": { 67 | "provider": "github", 68 | "key": "******" 69 | } 70 | } 71 | ``` 72 | 73 | Sample Response: 74 | 75 | ``` 76 | { 77 | "_id": "123ab456c789de1011fg12h13i", 78 | "lastModified": "2017-11-28T19:37:04.180Z", 79 | "name": "GitHub Event Listener (updated!)", 80 | "type": "webhook", 81 | "webhook": { 82 | "provider": "github", 83 | "key": "******" 84 | } 85 | } 86 | ``` 87 | -------------------------------------------------------------------------------- /flow.md: -------------------------------------------------------------------------------- 1 | Flow API 2 | ========== 3 | >**Guidance**: this API is typically only needed for SmartConnector development (where you need to create flows in your installer, or dynamically configure flows based on settings that you expose in your app), or for Embedded Integration development (where you want to automate deploying your flows via cloning or dynamically creating them from scratch). 4 | 5 | ### Endpoints 6 | | Relative URI| Method | Success Code | Description| 7 | |:-------------------|:-------|:------------:|:------------------------------| 8 | |/flows|GET|200|Get all flows.| 9 | |/flows/{_id}|GET|200|Get a specific flow.| 10 | |/flows|POST|201|Create a new flow.| 11 | |/flows/{_id}|PUT|200|Update a specific flow.| 12 | |/flows/{_id}|DELETE|204|Delete a specific flow.| 13 | |/flows/{_id}/clone|POST|201|Clone a specific flow.| 14 | |/flows/{_id}/run|POST|201|Run a specific flow on-demand.| 15 | 16 | 17 | ## Examples 18 | 19 | #### 1. Get a specific simple flow (i.e. a flow with just a single export and import). 20 | 21 | ``` 22 | GET /v1/flows/55ea78c6b751843c37b7b367 HTTP/1.1 23 | Host: api.integrator.io 24 | Authorization: Bearer my_api_token 25 | ``` 26 | 27 | Sample Response: 28 | 29 | ``` 30 | { 31 | "_id": "123ab456c789de1011fg12h13i", 32 | "lastModified": "2017-06-19T21:27:09.945Z", 33 | "name": "Send GitHub Events to Slack", 34 | "disabled": false, 35 | "timezone": "America/Los_Angeles", 36 | "_exportId": "55ea776bb751843c37b7ac6ab0", 37 | "_importId": "55ea78c546cf5825294aca0b", 38 | "_integrationId": "58f107a36b3bdd4f87aca76b", 39 | "skipRetries": false, 40 | "createdAt": "2017-06-19T21:27:09.900Z" 41 | } 42 | ``` 43 | 44 | #### 2. Get a specific orchestrated flow (i.e. a flow with multiple exports and imports linked together). 45 | 46 | ``` 47 | GET /v1/flows/5980e7fedd9939649f8a5d9a HTTP/1.1 48 | Host: api.integrator.io 49 | Authorization: Bearer my_api_token 50 | ``` 51 | 52 | Sample Response: 53 | 54 | ``` 55 | { 56 | "_id": "123ab456c789de1011fg12h13i", 57 | "lastModified": "2017-08-19T17:04:54.005Z", 58 | "name": "Update Usage Stats for all Trialers", 59 | "disabled": false, 60 | "schedule": "? 0 2 ? * *", 61 | "timezone": "America/Los_Angeles", 62 | "_integrationId": "58f107a36b3bdd4f87aca76b", 63 | "skipRetries": false, 64 | "pageProcessors": [ 65 | { 66 | "type": "export", 67 | "_exportId": "55ea776bb751843c37b7ac6ab0", 68 | "responseMapping": { 69 | "lists": [], 70 | "fields": [ 71 | { 72 | "extract": "data", 73 | "generate": "numConnections" 74 | } 75 | ] 76 | } 77 | }, 78 | { 79 | "type": "export", 80 | "_exportId": "55ea776bb751843c37b7ac6ab0", 81 | "responseMapping": { 82 | "lists": [], 83 | "fields": [ 84 | { 85 | "extract": "data", 86 | "generate": "dlSuccessAndErrors" 87 | } 88 | ] 89 | } 90 | }, 91 | { 92 | "type": "export", 93 | "_exportId": "55ea776bb751843c37b7ac6ab0", 94 | "responseMapping": { 95 | "lists": [], 96 | "fields": [ 97 | { 98 | "extract": "data", 99 | "generate": "lastSignIn" 100 | } 101 | ] 102 | } 103 | }, 104 | { 105 | "type": "export", 106 | "_exportId": "55ea776bb751843c37b7ac6ab0", 107 | "responseMapping": { 108 | "lists": [], 109 | "fields": [ 110 | { 111 | "extract": "data", 112 | "generate": "numDataLoaders" 113 | } 114 | ] 115 | } 116 | }, 117 | { 118 | "type": "export", 119 | "_exportId": "55ea776bb751843c37b7ac6ab0", 120 | "responseMapping": { 121 | "lists": [], 122 | "fields": [ 123 | { 124 | "extract": "data", 125 | "generate": "numFlows" 126 | } 127 | ] 128 | } 129 | }, 130 | { 131 | "type": "export", 132 | "_exportId": "55ea776bb751843c37b7ac6ab0", 133 | "responseMapping": { 134 | "lists": [], 135 | "fields": [ 136 | { 137 | "extract": "data", 138 | "generate": "numPasswordChanges" 139 | } 140 | ] 141 | } 142 | }, 143 | { 144 | "type": "export", 145 | "_exportId": "55ea776bb751843c37b7ac6ab0", 146 | "responseMapping": { 147 | "lists": [], 148 | "fields": [ 149 | { 150 | "extract": "data", 151 | "generate": "numPasswordResets" 152 | } 153 | ] 154 | } 155 | }, 156 | { 157 | "type": "export", 158 | "_exportId": "55ea776bb751843c37b7ac6ab0", 159 | "responseMapping": { 160 | "lists": [], 161 | "fields": [ 162 | { 163 | "extract": "data", 164 | "generate": "numSignIns" 165 | } 166 | ] 167 | } 168 | }, 169 | { 170 | "type": "export", 171 | "_exportId": "55ea776bb751843c37b7ac6ab0", 172 | "responseMapping": { 173 | "lists": [], 174 | "fields": [ 175 | { 176 | "extract": "data", 177 | "generate": "successAndErrors" 178 | } 179 | ] 180 | } 181 | }, 182 | { 183 | "type": "import", 184 | "_importId": "55ea776bb751843c37b7ac6ab0", 185 | "proceedOnFailure": true, 186 | "responseMapping": { 187 | "lists": [], 188 | "fields": [] 189 | } 190 | }, 191 | { 192 | "type": "import", 193 | "_importId": "55ea776bb751843c37b7ac6ab0", 194 | "responseMapping": { 195 | "lists": [], 196 | "fields": [] 197 | } 198 | } 199 | ], 200 | "pageGenerators": [ 201 | { 202 | "_exportId": "55ea776bb751843c37b7ac6ab0", 203 | "_id": "123ab456c789de1011fg12h13i" 204 | }, 205 | { 206 | "_exportId": "55ea776bb751843c37b7ac6ab0", 207 | "_id": "123ab456c789de1011fg12h13i" 208 | } 209 | ], 210 | "createdAt": "2017-08-01T20:43:42.156Z" 211 | } 212 | ``` 213 | -------------------------------------------------------------------------------- /iClient.md: -------------------------------------------------------------------------------- 1 | iClient API 2 | =========== 3 | >**Guidance**: currently the integrator.io UI does not support creating and/or editing iClient resources, and using the API is the only way to work with this resource type. 4 | 5 | ### Endpoints 6 | | Relative URI| Method | Success Code | Description| 7 | |:-------------------|:-------|:------------:|:------------------------------| 8 | |/iclients|GET|200|Get all iClients.| 9 | |/iclients/{_id}|GET|200|Get a specific iClient.| 10 | |/iclients|POST|201|Create a new iClient.| 11 | |/iclients/{_id}|PUT|200|Update a specific iClient.| 12 | |/iclients/{_id}|DELETE|204|Delete a specific iClient.| 13 | 14 | ### Fields 15 | 16 | | Field| Description| 17 | |:------------|:------------| 18 | | **provider**|Supported providers include the following: google, salesforce, azureoauth, windowslive, shopify, integrator, zendesk, bigcommerce, netsuite, ebay, amazonmws, ebay-xml, asana, box, dropbox, clover, servicenow, jobvite, twilio, certify', dropbox, squareup, docusign, and woocommerce| 19 | | **oauth2.clientId**|| 20 | | **oauth2.clientSecret**|| 21 | | **oauth2.scope**|| 22 | | **oauth2.scopeDelimiter**|| 23 | | **oauth2.redirectUri**|| 24 | | **netsuite.consumerKey**|| 25 | | **netsuite.consumerSecret**|| 26 | | **salesforce.clientId**|| 27 | | **salesforce.clientSecret**|| 28 | | **salesforce.apiToken**|| 29 | | **salesforce.privateKey**|| 30 | | **salesforce.publicKey**|| 31 | | **amazonmws.accessKeyId**|| 32 | | **amazonmws.secretKey**|| 33 | | **ebay.appId**|| 34 | | **ebay.devId**|| 35 | | **ebay.certId**|| 36 | | **ebay.ruName**|| 37 | 38 | 39 | ## Examples 40 | 41 | #### 1. Get all iClients. 42 | 43 | ``` 44 | GET /v1/iclients HTTP/1.1 45 | Host: api.integrator.io 46 | Authorization: Bearer my_api_token 47 | ``` 48 | 49 | Sample Response: 50 | 51 | ``` 52 | [ 53 | { 54 | "_id": "123ab456c789de1011fg12h13i", 55 | "name": "Amazon - North America", 56 | "lastModified": "2017-03-15T10:07:54.070Z", 57 | "provider": "amazonmws", 58 | "amazonmws": { 59 | "accessKeyId": "abcdef12345", 60 | "secretKey": "******" 61 | } 62 | }, 63 | { 64 | "_id": "123ab456c789de1011fg12h13i", 65 | "name": "eBay Sandbox", 66 | "lastModified": "2017-04-12T07:50:56.863Z", 67 | "provider": "ebay-xml", 68 | "ebay": { 69 | "appId": "Celigo-XXXX", 70 | "devId": "abcdef12345", 71 | "certId": "******", 72 | "ruName": "Celigo-ABC" 73 | } 74 | }, 75 | { 76 | "_id": "123ab456c789de1011fg12h13i", 77 | "name": "eBay", 78 | "lastModified": "2017-04-12T07:51:17.839Z", 79 | "provider": "ebay-xml", 80 | "ebay": { 81 | "appId": "Celigo-YYYY", 82 | "devId": "zyxwvu12345", 83 | "certId": "******", 84 | "ruName": "Celigo-XYZ" 85 | } 86 | }, 87 | { 88 | "_id": "123ab456c789de1011fg12h13i", 89 | "name": "NetSuite", 90 | "lastModified": "2017-04-21T10:32:37.100Z", 91 | "provider": "netsuite", 92 | "netsuite": { 93 | "consumerKey": "******", 94 | "consumerSecret": "******" 95 | } 96 | }, 97 | { 98 | "_id": "123ab456c789de1011fg12h13i", 99 | "lastModified": "2015-12-09T11:17:23.235Z", 100 | "provider": "Shopify", 101 | "oauth2": { 102 | "clientId": "c12345", 103 | "clientSecret": "******", 104 | "scope": [ 105 | "read_products", 106 | "write_products", 107 | "read_customers", 108 | "read_orders", 109 | "write_orders" 110 | ], 111 | "scopeDelimiter": "," 112 | } 113 | } 114 | ] 115 | ``` 116 | -------------------------------------------------------------------------------- /import.md: -------------------------------------------------------------------------------- 1 | Import API 2 | ========== 3 | >**Guidance**: this API is typically only needed for SmartConnector development (where you need to create imports in your installer, or dynamically configure imports based on settings that you expose in your app), or for Embedded Integration development (where you want to automate deploying your imports via cloning or dynamically creating them from scratch). 4 | 5 | 6 | ### Endpoints 7 | | Relative URI| Method | Success Code | Description| 8 | |:-------------------|:-------|:------------:|:------------------------------| 9 | |/imports|GET|200|Get all imports.| 10 | |/imports/{_id}|GET|200|Get a specific import.| 11 | |/imports|POST|201|Create a new import.| 12 | |/imports/{_id}|PUT|200|Update a specific import.| 13 | |/imports/{_id}|DELETE|204|Delete a specific import.| 14 | |/imports/{_id}/clone|POST|201|Clone a specific import.| 15 | 16 | ## Examples 17 | 18 | #### 1. Get a specific import. 19 | 20 | ``` 21 | GET /v1/imports/594d5058c5a4c41a4ba4b662 HTTP/1.1 22 | Host: api.integrator.io 23 | Authorization: Bearer my_api_token 24 | ``` 25 | 26 | Sample Response: 27 | 28 | ``` 29 | { 30 | "_id": "123ab456c789de1011fg12h13i", 31 | "lastModified": "2017-11-28T18:38:19.851Z", 32 | "name": "Upload File to FTP Site", 33 | "_connectionId": "56fd5ad09aa1825c4e678aca76", 34 | "distributed": false, 35 | "apiIdentifier": "ib8f75411f4", 36 | "file": { 37 | "skipAggregation": false, 38 | "type": "csv", 39 | "csv": { 40 | "rowDelimiter": "\n", 41 | "columnDelimiter": ",", 42 | "includeHeader": false, 43 | "wrapWithQuotes": false, 44 | "replaceTabWithSpace": false, 45 | "replaceNewlineWithSpace": false 46 | } 47 | }, 48 | "ftp": { 49 | "directoryPath": "/test", 50 | "fileName": "file-{{timestamp}}.csv" 51 | }, 52 | "mapping": { 53 | "fields": [ 54 | { 55 | "extract": "internal_id", 56 | "generate": "id" 57 | }, 58 | { 59 | "extract": "item_id", 60 | "generate": "sku" 61 | }, 62 | { 63 | "extract": "name", 64 | "generate": "name" 65 | }, 66 | { 67 | "extract": "sales_description", 68 | "generate": "description" 69 | }, 70 | { 71 | "extract": "rate", 72 | "generate": "price" 73 | }, 74 | { 75 | "extract": "qty_on_hand", 76 | "generate": "qty" 77 | } 78 | ] 79 | } 80 | } 81 | ``` 82 | 83 | #### 2. Update a specific import to change the name field and also one of the field mappings. 84 | 85 | ``` 86 | PUT /v1/imports/594d5058c5a4c41a4ba4b662 HTTP/1.1 87 | Host: api.integrator.io 88 | Authorization: Bearer my_api_token 89 | 90 | { 91 | "_id": "123ab456c789de1011fg12h13i", 92 | "lastModified": "2017-06-23T17:31:04.446Z", 93 | "name": "Upload File to FTP Site (updated!)", 94 | "_connectionId": "56fd5ad09aa1825c4e678aca76", 95 | "distributed": false, 96 | "apiIdentifier": "ib8f75411f4", 97 | "file": { 98 | "skipAggregation": false, 99 | "type": "csv", 100 | "lookups": [], 101 | "csv": { 102 | "rowDelimiter": "\n", 103 | "columnDelimiter": ",", 104 | "includeHeader": false, 105 | "wrapWithQuotes": false, 106 | "replaceTabWithSpace": false, 107 | "replaceNewlineWithSpace": false 108 | } 109 | }, 110 | "ftp": { 111 | "directoryPath": "/test", 112 | "fileName": "file-{{timestamp}}.csv" 113 | }, 114 | "mapping": { 115 | "fields": [ 116 | { 117 | "extract": "internal_id", 118 | "generate": "updated_id" 119 | }, 120 | { 121 | "extract": "item_id", 122 | "generate": "sku" 123 | }, 124 | { 125 | "extract": "name", 126 | "generate": "name" 127 | }, 128 | { 129 | "extract": "sales_description", 130 | "generate": "description" 131 | }, 132 | { 133 | "extract": "rate", 134 | "generate": "price" 135 | }, 136 | { 137 | "extract": "qty_on_hand", 138 | "generate": "qty" 139 | } 140 | ] 141 | } 142 | } 143 | ``` 144 | 145 | Sample Response: 146 | 147 | ``` 148 | { 149 | "_id": "123ab456c789de1011fg12h13i", 150 | "lastModified": "2017-11-28T18:47:09.553Z", 151 | "name": "Upload File to FTP Site (updated!)", 152 | "_connectionId": "56fd5ad09aa1825c4e678aca76", 153 | "distributed": false, 154 | "apiIdentifier": "ib8f75411f4", 155 | "file": { 156 | "skipAggregation": false, 157 | "type": "csv", 158 | "csv": { 159 | "rowDelimiter": "\n", 160 | "columnDelimiter": ",", 161 | "includeHeader": false, 162 | "wrapWithQuotes": false, 163 | "replaceTabWithSpace": false, 164 | "replaceNewlineWithSpace": false 165 | } 166 | }, 167 | "ftp": { 168 | "directoryPath": "/test", 169 | "fileName": "file-{{timestamp}}.csv" 170 | }, 171 | "mapping": { 172 | "fields": [ 173 | { 174 | "extract": "internal_id", 175 | "generate": "updated_id" 176 | }, 177 | { 178 | "extract": "item_id", 179 | "generate": "sku" 180 | }, 181 | { 182 | "extract": "name", 183 | "generate": "name" 184 | }, 185 | { 186 | "extract": "sales_description", 187 | "generate": "description" 188 | }, 189 | { 190 | "extract": "rate", 191 | "generate": "price" 192 | }, 193 | { 194 | "extract": "qty_on_hand", 195 | "generate": "qty" 196 | } 197 | ] 198 | } 199 | } 200 | ``` 201 | -------------------------------------------------------------------------------- /integration.md: -------------------------------------------------------------------------------- 1 | Integration API 2 | =========== 3 | >**Guidance**: this API is typically only needed for SmartConnector development where you need to work with the SmartConnector only fields listed below, or Embedded Integration development where you want to automate deploying your integration solution (either via cloning or dynamically creating everything from scratch). 4 | 5 | 6 | ### Endpoints 7 | | Relative URI| Method | Success Code | Description| 8 | |:-------------------|:-------|:------------:|:------------------------------| 9 | |/integrations|GET|200|Get all integrations.| 10 | |/integrations/{_id}|GET|200|Get a specific integration.| 11 | |/integrations|POST|201|Create a new integration.| 12 | |/integrations/{_id}|PUT|200|Update a specific integration.| 13 | |/integrations/{_id}|DELETE|204|Delete a specific integration.| 14 | |/integrations/{_id}/clone|POST|201|Clone a specific integration.| 15 | 16 | ### SmartConnector Only Fields 17 | 18 | | Field| Description| 19 | |:------------|:------------| 20 | | **mode**|For the most part this is a read-only field used by the integrator.io UI. Valid values are 'install', 'settings', and 'uninstall'. The value 'install' is used to indicate that the integration is still being installed by the user. The value 'settings' is used to indicate that the integration is done installing, and that the user has access to the settings page for the integration. The value 'uninstall' is used to indicate that the integration is being uninstalled.| 21 | | **settings**|This field is used to store the settings (i.e. the configuration) for the SmartConnector integration. For example, when a user opens the settings page for a SmartConnector integration running in their account, and they change a setting, this field is updated, and then also propagated to the SmartConnector's backend to adjust the integration accordingly.| 22 | | **version**|This field is used to store the version of an integration running in the user's integrator.io account. Whenever you push any managed updates to a user's integrator.io account you should always increment the version field as the final step.| 23 | | **updateInProgress**|This field is automatically set to 'true' whenever you push a managed update to a user's integrator.io account. You must explicitly set this field back to 'false' when your update is done. While updateInProgress is 'true' the user will not be allowed to change any settings or mappings in their integration.| 24 | | **install**|This array field is used to specifcy all of the steps that are needed to install the SmartConnector integration in a user's integrator.io account, and is also used to track the state of each step so that the integrator.io UI knows which ones are done vs which one the user should do next, etc...| 25 | 26 | ## Examples 27 | 28 | #### 1. Get a specific DIY integration. 29 | 30 | ``` 31 | GET /v1/integrations/554155c853bb53af2900000b HTTP/1.1 32 | Host: api.integrator.io 33 | Authorization: Bearer my_api_token 34 | ``` 35 | 36 | Sample Response: 37 | 38 | ``` 39 | { 40 | "_id": "123ab456c789de1011fg12h13i", 41 | "lastModified": "2017-08-07T18:34:07.786Z", 42 | "name": "Licensing and Usage", 43 | "readme": "This integration is mission critical and keeps the licensing data..." 44 | } 45 | ``` 46 | 47 | 48 | #### 2. Get a specific SmartConnector integration (notice all the extra fields related to SmartConnectors). 49 | 50 | ``` 51 | GET /v1/integrations/57974ed227a82a3475cecb15 HTTP/1.1 52 | Host: api.integrator.io 53 | Authorization: Bearer my_api_token 54 | ``` 55 | 56 | Sample Response: 57 | 58 | ``` 59 | { 60 | "_id": "123ab456c789de1011fg12h13i", 61 | "lastModified": "2017-09-15T10:55:15.675Z", 62 | "name": "BigCommerce - NetSuite Connector", 63 | "_connectorId": "56fd5ad0945g2345c4e678aca76", 64 | "install": [ 65 | { 66 | "name": "NetSuite Connection", 67 | "description": "Configure NetSuite account credentials", 68 | "imageURL": "/images/company-logos/netsuite.png", 69 | "completed": false, 70 | "installerFunction": "verifyNetSuiteConnection", 71 | "uninstallerFunction": "deleteNetSuiteConnection", 72 | "_connectionId": "56fd5ad0945g2345c4e678aca76" 73 | }, 74 | { 75 | "name": "BigCommerce Connection", 76 | "description": "Configure BigCommerce store credentials", 77 | "imageURL": "/images/company-logos/BigCommerce.png", 78 | "completed": false, 79 | "installerFunction": "verifyBigCommerceConnection", 80 | "uninstallerFunction": "deleteBigCommerceConnection", 81 | "_connectionId": "56fd5ad0945g2345c4e678aca76" 82 | }, 83 | { 84 | "name": "Integrator Bundle", 85 | "description": "Install Integrator Bundle in NetSuite", 86 | "imageURL": "/images/company-logos/netsuite.png", 87 | "installURL": "", 88 | "completed": false, 89 | "installerFunction": "verifyIntegratorBundleInstallation", 90 | "uninstallerFunction": "uninstallVerifyIntegratorBundle" 91 | }, 92 | { 93 | "name": "BigCommerce Bundle", 94 | "description": "Install BigCommerce Bundle in NetSuite", 95 | "imageURL": "/images/company-logos/netsuite.png", 96 | "installURL": "", 97 | "completed": false, 98 | "installerFunction": "verifyBigCommerceBundleInstallation", 99 | "uninstallerFunction": "uninstallVerifyBigCommerceBundle" 100 | } 101 | ], 102 | "mode": "install", 103 | "settings": { 104 | "sections": [ 105 | { 106 | "temp": "remove_me" 107 | } 108 | ], 109 | "commonresources": { 110 | "genericExportApiIdentifier": "e7654358b7", 111 | "bigcommerceConnectionId": "56fd5ad09a67g564e678aca76", 112 | "netsuiteConnectionId": "56fd5ad09a67g56412gh23a5" 113 | } 114 | }, 115 | "version": "1.0.1" 116 | } 117 | ``` 118 | -------------------------------------------------------------------------------- /job.md: -------------------------------------------------------------------------------- 1 | Job API 2 | =========== 3 | >**Guidance**: there are lots of use cases for using this API. For example, you might want to extract stats about running integrations, and submit those stats to an anlytics platform. Or, maybe you want to extract all your errors and process them in an external database. The integrator.io UI is always evolving to better support these same use cases too, but if/when the UI falls short then this API is a nice fallback to get at the raw data. 4 | 5 | 6 | ### Endpoints 7 | | Relative URI| Method | Success Code | Description| 8 | |:-----------|:-------|:------------:|:-------------| 9 | |/jobs|GET|200|Get all jobs. The following query parameters are supported: _integrationId, _exportId, _importId, _flowId, _flowJobId, _bulkJobId, _flowId_in, createdAt_lte, createdAt_gte, status, numSuccess_lte, numSuccess_gte, numExport_lte, numExport_gte, numIgnore_lte, numIgnore_gte, retriable, type, and type_in| 10 | |/jobs/{_id}|GET|200|Get a specific job.| 11 | |/jobs/{_id}/joberrors|GET|200|If a job has <= 1000 errors use this API to retrieve the errors directly.| 12 | |/jobs/{_id}/errorFile/signedURL|GET|200|If a job has > 1000 errors, or you prefer to get a file, use this API to get a signed URL that can then be used to download an error file directly from S3.| 13 | 14 | 15 | ## Examples 16 | 17 | #### 1. Get all jobs where type = 'import' and status = 'running'. 18 | 19 | ``` 20 | GET /v1/jobs?type=import&status=running HTTP/1.1 21 | Host: api.integrator.io 22 | Authorization: Bearer my_api_token 23 | ``` 24 | 25 | Sample Response: 26 | 27 | ``` 28 | [ 29 | { 30 | "_id": "123ab456c789de1011fg12h13i", 31 | "type": "import", 32 | "_importId": "55ea78c546cf5825294aca0b", 33 | "_flowJobId": "59ee8f82c41g45g165ef1b9a9", 34 | "startedAt": "2017-10-24T00:55:49.128Z", 35 | "status": "running", 36 | "numError": 0, 37 | "numSuccess": 1, 38 | "numIgnore": 0, 39 | "numPagesProcessed": 1, 40 | "oIndex": 1, 41 | "retriable": false, 42 | "createdAt": "2017-10-24T00:55:49.128Z", 43 | "lastModified": "2017-10-24T00:55:49.642Z" 44 | } 45 | ] 46 | ``` 47 | 48 | #### 2. Get job errors for a specific import job. 49 | 50 | ``` 51 | GET /v1/jobs/59ee8cad03785d04d8469918/jobErrors HTTP/1.1 52 | Host: api.integrator.io 53 | Authorization: Bearer my_api_token 54 | ``` 55 | 56 | Sample Response: 57 | ``` 58 | [ 59 | { 60 | "resolve": false, 61 | "retry": false, 62 | "createdAt": "2017-10-24T00:43:30.434Z", 63 | "code": "422", 64 | "extract": "", 65 | "generate": "", 66 | "extracted": "", 67 | "generated": "", 68 | "message": "'{\"errors\":[{\"field\":\"expires\",\"code\":\"missing_required_field\"}]}'", 69 | "source": "integrator.io", 70 | "exportDataURI": "", 71 | "importDataURI": "", 72 | "_retryId": "59ee8cb20df374sf469sd919", 73 | "_jobId": "59ee8cad03784g7hd8469918" 74 | } 75 | ] 76 | ``` 77 | -------------------------------------------------------------------------------- /readme.md: -------------------------------------------------------------------------------- 1 | Introduction 2 | ============ 3 | 4 | The integrator.io API is RESTful, uses JSON, and is secured by Bearer Tokens. The target audience for the API is developers that are interested in building one or more of the following. 5 | 6 | 1. **Integration Apps**. These are fully managed, pre-built integration apps listed in the [integrator.io marketplace](https://integrator.io/marketplace) that can be installed by any other integrator.io user. These integration apps typically include an installer, uninstaller, licensing controls, settings pages, and receive on-going enhancements in functionality. 7 | 8 | 2. **Embedded Integrations**. These are fully managed integrations where integrator.io remains completely invisible to the end user. These integrations are typically enabled and/or configured within an external application's UI, where that application's backend servers use the integrator.io API to dynamically deploy and customize integration functionality. 9 | 10 | 3. **Hooks**. integrator.io is all about creating and running flows. A flow is composed of one or more exports along with one or more imports. Exports are responsible for pulling data out of an application, and imports are responsible for mapping and inserting data into an application. Hooks are well defined points within the flow where custom code can be run (i.e. to customize the flow beyond what is possible in the integrator.io UI). See [here](https://github.com/celigo/integrator-extension#hooks) for more info. 11 | 12 | 4. **Wrappers**. These can be used to connect applications that are not natively supported by integrator.io. See [here](https://github.com/celigo/integrator-extension#wrappers) for more info. 13 | 14 | Enjoy, and happy integrating! 15 | 16 | 17 | Authentication 18 | ============ 19 | 20 | ### Bearer Tokens 21 | 22 | API tokens can be generated and accessed via 'Resources' -> 'API Tokens' (within your integrator.io account). Please note that only the owner of an integrator.io account can access the API tokens page. API clients should transmit API tokens using the "**Authorization**" request header field and the "**Bearer**" authentication scheme. 23 | 24 | Sample HTTP Request: 25 | 26 | ``` 27 | GET /v1/tokenInfo HTTP/1.1 28 | Host: api.integrator.io 29 | Authorization: Bearer my_api_token 30 | ``` 31 | 32 | Sample Response: 33 | 34 | ``` 35 | HTTP/1.1 200 OK 36 | Content-Type: application/json; charset=utf-8 37 | { 38 | "_userId": "123ab456c789de1011fg12h13i" 39 | } 40 | ``` 41 | 42 | ### One-time Tokens 43 | When using the integrator.io extension framework one-time tokens are also supported (and highly recommended). The one-time tokens are passed in the options argument to each of your functions, and can be used similar to [Bearer Tokens](#bearer-tokens) to call back into integrator.io. One-time tokens auto expire after being used (or after a 15 minute timeout if never used). For SmartConnectors (i.e. managed integration apps), one-time tokens passed are only granted access to invoke the resources that belong to the SmartConnector. 44 | 45 | Resource Types 46 | ========= 47 | > **Very important tip!** The integrator.io UI also uses the API, and if you ever get stuck with the API you can always revert back to the UI to create and/or modify something, and then use your API client (or the browser via https://integrator.io/api/relative_uri_here) to see the resulting JSON. 48 | 49 | ### Connection 50 | 51 | Connections are used to store credentials, along with any other information needed to access the applications you are integrating. 52 | 53 | Click [here](/connection.md) for details. 54 | 55 | ### Export 56 | 57 | Exports are used to extract data from an application. Exports can run standalone via the API, or in the context of a flow. 58 | 59 | Click [here](/export.md) for details. 60 | 61 | ### Import 62 | 63 | Imports are used to insert data into an application. Imports can run standalone via the API, or in the context of a flow. 64 | 65 | Click [here](/import.md) for details. 66 | 67 | ### Flow 68 | 69 | Flows are used to compose exports and imports so that data can be exported out of one or more applications and then imported into one or more applications. 70 | 71 | Click [here](/flow.md) for details. 72 | 73 | ### Integration 74 | 75 | Integrations are used to group flows. All flows that belong to the same integration will share the same permissions, and all stats will bubble up under the same tile on the home page. 76 | 77 | Click [here](/integration.md) for details. 78 | 79 | ### State 80 | 81 | State is an API only resource type that can be used to store arbitrary JSON data (associated with a custom key). Typically the state API is used to persist data about a flow's last execution, and then to use that same data to parameterize the next execution of the flow (i.e. the next time it runs). 82 | 83 | Click [here](/state.md) for details. 84 | 85 | Less Common Resource Types 86 | ----------- 87 | 88 | ### iClient 89 | 90 | iClients are used (mostly) by SmartConnectors to store the authentication data required to connect with a specific API (on behalf of the SmartConnector). For example, if you are building a SmartConnector for Salesforce you will be required (by Salesforce) to register your app, and Salesforce will provide you with a client id, token, etc... and then you can use an iClient to store this data and also make it available ONLY to your SmartConnector install base. 91 | 92 | Click [here](/iClient.md) for details. 93 | 94 | 95 | ### Connector + License 96 | 97 | The connector resource type represents the SmartConnector solutions you build and list in the integrator.io marketplace. This resource type has basic listing type fields to help market your solution, and then developer type fields to specify which functions on your server stack should be invoked when the connector is installed, uninstalled, etc... There is a license resource type available too (within the context of a connector) to formally provision your solution to an end user. And, using the related licensing APIs you can fully automate provisioning of your solution with an external subscription and/or recurring payments platform. You can even use an integrator.io account to manage the data flows between those apps (i.e. integrator.io and subscription/payment platform)! 98 | 99 | Click [here](/connector.md) for details. 100 | 101 | 102 | ### Template 103 | 104 | This is the listing record for Templates in the integrator.io marketplace. Templates are different than SmartConnectors in that they are completely un-managed once installed by end users. 105 | 106 | Click [here](/template.md) for details. 107 | 108 | ### Job 109 | 110 | Jobs represent the state of a flow while it is running (start time, status, percentage complete, etc...), and then the final stats for a flow when it has finished running (num success, num error, end time, etc...). 111 | 112 | Click [here](/job.md) for details. 113 | 114 | 115 | Rate Limiting 116 | ============ 117 | 118 | The integrator.io API is rate limited using a leaky bucket algorithm with a bucket size of 1000 and a fill rate of 300 tokens every 1 second, which approximates to 1,080,000 requests allowed per hour. 119 | 120 | Headers 121 | ============ 122 | 123 | The integrator.io API supports the following custom HTTP headers to facilitate proxing requests directly to a NetSuite RESTlet. 124 | 125 | - Integrator-NetSuite-ScriptId 126 | - Integrator-NetSuite-DeployId 127 | -------------------------------------------------------------------------------- /state.md: -------------------------------------------------------------------------------- 1 | State API 2 | ======== 3 | >**Guidance**: there are lots of use cases for using this very generic key value storage API. The most popular use case is storing state information about the execution of a flow, and then loading that state information before the flow is run to parameterize the behavior of the flow. For example, every time a flow runs increment a sequence counter so that files uploaded to an FTP site can include a unique sequence id in the data (i.e. so that the system processing the files can reject accidental duplicate files, or flag missing files). 4 | 5 | ### Endpoints 6 | | Relative URI| Method | Success Code | Description| 7 | |:-------------------|:-------|:------------:|:------------------------------| 8 | |/state|GET|200|Get all global keys.| 9 | |/state/{key}|GET|200|Get the value associated with the key.| 10 | |/state/{key}|PUT|200|Create/update the value associated with the key.| 11 | |/state/{key}|DELETE|204|Delete the key and value.| 12 | |/state|DELETE|204|Delete all global keys and values. Be careful with this API!| 13 | |/{resource_type}/{_id}/state|GET|200|Get all keys stored underneath a specific resource in your account.| 14 | |/{resource_type}/{_id}/state/{key}|GET|200|Get the resource specific value associated with the key.| 15 | |/{resource_type}/{_id}/state/{key}|PUT|200|Create/update the resource specific value associated with the key.| 16 | |/{resource_type}/{_id}/state/{key}|DELETE|200|Delete the resource specific key and value.| 17 | |/{resource_type}/{_id}/state|DELETE|200|Delete all keys and values stored underneath the resource. Be careful with this API!| 18 | 19 | ## Examples 20 | 21 | #### 1. Get all keys. 22 | 23 | ``` 24 | GET /v1/state HTTP/1.1 25 | Host: api.integrator.io 26 | Authorization: Bearer my_api_token 27 | ``` 28 | 29 | Sample Response: 30 | 31 | ``` 32 | { 33 | "keys": [ 34 | "apple", 35 | "banana" 36 | ] 37 | } 38 | ``` 39 | 40 | #### 2. Get the value for the key "banana". 41 | 42 | ``` 43 | GET /v1/state/banana HTTP/1.1 44 | Host: api.integrator.io 45 | Authorization: Bearer my_api_token 46 | ``` 47 | 48 | Sample Response: 49 | 50 | ``` 51 | { 52 | "message": "Don't slip!" 53 | } 54 | ``` 55 | 56 | #### 3. Update the value for the key "banana". 57 | 58 | ``` 59 | PUT /v1/state/banana HTTP/1.1 60 | Host: api.integrator.io 61 | Authorization: Bearer my_api_token 62 | 63 | {"message": "Don't slip!", "reply": "i didn't!"} 64 | ``` 65 | 66 | Sample Response: 67 | 68 | ``` 69 | OK 70 | ``` 71 | 72 | #### 4. Get the value for the key "banana" (again). 73 | 74 | ``` 75 | GET /v1/state/banana HTTP/1.1 76 | Host: api.integrator.io 77 | Authorization: Bearer my_api_token 78 | ``` 79 | 80 | Sample Response: 81 | 82 | ``` 83 | { 84 | "message": "Don't slip!", 85 | "reply": "i didn't!" 86 | } 87 | ``` 88 | 89 | #### 5. Create a value to track a sequence number for an EDI data import (that would be updated every time the import is run). Note that this state value is stored underneath the related import resource. 90 | 91 | ``` 92 | PUT /v1/imports/55cca9d6f7dc37597700005d/state/sequenceNumber HTTP/1.1 93 | Host: api.integrator.io 94 | Authorization: Bearer my_api_token 95 | 96 | {"counter": 1} 97 | ``` 98 | 99 | Sample Response: 100 | 101 | ``` 102 | Created 103 | ``` 104 | 105 | #### 6. Get the value just created above. 106 | 107 | ``` 108 | GET /v1/imports/55cca9d6f7dc37597700005d/state/sequenceNumber HTTP/1.1 109 | Host: api.integrator.io 110 | Authorization: Bearer my_api_token 111 | ``` 112 | 113 | Sample Response: 114 | 115 | ``` 116 | { 117 | "counter": 1 118 | } 119 | ``` 120 | 121 | #### 7. Get all keys (again). 122 | Note that the key stored underneath the import (that we just created above) was not returned. Only global keys are returned by the top level GET /state API. To return all keys underneath a specific resource you would need to use the more specific state API for that resource. i.e. GET /imports/55cca9d6f7dc37597700005d/state 123 | 124 | ``` 125 | GET /v1/state HTTP/1.1 126 | Host: api.integrator.io 127 | Authorization: Bearer my_api_token 128 | ``` 129 | 130 | Sample Response: 131 | 132 | ``` 133 | { 134 | "keys": [ 135 | "apple", 136 | "banana" 137 | ] 138 | } 139 | ``` 140 | ``` 141 | GET /v1/imports/55cca9d6f7dc37597700005d/state HTTP/1.1 142 | Host: api.integrator.io 143 | Authorization: Bearer my_api_token 144 | ``` 145 | 146 | Sample Response: 147 | 148 | ``` 149 | { 150 | "keys": [ 151 | "sequenceNumber" 152 | ] 153 | } 154 | ``` 155 | -------------------------------------------------------------------------------- /template.md: -------------------------------------------------------------------------------- 1 | Template API 2 | =========== 3 | >**Guidance**: there are no known use cases for accessing the template resource type via API (vs just using the integrator.io UI). For now, this page is just a placeholder, and we will update our guidance if a good use case is ever discovered. :) 4 | 5 | ### Endpoints 6 | | Relative URI| Method | Success Code | Description| 7 | |:-----------|:-------|:------------:|:-------------| 8 | |/templates|GET|200|Get all templates.| 9 | |/templates/{_id}|GET|200|Get a specific template.| 10 | |/templates|POST|201|Create a new template.| 11 | |/templates/{_id}|PUT|200|Update a specific template.| 12 | |/templates/{_id}|DELETE|204|Delete a specific template.| 13 | 14 | 15 | ## Examples 16 | 17 | #### 1. Get all templates in my account. 18 | 19 | ``` 20 | GET /v1/template HTTP/1.1 21 | Host: api.integrator.io 22 | Authorization: Bearer my_api_token 23 | ``` 24 | 25 | Sample Response: 26 | 27 | ``` 28 | [ 29 | { 30 | "_id": "123ab456c789de1011fg12h13i", 31 | "name": "Send GitHub Notifications to Slack", 32 | "description": "This is a very simple integration that listens for commit events in GitHub, and then posts messages to Slack so that people can use Slack to monitor developer activity. The benefit of using this integration vs the free integration provided by Slack is that you can customize how the messages post to Slack. For example, you might want messages to post as if they were sent by the user that triggered the event in GitHub (vs a generic bot type user).", 33 | "imageURL": "https://secure.gravatar.com/avatar/33895cc016e520a2a07131c3753d8d4f?d=mm&s=55", 34 | "websiteURL": "http://www.celigo.com/", 35 | "contactEmail": "template@celigo.com", 36 | "published": true, 37 | "lastModified": "2017-04-24T16:54:25.186Z", 38 | "applications": [ 39 | "github", 40 | "slack" 41 | ] 42 | }, 43 | { 44 | "_id": "123ab456c789de1011fg12h13i", 45 | "name": "Send Travis Build Notifications to Slack", 46 | "description": "This integration listens for build notifications in Travis CI and posts messages to Slack. Very similar to the native integration that Slack has in their integration marketplace, except now you can completely customize how the messages appear in Slack. For example, you might want to minimize the message content that gets sent to Slack to only show the repository, user, and build status.", 47 | "imageURL": "https://secure.gravatar.com/avatar/33895cc016e520a2a07131c3753d8d4f?d=mm&s=55", 48 | "websiteURL": "http://www.celigo.com/", 49 | "contactEmail": "template@celigo.com", 50 | "published": true, 51 | "lastModified": "2017-04-24T16:57:55.663Z", 52 | "applications": [ 53 | "slack", 54 | "travis" 55 | ] 56 | }, 57 | { 58 | "_id": "123ab456c789de1011fg12h13i", 59 | "name": "Send Zendesk Tickets to Slack", 60 | "description": "This integration routes Zendesk tickets into Slack. This integration is used by Celigo's engineering and QA department to keep an eye on all support tickets being logged throughout the day (i.e. without having to login to Zendesk).", 61 | "imageURL": "https://secure.gravatar.com/avatar/33895cc016e520a2a07131c3753d8d4f?d=mm&s=55", 62 | "websiteURL": "http://www.celigo.com/", 63 | "contactEmail": "template@celigo.com", 64 | "published": true, 65 | "lastModified": "2017-04-24T16:58:00.199Z", 66 | "applications": [ 67 | "slack", 68 | "zendesk" 69 | ] 70 | } 71 | ] 72 | ``` 73 | #### 2. Update a specific template in my account. 74 | 75 | ``` 76 | PUT /v1/template/58f12659c468a47a9489242c HTTP/1.1 77 | Host: api.integrator.io 78 | Authorization: Bearer my_api_token 79 | 80 | { 81 | "name": "Give your template a really great name!", 82 | "description": "A good description helps a lot too.", 83 | "imageURL": "https://secure.gravatar.com/avatar/33895cc016e520a2a07131c3753d8d4f?d=mm&s=55", 84 | "websiteURL": "http://www.celigo.com/", 85 | "contactEmail": "template@celigo.com", 86 | "published": true, 87 | "applications": [ 88 | "slack", 89 | "zendesk" 90 | ] 91 | } 92 | ``` 93 | 94 | Sample Response: 95 | 96 | ``` 97 | { 98 | "_id": "123ab456c789de1011fg12h13i", 99 | "name": "Give your template a really great name!", 100 | "description": "A good description helps a lot too.", 101 | "imageURL": "https://secure.gravatar.com/avatar/33895cc016e520a2a07131c3753d8d4f?d=mm&s=55", 102 | "websiteURL": "http://www.celigo.com/", 103 | "contactEmail": "template@celigo.com", 104 | "published": true, 105 | "lastModified": "2017-10-24T15:03:45.140Z", 106 | "applications": [ 107 | "slack", 108 | "zendesk" 109 | ] 110 | } 111 | ``` 112 | --------------------------------------------------------------------------------