The integrator.io API is RESTful, performs requests in JSON formatting, and is secured by bearer tokens. You'll need to Create an API token to authenticate your requests.
Table of contents
Create API tokens
The integrator.io API uses API keys to authenticate requests. Only an account owner or administrator can create and view an API token. You can view and manage your API keys at Resources → API tokens. Be sure to keep your API keys secure at all times since they carry many privileges.
Every integrator.io account is provisioned with one API token. API clients should transmit this token using the Authorization
request header field and the Bearer
authentication scheme.
Sample HTTP request
GET /v1/tokenInfo HTTP/1.1 Host: api.integrator.io Authorization: Bearer my_api_token
Sample response
HTTP/1.1 200 OK Content-Type: application/json; charset=utf-8 { "_userId": "5e03061cda20740022300f09", "scope":"*" }
Generate additional tokens common to your account or specific to an Integration App:
- Common to your entire integrator.io account – Open API tokens from the Resources menu. Click + Create API token at the top right.
–– or –– - Specific to an Integration App – In the Integration App’s dashboard, open the Admin tab, click the API tokens setting. Click + Create API token at the top right.
Settings
Your settings are identical for API keys configured for your entire account or for an Integration App.

Provide a meaningful Name and Description to identify your API key.
Auto purge token (required): Select the time after which the token should be automatically purged from the system.
Note: If you cannot generate long-lived API tokens (tokens with expiration limits beyond one hour), you must add an API Management license to your account. This license allows you to create valid tokens for longer than one hour. API Management is included in Enterprise plans and is available for purchase in Standard, Professional, and Premium plans.
You can use scopes to restrict your API token's access, which will help keep your account secure.
Scope (Set the access permissions for your token, required):
- Full access – tokens provisioned at the account level have unrestricted permissions to your integrator.io account. No further scopes need to be selected.
–– or –– - Custom – tokens can be created with permissions to specific resources in your integrator.io account, and they can only be used to invoke very specific integrator.io APIs. You can select multiple scopes and multiple options within each scope.
- Connections: Select the connections that this token will be able to access.
- Exports: Select the exports that this token will be able to access.
- Imports: Select the imports that this token will be able to access.
- My APIs: Select the My APIs that this token can access.
Click Save or Save & close to save your new token.
The base URL depends on your account location:
- North America:
https://api.integrator.io/v1/
- European Union:
https://api.eu.integrator.io/v1/
You can use a variety of endpoints to manage integrator.io, including your connections, integrations, and jobs.
API endpoints
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.
Integration app fields
Field | Description |
mode |
The integrator.io user interface uses this as a read-only field. Valid values are:
|
settings | This field stores the settings (i.e. the configuration) for the integration app integration. For example, when a user opens the settings page for an integration app integration running in their account, and they change a setting, this field is updated and propagates to the integration app's backend to adjust the integration accordingly. |
version | This field stores the version of an integration running in the user's integrator.io account. Always increment the version field as a final step whenever you push any managed updates to a user's integrator.io account. |
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 complete. While updateInProgress is true, the user can't change any settings or mappings in their integration. |
install | Use this array field to specify all of the steps that are needed to install the integration app integration in a user's integrator.io account. You can also use this to track the state of each step so that the integrator.io UI knows which steps are complete and which steps the user should perform next. |
Integration app examples
GET /v1/integrations/554155c853bb53af2900000b HTTP/1.1
Host: api.integrator.io
Authorization: Bearer my_api_token
Sample Response:
{ "_id":"554155c853bb53af2900000b", "lastModified":"2017-08-07T18:34:07.786Z", "name":"Licensing and Usage", "readme":"This integration is mission critical and keeps the licensing data..." }
Notice all the extra fields related to integration apps.
GET /v1/integrations/57974ed227a82a3475cecb15 HTTP/1.1
Host: api.integrator.io
Authorization: Bearer my_api_token
Sample Response:
{ "_id":"57974ed227a82a3475cecb15", "lastModified":"2017-09-15T10:55:15.675Z", "name":"BigCommerce - NetSuite Connector", "_connectorId":"57179182e0a908200c2781d9", "install":[ { "name":"NetSuite Connection", "description":"Configure NetSuite account credentials", "imageURL":"/images/company-logos/netsuite.png", "completed":false, "installerFunction":"verifyNetSuiteConnection", "uninstallerFunction":"deleteNetSuiteConnection", "_connectionId":"57974ed21d2e4ab87ae46d99" }, { "name":"BigCommerce Connection", "description":"Configure BigCommerce store credentials", "imageURL":"/images/company-logos/BigCommerce.png", "completed":false, "installerFunction":"verifyBigCommerceConnection", "uninstallerFunction":"deleteBigCommerceConnection", "_connectionId":"57974ed227a82a3475cecb17" }, { "name":"Integrator Bundle", "description":"Install Integrator Bundle in NetSuite", "imageURL":"/images/company-logos/netsuite.png", "installURL":"", "completed":false, "installerFunction":"verifyIntegratorBundleInstallation", "uninstallerFunction":"uninstallVerifyIntegratorBundle" }, { "name":"BigCommerce Bundle", "description":"Install BigCommerce Bundle in NetSuite", "imageURL":"/images/company-logos/netsuite.png", "installURL":"", "completed":false, "installerFunction":"verifyBigCommerceBundleInstallation", "uninstallerFunction":"uninstallVerifyBigCommerceBundle" } ], "mode":"install", "settings":{ "sections":[ { "temp":"remove_me" } ], "commonresources":{ "genericExportApiIdentifier":"e7654358b7", "bigcommerceConnectionId":"57974ed227a82a3475cec222", "netsuiteConnectionId":"57464ed11d2e4ab87ae46d99" } }, "version":"1.0.1" }
Comments
10 comments
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
Could you please add an example of an Export Clone? I'm getting the response:
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
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.
Don Conrad That's correct. If you could share, what scenarios/tasks are you planning to automate with these error APIs?
Thanks
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.
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).
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.
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.
Hello, Is there detailed documentation available for the required body fields for PUT and POST requests for each of the endpoints? That would be really helpful. I tried the connection PUT request but I am getting the following 422 error
Please sign in to leave a comment.