Cloud Elements API Version 2.0 Documentation

Cloud Elements is proud to announce our next version of APIs

Our Version 2 APIs are now available for our CRM, Documents, Help Desk, Marketing and Messaging Hubs, as well as our Usage tools. Over the past year, hundreds of companies have been building on our V1 RESTlike APIs. In V2, we updated our core application to better support REST best practices. Conversion to RESTful architecture gives us more consistency across our API and is a well known pattern for API clients. If you are currently using Version 1, don’t worry, we will be continuing to support Version 1, and you won’t have to change any of your current integrations.

Some key features of our V2 APIs:

  • Easier for developers to integrate our framework with automated tools that consume RESTful APIs.

  • Transparently see what a request is suppose to do by looking at only the request URL (which represents the resource being manipulated) and the HTTP verb (which represents the operation being done to the resource).

  • Improved and normalized error handling.

  • Simplified provisioning process that resembles a typical OAuth 2.0 workflow.

  • Potential to support hypermedia controls and self-describing actions.

Fewer Verbs, More RESTful

The verbs describing the operation have changed from method name to HTTP verbs. For example, to provision a Documents Hub instance, the method call went from POST /provisioning/createInstance  to POST /instances.

When using the Documents Hub  in V2, there is an explicit separation between file and folder operations. Our new URL structure will intuitively enumerate the resources in the Documents Hub. For example, the form of a request URL is /{apiVersion}/hubs/{hubName}/{resource}.

Request URL = {apiVersion} + hubs + {hubName} + {resource}

For more details, check out our interactive documentation here.

Coming Soon!

Version 2 Transformations are coming soon, so please continue to use Version 1. V1 and V2 Transformation APIs will work together.

On our Developer Blog

Look for updates on API V2 on our Developer Blog.

Developer Portal

For more information about using Cloud Elements’ current APIs, check out our Developer Portal.

Hub API Documentation:

Coming Soon!

Platform Level Documentation:

Discover more of our functionality with Cloud Elements Platform APIs.  Download our Usage Guides to see example of all our Platform level API calls, as well as, example responses.  These APIs can be used across all of the Cloud Elements Hubs.  Leverage the power of our Platform APIs in your workflow and get the most out of Cloud Elements Service.

AccountsElementsHubsInstances and Usage

Two main changes happening in the V2 release:

  • We no longer use the Provisioning Hub APIs, and instead use Hubs, Elements and Instance APIs
  • Manipulation of files and folders can now be used via the Documents Hub APIs

OAuth workflow changes from V1 to V2 – High level

New OAuth workflow that mimics the standard OAuth authorization grant workflow:

  1. GET /elements/{elementKey}/oauth  retrieves the URL to request in order to retrieve the authorization code
  2. POST /instances  implicitly handles the the final portion of the OAuth handshake, taking the authorization code and trading it in for the access token behind the scenes
  3. /api-v1/provisioning/createInstance  -> POST /api-v2/instances
  4. /api-v1/provisioning/getOAuthUrl  -> GET /api-v2/elements/{elementKey}/oauth


Documents Hub changes from V1 to V2 – High level

Hub now supports explicit operations by path and provider specific id:

  1. Path based arguments are supplied as URL params (ie. /{requestUrl}?path=/pathToMyFileOrFolder )
  2. Id arguments are treated as resources of a particular file or folder (ie. /{requestUrlForFile}/{providerSpecificFileId} )
  3. /api-v1/document/get  -> GET /api-v2/hubs/documents/files or api-v2/hubs/documents/folders
  4. /api-v1/document/list  -> GET /api-v2/hubs/documents/folders/{folderId}/contents
  5. /api-v1/document/search  -> GET /api-v2/hubs/documents/search
  6. /api-v1/document/delete  -> DELETE /api-v2/hubs/documents/<files | folders>
  7. /api-v1/document/createFolder  -> POST /api-v2/hubs/documents/folders
  8. /api-v1/document/uploadFile  -> POST /api-v2/hubs/documents/files
  9. Consolidated GetAccessUrls and GetDownloadLinks APIs into “links” API (ie. GET /api-v2/hubs/documents/files/{fileId}/links )
  10. Consolidated V1 Move, Rename APIs into PATCH /api-v2/hubs/documents/{files | folders}

Cloud Elements Version 2.0 APIs