Articles in this section

Connection API endpoints

Kathyana Queeman
Updated

download.svg​​ Download Postman collection

Create a connection in integrator.io

Before you begin working with integrator.io APIs

GET /v1/connections/:_id – Get a specific connection

Get a specific connection.

connections.get(_id )

Method

GET

Relative URI

/v1/connections/:_id

Response body structure

 
{
  "_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
    }
  ]
}

PUT /v1/connections/:_id – Update a specific connection

Update a specific connection.

connections.update( connection )

Method

PUT

Relative URI

/v1/connections/:_id

Response body structure

 
{
  "_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
    }
  ]
}

PATCH /v1/connections/:_id – Update part of a connection

Update part of a specific connection.

connections.patch( options )

The following fields are available for update using PATCH. You must use the provided format to update the field.

Fields

Subfields

Data type

name

string

debugDate

date

rest

cookieAuth.successStatusCode

number

http.ping

successPath

string

successValues

array

failPath

string

failValues

array

http.auth

failStatusCode

number

failPath

string

failValues

array

cookie.successStatusCode

number

http.rateLimit

failPath

string

failStatusCode

number

failValues

array

limit

number

van.contentBasedFlowRouter

function

string

_scriptId

objectId

as2.partnerStationInfo.auth

failValues

array

failStatusCode

number

failPath

string

rateLimit.failPath

string

rateLimit.failStatusCode

number

rateLimit.failValues

array

rateLimit.limit

number

debugUntil

date

Method

PATCH

Relative URI

/v1/connections/:_id

Request body structure

 
[
    {
        "op": "replace",
        "path": "/fieldname",
        "value": "newvalue"
    }
]

Response body structure

 
{
  "_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
    }
  ]
}

DELETE /v1/connections/:_id – Delete a connection

Delete a specific connection.

connections.delete( _id )

Method

DELETE

Relative URI

/v1/connections/:_id

GET /v1/connections/:_id/ping – Test that a connection is operational

Test that a specific connection is operational.

Method

GET

Relative URI

/v1/connections/:_id>/ping

POST /v1/connections/ping – Test a virtual connection

Test a virtual connection where all connection details are submitted in the POST body but not saved.

Method

POST

Relative URI

/v1/connections/ping

Request body structure

 
{
  "_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
    }
  ]
}

Response body structure

 
{
  "code": 200
}

GET /v1/connections/:_id/debug/:_resourceId – Get debug logs for a connection

Get debug logs for a given connection by _id. Use the optional _resourceId to filter logs by a specific import or export.

Method

GET

Relative URI

/v1/connections/:_id/debug/:_resourceId

POST /v1/connections/:_id/export – Execute a virtual export

Execute a virtual export using a connection identified by _id by posting the export model to this endpoint.

Method

POST

Relative URI

/v1/connections/:_id/export

Request body structure

 
{
  "export": {
    "name": "sfdummyconnection",
    "_connectionId": "641•••••••••••••••••913",
    "asynchronous": true,
    "oneToMany": false,
    "sandbox": false,
    "rawData": "640•••••••••••••••••••4a8",
    "salesforce": {
      "type": "soql",
      "api": "rest",
      "soql": {
        "query": "Select Name,Email__c,phone,fax from Account where name like 'test7676'"
      }
    },
    "adaptorType": "SalesforceExport"
  }
}

POST /v1/connections/:_id/export/pages – Virtual export execution with paging

Alternative virtual export execution with paging support.

Method

POST

Relative URI

/v1/connections/:_id/export/pages

Request body structure

Export data from an external application using a virtual export, with paging (size 5)

{
  "export": {
    "asynchronous": true,
    "pageSize": 5,
    "netsuite": {
      "type": "search",
      "searches": [
        {
          "recordType": "customRecord",
          "savedSearchId": "131298"
        }
      ],
      "skipGrouping": true
    }
  }
}

Retrieve additional pages

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.

{
  "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
    }
  }
}

Import four records into an external app using a virtual import

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.

{
  "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
    }
  ]
}

Response body structure

Export data from an external application using a virtual export, with paging (size 5)

{
  "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":"999••••••••••••••910",
      "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":"999••••••••••••••91x",
      "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"
  }
}

Retrieve additional pages

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.

{
  "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"
  }
}

Import four records into an external app using a virtual import

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.

[
  {
    "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
    }
  }
]

POST /v1/connections/:_id/import – Execute a virtual import

Execute a virtual import using a connection identified by _id by posting the import model to this endpoint.

Method

POST

Relative URI

/v1/connections/:_id/import

Request body structure

 
{
  "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
    }
  ]
}

POST /v1/connections/:_id/import/map – Evaluate only the mapping step in a virtual import

Evaluate only the mapping step in a virtual import and return the set of post-mapped records.

Method

POST

Relative URI

/v1/connections/:_id/import/map

Request body structure

 
{
  "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
    }
  ]
}

GET /v1/connections/:_id/audit – Get a connection's logs

Get a log for a specific connection.

Method

GET

Relative URI

/v1/connections/:_id/audit

Response body structure

 
[
  {
    "_id": "554•••••00d",
    "resourceType": "connection",
    "_resourceId": "67e••••••••••3cb",
    "source": "ui",
    "fieldChanges": [],
    "event": "create",
    "time": "2025-03-28T15:22:51.518Z",
    "byUser": {
      "_id": "60c••••••••••6f6",
      "email": "email@email.com",
      "name": "Your Name"
    }
  }
]

GET /v1/connections/:_id/oauth2 – Create an OAuth 2.0 connection in Celigo via a third-party portal

Create an OAuth 2.0 connection in Celigo via a third-party portal.

Method

GET

Relative URI

/v1/connections/:_id/oauth2

GET /v1/connections/:_id/dependencies – Get all resources using or used by this connection

Get all resources using or used by this connection.

Method

GET

Relative URI

/v1/connections/:_id/dependencies

Response body structure

 
{
  "exports": [
    {
      "id": "65c•••••••••••440",
      "name": "NASA API Export",
      "paths": [
        "_connectionId"
      ],
      "accessLevel": "manage",
      "dependencyIds": {
        "connection": [
          "65c•••••••••••c8c"
        ]
      }
    }
  ],
  "flows": [
    {
      "id": "65c••••••••••••••25c",
      "name": "NASA APOD - Slack",
      "paths": [
        "pageGenerators[*]._exportId"
      ],
      "accessLevel": "manage",
      "dependencyIds": {
        "export": [
          "65c•••••••••••••440"
        ]
      }
    }
  ],
  "integrations": [
    {
      "id": "65c•••••••••••••••••c06",
      "name": "NASA Astronomy Picture of the Day to Slack",
      "paths": [
        "_registeredConnectionIds[*]"
      ],
      "accessLevel": "manage",
      "dependencyIds": {
        "connection": [
          "65c••••••••••••••c8c"
        ],
        "flow": [
          "65c••••••••••••••25c"
        ]
      }
    }
  ]
}