Articles in this section

Getting started with standard REST API

The integrator.io API is RESTful, performs requests in JSON formatting, and is secured by bearer tokens.

URL

You can access your integrator.io API data from the browser or the REST client using the URLs below.

North America

Browser

See integrator.io API data in your browser.
https://integrator.io/api/
https://integrator.io/api/exports/a2la•••••••••••w4r

To use this feature, find your resource ID (import, export, connection, etc.) by opening the resource and checking the browser for the ID string. Then, append it to the API URL.

External calls

Access the integrator.io API via the REST client using this URL.
https://api.integrator.io/v1/

EU

Browser

See integrator.io API data in your browser.
https://eu.integrator.io/api/
https://eu.integrator.io/api/exports/a2la•••••••••••w4r

To use this feature, find your resource ID (import, export, connection, etc.) by opening the resource and checking the browser for the ID string. Then, append it to the API URL.

External calls

Access the integrator.io API via the REST client using this URL.
https://api.eu.integrator.io/v1/

Authentication

The integrator.io API uses API tokens to authenticate requests. Only an account owner or administrator can create and view an API token. You can view and manage your API tokens in integrator.io under ResourcesAPI tokens. Be sure to keep your tokens secure at all times since they carry many privileges.

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/v1> OR <api.eu.integrator.io/v1>
Authorization: Bearer my_api_token

Sample response

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
  "_userId": "5e0••••••••••••••09",
  "scope":"*"
}
Was this article helpful?
0 out of 0 found this helpful

Comments

23 comments
Date Votes
  • Would it be possible to add a description of the error fields returned in the new error API? What I'm looking for is what field(s) make an error unique across all integrations and flows.

    These are the fields we get back,
    occurredAt
    source
    code
    message
    oIndex
    retryDataKey
    errorId
    _flowJobId

    There is an errorId field which sounds good but I have a suspicion that may not be unique across all integration flows.

    Thanks

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

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

    The combination of "flowId + stepId + errorId" will be the unique identifier for all errors in an account. You cannot use _flowJobId because it may be blank in a specific error situation.

    Thanks

    0
  • Thanks! Just to clarify stepId is the same as import/export id?

    /flows/<_flowid>/<_importId>/errors
    So the unique key would be _flowid + _importId + errorId right?

    Looking good so far, this is going to help us a lot.

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

    Thanks

    0
  • We use Celigo to import Amazon orders into Netsuite as Sales Orders. We want to switch to invoices which would half our transaction volume. The challenge is invoices error if there isn't enough inventory rather than go on back order like sales orders. Prior to EM2.0 we didn't have a way for our warehousing team to manage those errors.

    Now we can build an interface in Netsuite for the warehouse team to manage the errors. They can stay in the tool they know and we can filter it so they only see the inventory errors they need to address.

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

    1
  • Christoffer Sinnbeck: thanks for the correction, and please forgive our oversight and bias. 

    The requested update will surely help others. I hope you didn't lose too much time figuring out the right URL or bringing it to our attention. 

    0
  • Stephen Brandt: Thanks Stephen, no worries at all. I figured it out after a few minutes of "Unauthorized" messages, and just wanted to add my finding here. Have a great day.

    0
  • 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 

    {
        "errors": [
            {
                "field": "type",
                "code": "missing_required_field"
            }
        ]
    }. Please advise.
     
    Thanks,
    Divya
    0
  • I keep getting errors with my request

     

    example in cURL
    ```
    curl --location 'https://api.integrator.io/v1/tokenInfo' \

    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer TOKEN' \
    --data '{}'
    ```



    response:
    ```

    {
      "errors": [
        {
          "message":"Content-Type should equal application/json"
        }
      ]
    }
    ```

    ideas?
    0
  • Alvin Mites I don't think you need to send a JSON payload (--data '{}') for that endpoint. I also don't think you need to follow redirects (that's what --location does if I am not mistaken). 

    Could you try to put it all into one line, like this:

    curl 'https://api.integrator.io/v1/tokenInfo' --header 'Content-Type: application/json' --header 'Authorization: Bearer XXXXXXX'

    That seems to work for me using a valid token. For some reason I cannot make it return the same error code that you get, not even if I put in a wrong content-type header.

    EDIT: In fact this seems to be enough:

    curl 'https://api.integrator.io/v1/tokenInfo' --header 'Authorization: Bearer XXXXXXXX'

    0
  • I got past that one -- apparently that's a generic error returned if you use the wrong request type for an endpoint

    my goal is to get a "preview" of the data being requested by a given export but I'm struggling to figure out how to do that with the API

    through postman I can hit the endpoint for
    https://integrator.io/api/integrations/:INTEGRATION_IDflows/:FLOW_ID/exports/preview

    is there a way to do that using the API with a bearer token?

    0
  • Alvin Mites If it works in Postman, it should work with curl as well, but maybe I am misunderstanding? I seem to remember that Postman has a function to export a Postman request as a curl command line request?

    EDIT: I guess this depends on whether you intercept cookies from Chrome in Postman, in which case Postman can request URLs that you are logged into in Chrome. Those you cannot successfully request with cURL.

    Am I correct that the URL you try to request has been intercepted from the Celigo UI (i.e. in the Chrome network tab)?

    EDIT 2: Maybe this is what you are looking for: https://docs.celigo.com/hc/en-us/articles/8213191419163-Invoke-an-existing-import-through-the-API

    or https://docs.celigo.com/hc/en-us/articles/4409594232475-Invoke-an-existing-export-through-the-API

    0
  • I could duplicate the calls to the preview endpoint easily enough

    However that is a different type of call and not part of the published API that has an expectation of consistent availability

     

    My question is there a way to use an endpoint like that to get the raw data from an import resource using the API or is that beyond scope?

    edit 1: the example at https://docs.celigo.com/hc/en-us/articles/4409594232475-Invoke-an-existing-export-through-the-APIlooks like it does something similar to what I'm trying to accomplish but I keep getting an error 

    ```
    "exportResponse": "{\"message\":\"API call is not allowed(_apiId).\"}"
    ```

    0
  • Alvin Mites I believe you can use the "Invoke URL" from each export/import to do this. For example, this curl request works for me:

    curl -X POST https://api.integrator.io/XXXXXXXXXX --header 'Authorization: Bearer XXXXXXXXXX'

    where the URL has been taken from the "Advanced" section under the given export or import. Notice that these endpoints must be requested with the POST method (curl defaults to GET).

    Described in more detail here: https://docs.celigo.com/hc/en-us/articles/4409594232475-Invoke-an-existing-export-through-the-API

    0
  • updated question above before I saw your response

    0
  • Alvin Mites What is your exact curl request (of course with the bearer token and ID in URL replaced with XXXX)?

    0
  • Alvin Mites your curl should be this:

    curl --location --request POST 'https://api.integrator.io/v1/exports/62b21440685f60536da17d19/invoke' \
    --header 'Authorization: Bearer XXX'

    Where the ID after /exports/ is your export id.

    0
  • Kathyana Queeman - Is there any support for pagination with these APIs? There is a small reference to needing to use it in the documentation but nothing that I can find to tell me how.

    0
  • Brian Cummings we have actually been working to get these articles updated with paging mechanisms and it should be out later this week or next week. In the mean time, which endpoint are you trying to page? Most of the endpoints, except jobs api and errors api, use a next link header. So if you look at the response header, there will be a link in the header which you can use. If you're using an integrator export to do this, it would be the link header option and then "next" as the override.

     

    If you're using the error list endpoint, it has a next link url returned in the body, so it's setup would be like this:

     

    0
  • Thanks, Tyler Lamparter - I was trying to use Jobs.

    0
  • Brian Cummings so the jobs api doesn't have an official paging mechanism, but it does allow many different parameters to be passed to it. Since we can pass many different datetime parameters, we can come up with our own paging mechanism. Here is how you would set that up:

    /v1/jobs?createdAt_gte={{lastExportDateTime}}

    /v1/jobs?createdAt_lte={{{dateAdd previous_page.last_record.createdAt '-1'}}}&createdAt_gte={{{lastExportDateTime}}}

     

    When you call the jobs api, it gives you 1000 results in descending order. This basically uses that descending order to our advantage by taking the last record in the 1000 results, subtracting 1 milliseconds from the created datetime, then passes that as a parameter value for the next page.

    1

Please sign in to leave a comment.