The docs are moving!

Find us at our new Help Center where we've combined our documentation and knowledgebase articles in one easy-to-search location.

We aren't updating the Developer Portal anymore, except for the Element Docs — all updates happen in the Help Center. We're retiring the Developer Portal as you know it in:

Instance APIs

The Instances APIs allow you to access your account’s element instances that have been provisioned. Access includes creating, retrieving, updating, and deleting instances.

In order to access the Instances APIs, you must sign up for Cloud Elements Service. You will need your Organization and User Secrets to make success Usage API calls. These are generated for you when you sign up for our service. Details on how to sign up and where to find your Organization and User Secrets are documented in the next section.

How to Use the Instance APIs

Below are example cURL commands and examples of successful responses for the Instances API calls. NOTE, not all supported calls are displayed - this is just a sample.

POST /instances

Create a new element instance.

Below is an example cURL command demonstrating the POST /instances API call and successful response. The create-instance.json file is needed for successful instance creation. This file will be places after the -d @ in the cURL command. The create-instance.json file is example data that was created for this demonstration. Please make sure your quotes are straight in the cURL command.

curl -X POST
-H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>'
-H 'Content-Type: application/json'
-d @create-instance.json
'https://api.cloud-elements.com/elements/api-v2/instances'

Example JSON file – create-instance.json:

{
  "element": {
    "key": "dropbox"
  },
  "providerData": {
    "code": "Code on the Return URL"
  },
  "configuration": {
    "oauth.callback.url": "https://www.cloud-elements.com",
    "oauth.api.key": "za6jhr3hychnef0",
    "oauth.api.secret": "eghxt92pr5xjkuv",
    "document.tagging": false
  },
  "tags": [
    "my_first_tag"
  ],
  "name": "my_first_instance"
}
Successful Example Response:

{
  "id": 27,
  "name": "my_first_instance",
  "token": "BUIWhN8NTPaeyYo7Kblo91CJ1tCG6PUonwnV/XJjy2A=",
  "element": {
    "id": 14,
    "name": "Dropbox",
    "key": "dropbox",
    "description": "One place for all your stuff, wherever you are. Dropbox is a free service that lets you bring your photos, docs, and videos anywhere and share them easily. Anything you add to Dropbox will automatically show up on all your computers, phones and even the Dropbox website.",
    "active": true,
    "deleted": false,
    "typeOauth": true,
    "trialAccount": false,
    "existingAccountDescription": "Give your application access to your existing <br> Dropbox account</br><span class="buttonDescription">Enter your credentials and details for your <b>Dropbox Account</b></span>",
    "configDescription": "If you do not have an Dropbox account, you can create one at <a href="http://www.dropbox.com" target="_blank">Dropbox Signup</a>",
    "signupURL": "http://www.dropbox.com",
    "elementProvisionType": "OAUTH_TEMPLATE"
  },
  "tags": [
    {
      "id": 12,
      "name": "my_first_tag"
    }
  ],
  "provisionInteractions": [],
  "valid": true,
  "disabled": false
}

Note: Make sure you have straight quotes in your JSON files and cURL commands. Please use plain text formatting in your code.

Instance Configuration

The content in the configuration section or nested object in the body posted to the POST /instances or PUT /instances/{id} APIs varies depending on which element is being instantiated. However, some configuration properties are common to all elements and available to be configured for all elements. These properties are -

event.notification.enabled: This property is a boolean property, and determines if event reception (via webhook or polling) is enabled for the element instance. This property defaults to false.
event.vendor.type: When event.notification.enabled property is set to true, this property determines the mechanism for Cloud Elements to use to receive or fetch changed events from the service endpoint. The supported values are webhook and polling. Most elements support one mechanism or the other, but some elements, e.g., Salesforce.com support both mechanisms. This property is optional.
event.notification.type: This property can be used to determine how an event notification should be sent to the consumer of the element instance, in most cases your application. Currently, webhook is the only supported value for this property. This means that when an event is received by the element instance, it will get forwarded to the provided event.notification.callback.url via a webhook to you. This property is optional.
event.notification.callback.url: As mentioned above, the value of this property is an http or https URL to which Cloud Element will post the event for consumption by your application. This property is optional.
filter.response.nulls: This property defaults to true, i.e., it's boolean property, and determines if null values in the response JSON should or should not be filtered from the response returned to the consuming application. By default, all null values are filtered from the response before sending the response to the consuming application.

GET /instances

Retrieve all of your account’s element instances.

Below is an example cURL command demonstrating the GET /instances API call and successful response. Please make sure your quotes are straight in the cURL command.

curl -X GET
-H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>'
'https://api.cloud-elements.com/elements/api-v2/instances'

Example of Successful Response – example has been truncated.

[
    {
        "id": 4014,
        "name": "QA Box",
        "token": "abcU3kXt5Na7EPiabc6wPagnskTsZUJrY4gTQCjt7efa=",
        "element": {
            "id": 22,
            "name": "Box",
            "key": "box",
            "description": "Box offers secure, scalable, content-sharing that both users and IT love and adopt. Box is a simple and affordable solution to manage documents, media and all your content online. Share files as a link. Sync files on the desktop. It's file sharing, reinvented.",
            "image": "elements/provider_box.png",
            "active": true,
            "deleted": false,
            "typeOauth": true,
            "trialAccount": false,
            "existingAccountDescription": "Give your application access to your existing <br> Box account</br><span class="buttonDescription">Enter your credentials and details for your <b>Box Account</b></span>",
            "configDescription": "If you do not have an Box.net account, you can create one at <a href="http://www.box.com" target="_blank">Box.Net Signup</a>",
            "elementProvisionType": "OAUTH_TEMPLATE"
        },
        "tags": [
            "QA",
            "QA Box",
            "Starter"
        ],
        "valid": true,
        "maxCacheSize": 0,
        "cacheTimeToLive": 0,
        "cachingEnabled": false
    },
    {
        "id": 2535,
        "name": “QA SFDC Service Cloud",
        "token": "e298ab9bf609f98e750fab49efcd18508",
        "element": {
            "id": 29,
            "name": "Salesforce.com Service Cloud",
            "key": "sfdcservicecloud",
            "description": "Salesforce.com Service Cloud allows you to deliver revolutionary customer service from anywhere, anytime, on any device.",
            "image": "elements/provider_sfdc.png",
            "active": true,
            "deleted": false,
            "typeOauth": true,
            "trialAccount": false,
            "configDescription": "If you do not have a Salesforce.com account, you can create one at <a href="http://www.salesforce.com" target="_blank">Salesforce.com Signup</a>"
        },
        "tags": [
           "QA"
        ],
        "valid": true,
        "maxCacheSize": 0,
        "cacheTimeToLive": 0,
        "cachingEnabled": false
    }
]

PUT /instances/{id}

Update an already existing element instance.

Below is an example cURL command demonstrating the PUT /instances/{id} API call and successful response. The update-instance.json file is needed to successfully update an instance. This file will be places after the -d @ in the cURL command.The ID will need to be placed at the end of the URL in the cURL command. For our example, the ID used is 4590. Please make sure your quotes are straight in the cURL command.

curl -X PUT
-H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>'
-H 'Content-Type: application/json'
-d @sfdc-update-instance.json
'https://api.cloud-elements.com/elements/api-v2/instances/4590'

update-instance.json: – JSON file needed to update instance

{
    "name": "SFDC Updated Instance",
    "tags": [
        "sandbox",
        "08/21/2014",
        "new-tag"
    ]
}
Example of Successful Response:

{
    "id": 4590,
    "name": "SFDC Updated Instance",
    "token": "bl+pVH4pVl1yciJZ8IpPVfb5gT2ZmQGdyHbjlSKF7ee=",
    "element": {
        "id": 23,
        "name": "Salesforce.com",
        "key": "sfdc",
        "description": "Customer relationship management, simplified. with the Salesforce.com Element, integrate a leading customer management service into your application in a fraction of the time, with a fraction of the code. Your campaigns, projects, CRM, payments and documents are all in one place, all integrated seamlessly into your app.",
        "image": "elements/provider_sfdc.png",
        "active": true,
        "deleted": false,
        "typeOauth": false,
        "trialAccount": false,
        "existingAccountDescription": "Use your Salesforce.com Account <br /><span class="buttonDescription">Enter your credentials and details for your <b>Salesforce.com Account</b>.</span>",
        "configDescription": "If you do not have a Salesforce.com account, you can create one at <a href="http://www.salesforce.com" target="_blank">Salesforce.com Signup</a>",
        "signupURL": "http://www.salesforce.com"
    },
    "provisionInteractions": [],
    "valid": true,
    "disabled": false,
    "maxCacheSize": 0,
    "cacheTimeToLive": 0,
    "cachingEnabled": false
}

DELETE /instances/{id}

Delete an element instance.

Below is an example cURL command demonstrating the DELETE /instances/{id} API call and successful response. The ID will need to be placed at the end of the URL in the cURL command. For our example, the ID used is 4590. Please make sure your quotes are straight in the cURL command.

curl -X DELETE
-H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>'
'https://api.cloud-elements.com/elements/api-v2/instances/4590'

Example of Successful Response:

HTTP 200 on success

GET /instances/{id}

Retrieve a specific element instance.

Below is an example cURL command demonstrating the GET /instances/{id} API call and successful response. The ID will need to be placed at the end of the URL in the cURL command. For our example, the ID used is 4014. Please make sure your quotes are straight in the cURL command.

curl -X GET
-H 'Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_ORGANIZATION_SECRET>'
'https://api.cloud-elements.com/elements/api-v2/instances/4014'

Example of Successful Response:

{
    "id": 4014,
    "name": "QA Box",
    "token": "abcU3kXt5Na7EPiabc6wPagnskTsZUJrY4gTQCjt7efa=",
    "element": {
        "id": 22,
        "name": "Box",
        "key": "box",
        "description": "Box offers secure, scalable, content-sharing that both users and IT love and adopt. Box is a simple and affordable solution to manage documents, media and all your content online. Share files as a link. Sync files on the desktop. It's file sharing, reinvented.",
        "image": "elements/provider_box.png",
        "active": true,
        "deleted": false,
        "typeOauth": true,
        "trialAccount": false,
        "existingAccountDescription": "Give your application access to your existing <br> Box account</br><span class="buttonDescription">Enter your credentials and details for your <b>Box Account</b></span>",
        "configDescription": "If you do not have an Box.net account, you can create one at <a href="http://www.box.com" target="_blank">Box.Net Signup</a>",
        "elementProvisionType": "OAUTH_TEMPLATE"
    },
    "tags": [
        "QA Box",
        "QA",
        "Starter"
    ],
    "provisionInteractions": [],
    "valid": false,
    "disabled": false,
    "maxCacheSize": 0,
    "cacheTimeToLive": 0,
    "cachingEnabled": false
}

PATCH /instances/{id}

Update an already existing element instance.

One common use of PATCH is to update the tags associated with an element instance. Updating tags removes any existing tags, so if you want to keep existing tags and add to them, include all of your tags in the JSON body.

To update tags:

Construct a JSON body that includes the element instance ID and tags.

{
  "id": 764,
  "tags": [
    "tag1",
    "tag2",
    "tag3"
  ]
}

Include the JSON in the body of the following API call, replacing {id} with the same element instance ID that you included in the JSON body:
```
PATCH /instances/{id}
```

If you need any support integrating our APIs, please let us know. You can email or give us a call at +1.866.830.3456. We will do our best to get back to you within 24 hours. Your success is our success.