Sending Data To Cleo Integration Cloud Via REST API

Cleo Integration Cloud (CIC) offers various methods and data transmission protocols for transferring data. (https://support.cleo.com/hc/en-us/sections/360008272154-Endpoint-Types)

API based integration is becoming more and more desirable as a method to meet business automation needs and so I’ll describe how to achieve this using practical examples below.

Upload Overview

Before we jump into the API details, let’s start with the manual process that we’re trying to automate.

CIC provides a “partner mailbox” (https://support.cleo.com/hc/en-us/articles/360038528394-Partner-Mailbox-Endpoint) which allows you to create a login account to the Cleo Portal, a web based interface for transferring files.

Using this partner mailbox, a user can point their web browser to the Cleo Portal, log in, navigate to the “upload” folder, upload a file and then that file will then be processed and routed by CIC.

This manual flow can be described this way:

• Log in
• Navigate to the “upload” folder
• Upload the data

The above is the flow that needs to be implemented via REST API.

Setup

To keep this example simple, the partner mailbox has been set up to allow access to the Cleo Portal using a basic username and password. For the example, I’ll use a username of claudioapp and a password of Cl@udio_@pp_P@ssword.

I’ll be using cURL (https://en.wikipedia.org/wiki/CURL), a common command line tool, for my examples.

Log In

Our first step is to log in. In API terms, this means authenticating, using the supplied username and password, and retrieving the API Bearer Token, which is needed to make subsequent API calls.

To get logged in and retrieve your Bearer Token, perform the following API request:

• URI:
  • https://YOURTENANT.cleointegration.com/api/authentication
• Method/Action:
  • POST
• Headers:
  • None
• Data:
  • grant_type=password&username=USERNAME&password=PASSWORD

Replace these items above with the correct values:

• YOURTENANT should be replaced with the URL component shown in the Cleo Portal setting of the Partner Mailbox in CIC.
  • For example: mycompany
• USERNAME should be replaced with the Partner Mailbox username for the Cleo Portal.
  • For example: claudioapp
• PASSWORD should be replaced with the Partner Mailbox password for the Cleo Portal.
  • For example: Cl@udio_@pp_P@ssword

cURL Example:

curl -X POST -d 'grant_type=password&username=claudioapp&password=Cl@udio_@pp_P@ssword' https://mycompany.cleointegration.com/api/authentication

You’ll receive back some JSON formatted text, including the Bearer Token (returned as “access_token”), like this:

{

  "token_type": "bearer",

  "access_token": "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3Yzc1NzAyYi03MWY2LTQ4NDAtYTI5OC01NDAyMTQ2Mzk4MTQiLCJjeWNsZUlkIjoiQSIsImlzcyI6Imh0dHA6XC9cL3d3dy5jbGVvLmNvbSIsIm9tbmlJZCI6IjdjNzU3MDJiLTcxZjYtNDg0MC1hMjk4LTU0MDIxNDYzOTgxNCIsImV4cCI6MTYxNzEyNzI1OCwiaWF0IjoxNjE3MTIzNjU4LCJBY2Nlc3NUeXBlIjoiREVGQVVMVCJ9.IX3FCmWhlhpQlZPAYRm_-Xv_Qxef7N4nQLrubjF77u4",

  "user_id": "7c75702b-71f6-4840-a298-540214639814"

}

Save the value of the “access_token” for use in the subsequent API calls.

Navigate To The Upload Folder

When using APIs, items such as folders are typically identified by their unique ID rather than their human readable name. This means that we need to determine this unique ID of the “upload” folder in order to be able to target it for the data upload.

This is a two step process:

1. Determine the ID of the “root” (or “home”) folder.
2. Determine the “children” folder IDs contained in the above “root folder” and find the one that is named “upload”.

To determine the “root” folder ID, perform the following API request:

• URI:
  • https://YOURTENANT.cleointegration.com/api/folders
• Method/Action:
  • GET
• Headers:
  • Authorization: Bearer BEARERTOKEN
• Data:
  • None

Replace these items above with the correct values:

• YOURTENANT should be replaced with the URL component shown in the Cleo Portal setting of the Partner Mailbox in CIC.
  • For example: mycompany
• BEARERTOKEN should be replaced with the value of the “access_token” retrieved above.
  • For example: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3Yzc1NzAyYi03MWY2LTQ4NDAtYTI5OC01NDAyMTQ2Mzk4MTQiLCJjeWNsZUlkIjoiQSIsImlzcyI6Imh0dHA6XC9cL3d3dy5jbGVvLmNvbSIsIm9tbmlJZCI6IjdjNzU3MDJiLTcxZjYtNDg0MC1hMjk4LTU0MDIxNDYzOTgxNCIsImV4cCI6MTYxNzEyNzI1OCwiaWF0IjoxNjE3MTIzNjU4LCJBY2Nlc3NUeXBlIjoiREVGQVVMVCJ9.IX3FCmWhlhpQlZPAYRm_-Xv_Qxef7N4nQLrubjF77u4

cURL Example:

curl -X GET -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3Yzc1NzAyYi03MWY2LTQ4NDAtYTI5OC01NDAyMTQ2Mzk4MTQiLCJjeWNsZUlkIjoiQSIsImlzcyI6Imh0dHA6XC9cL3d3dy5jbGVvLmNvbSIsIm9tbmlJZCI6IjdjNzU3MDJiLTcxZjYtNDg0MC1hMjk4LTU0MDIxNDYzOTgxNCIsImV4cCI6MTYxNzEyNzI1OCwiaWF0IjoxNjE3MTIzNjU4LCJBY2Nlc3NUeXBlIjoiREVGQVVMVCJ9.IX3FCmWhlhpQlZPAYRm_-Xv_Qxef7N4nQLrubjF77u4' https://mycompany.cleointegration.com/api/folders

You’ll receive back some JSON formatted text, including the “root” folder ID (returned as “resources[].id”), like this:

{

  "totalResults": 1,

  "startIndex": 0,

  "count": 1,

  "resources": [

    {

      "type": "folder",

      "space": "home",

      "id": "MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTAyMjNiNGVkNmZjMTliOTAyNzU0ZjE4OGIwNzdjY2JlZg",

      "name": "claudioapp",

      "permissions": [],

      "systemProtected": {

        "delete": false,

        "rename": false

      },

      "_links": {

        "self": {

          "href": "/api/folders/MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTAyMjNiNGVkNmZjMTliOTAyNzU0ZjE4OGIwNzdjY2JlZg"

        }

      },

      "meta": {

        "lastModified": "2021-03-30T04:16:12.000Z"

      }

    }

  ]

}

Now that we have the “root” folder ID, we can make another API call to find the child folders and determine the ID of the child folder named “upload”.

To retrieve information about the child folders, perform the following API request:

• URI:
  • https://YOURTENANT.cleointegration.com/api/folders/ROOTFOLDERID/children
• Method/Action:
  • GET
• Headers:
  • Authorization: Bearer BEARERTOKEN
• Data:
  • None

Replace these items above with the correct values:

• YOURTENANT should be replaced with the URL component shown in the Cleo Portal setting of the Partner Mailbox in CIC.
  • For example: mycompany
• BEARERTOKEN should be replaced with the value of the “access_token” retrieved above.
  • For example: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3Yzc1NzAyYi03MWY2LTQ4NDAtYTI5OC01NDAyMTQ2Mzk4MTQiLCJjeWNsZUlkIjoiQSIsImlzcyI6Imh0dHA6XC9cL3d3dy5jbGVvLmNvbSIsIm9tbmlJZCI6IjdjNzU3MDJiLTcxZjYtNDg0MC1hMjk4LTU0MDIxNDYzOTgxNCIsImV4cCI6MTYxNzEyNzI1OCwiaWF0IjoxNjE3MTIzNjU4LCJBY2Nlc3NUeXBlIjoiREVGQVVMVCJ9.IX3FCmWhlhpQlZPAYRm_-Xv_Qxef7N4nQLrubjF77u4
• ROOTFOLDERID should be replaced with the value of “resources[].id” retrieved above.
  • For example: MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTAyMjNiNGVkNmZjMTliOTAyNzU0ZjE4OGIwNzdjY2JlZg

cURL Example:

curl -X GET -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3Yzc1NzAyYi03MWY2LTQ4NDAtYTI5OC01NDAyMTQ2Mzk4MTQiLCJjeWNsZUlkIjoiQSIsImlzcyI6Imh0dHA6XC9cL3d3dy5jbGVvLmNvbSIsIm9tbmlJZCI6IjdjNzU3MDJiLTcxZjYtNDg0MC1hMjk4LTU0MDIxNDYzOTgxNCIsImV4cCI6MTYxNzEyNzI1OCwiaWF0IjoxNjE3MTIzNjU4LCJBY2Nlc3NUeXBlIjoiREVGQVVMVCJ9.IX3FCmWhlhpQlZPAYRm_-Xv_Qxef7N4nQLrubjF77u4' https://mycompany.cleointegration.com/api/folders/ MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTAyMjNiNGVkNmZjMTliOTAyNzU0ZjE4OGIwNzdjY2JlZg/children

You’ll receive back some JSON formatted text, including the children folder names (returned as “resources[].name”) and the children folder IDs (returned as “resources[].id”) like this:

{

  "totalResults": 2,

  "startIndex": 0,

  "count": 2,

  "resources": [

    {

      "type": "folder",

      "space": "home",

      "subspace": "download",

      "id": "MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTA5YjU0YjdkMTM5NGQxNzg1MTM5ODM0NWM5Y2M1NzZkZg",

      "name": "download",

      "permissions": [

        "download"

      ],

      "systemProtected": {

        "delete": true,

        "rename": true

      },

      "_links": {

        "self": {

          "href": "/api/folders/MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTA5YjU0YjdkMTM5NGQxNzg1MTM5ODM0NWM5Y2M1NzZkZg"

        }

      },

      "meta": {

        "lastModified": "2021-03-30T18:13:34.365Z"

      }

    },

    {

      "type": "folder",

      "space": "home",

      "subspace": "upload",

      "id": "MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTA2ZmNmZWQ3NGM2ZTcxNjY1NWMzMjgzNzZhMDEyMjRhZg",

      "name": "upload",

      "permissions": [

        "upload"

      ],

      "systemProtected": {

        "delete": true,

        "rename": true

      },

      "_links": {

        "self": {

          "href": "/api/folders/MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTA2ZmNmZWQ3NGM2ZTcxNjY1NWMzMjgzNzZhMDEyMjRhZg"

        }

      },

      "meta": {

        "lastModified": "2021-03-30T18:13:34.369Z"

      }

    }

  ]

}

Now that we have determined the ID of the child folder named “upload”, we can finally make the API call to upload data into CIC.

Upload The Data

To upload the data, we need to target the “upload” folder, using the ID captured above, and send the data payload.

Any type of data can be transmitted but, for this example, I’ll use some dummy JSON text representing an EDI message.

To upload payload data, perform the following API request:

• URI:
  • https://YOURTENANT.cleointegration.com/api/folders/UPLOADFOLDERID/files
• Method/Action:
  • POST
• Headers:
  • Authorization: Bearer BEARERTOKEN
  • Content-Disposition: attachment;filename=FILENAME
  • Content-Type: application/octet-stream
• Data:
  • RAWPAYLOAD

Replace these items above with the correct values:

• YOURTENANT should be replaced with the URL component shown in the Cleo Portal setting of the Partner Mailbox in CIC.
  • For example: mycompany
• BEARERTOKEN should be replaced with the value of the “access_token” retrieved above.
  • For example: eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3Yzc1NzAyYi03MWY2LTQ4NDAtYTI5OC01NDAyMTQ2Mzk4MTQiLCJjeWNsZUlkIjoiQSIsImlzcyI6Imh0dHA6XC9cL3d3dy5jbGVvLmNvbSIsIm9tbmlJZCI6IjdjNzU3MDJiLTcxZjYtNDg0MC1hMjk4LTU0MDIxNDYzOTgxNCIsImV4cCI6MTYxNzEyNzI1OCwiaWF0IjoxNjE3MTIzNjU4LCJBY2Nlc3NUeXBlIjoiREVGQVVMVCJ9.IX3FCmWhlhpQlZPAYRm_-Xv_Qxef7N4nQLrubjF77u4
• UPLOADFOLDERID should be replaced with the value of the “resources[].id” retrieved above that matches the “upload” folder.
  • For example: MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTA2ZmNmZWQ3NGM2ZTcxNjY1NWMzMjgzNzZhMDEyMjRhZg
• FILENAME should be replaced with a valid file name.
  • For example: purchase_order_850.json
• RAWPAYLOAD should be replaced with the data being transmitted.
  • For example: [ { "type": "850", "value": "$99.99" } ]

cURL Example:

curl -X GET -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI3Yzc1NzAyYi03MWY2LTQ4NDAtYTI5OC01NDAyMTQ2Mzk4MTQiLCJjeWNsZUlkIjoiQSIsImlzcyI6Imh0dHA6XC9cL3d3dy5jbGVvLmNvbSIsIm9tbmlJZCI6IjdjNzU3MDJiLTcxZjYtNDg0MC1hMjk4LTU0MDIxNDYzOTgxNCIsImV4cCI6MTYxNzEyNzI1OCwiaWF0IjoxNjE3MTIzNjU4LCJBY2Nlc3NUeXBlIjoiREVGQVVMVCJ9.IX3FCmWhlhpQlZPAYRm_-Xv_Qxef7N4nQLrubjF77u4' -H "Content-Disposition: attachment;filename=purchase_order_850.json" -H "Content-Type: application/octet-stream" -d'[ { "type": "850", "value": "$99.99" } ]' https://mycompany.cleointegration.com/api/folders/MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTA2ZmNmZWQ3NGM2ZTcxNjY1NWMzMjgzNzZhMDEyMjRhZg/file

A successful upload will return a HTTP Code of 201 and you’ll receive back some JSON formatted text showing details of the successful upload, like this:

{

  "space": "home",

  "subspace": "upload",

  "id": "MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTBhNjBhMTQxZjE0MmY1YjhhYjQwZWMzYzlhMTM5NDA3Nzc3OWRjMzc4ODA4YzIxYTczNzJhMDcwNjhhYmEzMzZh",

  "parentId": "MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTA2ZmNmZWQ3NGM2ZTcxNjY1NWMzMjgzNzZhMDEyMjRhZg",

  "name": "purchase_order_850.json",

  "length": 0,

  "path": [

    {

      "href": "/api/folders/MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTAyMjNiNGVkNmZjMTliOTAyNzU0ZjE4OGIwNzdjY2JlZg",

      "id": "MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTAyMjNiNGVkNmZjMTliOTAyNzU0ZjE4OGIwNzdjY2JlZg",

      "name": "claudioapp "

    },

    {

      "href": "/api/folders/MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTA2ZmNmZWQ3NGM2ZTcxNjY1NWMzMjgzNzZhMDEyMjRhZg",

      "id": "MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTA2ZmNmZWQ3NGM2ZTcxNjY1NWMzMjgzNzZhMDEyMjRhZg",

      "name": "upload"

    }

  ],

  "permissions": [

    "overwrite",

    "delete"

  ],

  "systemProtected": {

    "delete": false,

    "rename": false

  },

  "_links": {

    "self": {

      "href": "/api/files/MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTBhNjBhMTQxZjE0MmY1YjhhYjQwZWMzYzlhMTM5NDA3Nzc3OWRjMzc4ODA4YzIxYTczNzJhMDcwNjhhYmEzMzZh"

    },

    "parent": {

      "href": "/api/folders/MjIyODFjY2Q5ZmUyMmRiZWI1ZjhkZGNkMTliNjNmOTA2ZmNmZWQ3NGM2ZTcxNjY1NWMzMjgzNzZhMDEyMjRhZg"

    }

  },

  "meta": {

    "lastModified": "1970-01-01T00:00:00.000Z"

  }

}

Your data payload has now been delivered to CIC and will be processed and routed.

Conclusion

With a few REST API calls we’re able to automate a manual process and enable tight integration between any API capable system and CIC.

This can speed up the flow of EDI based business processes between systems, regardless of whether those systems are internal to your organization or externally located trading partner systems, and also improve response times of critical B2B business interactions. Any type of EDI message can be delivered via API, allowing you to implement business critical processes, such as Order to Cash, Purchase to Pay, Load Tender to Invoice and many more.

Cleo Integration Cloud allows for seamless integration between API and EDI, allowing you to bridge modern capabilities with well-established legacy business processes.

Watch CIC Demo