Elements | Cloud Elements Help Center

Use the Elements resource to interact with elements and their authenticated element instances.

List Element

Retrieve the OpenAPI Schema

GET /elements/{id}/metadata

Retrieve a Specific Element

GET /elements/{keyOrId}/instances

Create an Element Instance

List Element

GET /elements

Retrieve a list of element.

List Element Query Parameters

nextPage	The next page token. Found in the header of the previous search.
pageSize	The page size for the paginated results, defaults to 200. Maximum 200.

List Element Response Fields

The table below shows an abbreviated list of response fields.

id	The element id is a unique numeric identifier for the element, distinct from the element key which is alphanumeric.
name	The display name of the element.
key	The element key is a unique alphanumeric identifier for the element, distinct from the element id which is numeric.
description	A brief description of the element.
image	The branded image associated with the element.
configuration	Object containing the configuration of the element.
transformationsEnabled	Indicates whether resources at the API provider can be mapped to a virtual data resource.
bulkDownloadEnabled/ bulkUploadEnabled	Indicates whether the element supports bulk.
extendable	Indicates whether you can extend the element by adding resources.
authentication	Identifies the type of authentication used.
extended	Identifies whether you have added resources to the element or not.
hub	The hub in which the element is categorized.
private	Indicates whether the element is part of the public element catalog or not.

List Element Example Request

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2/elements \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -H 'Content-Type: application/json' \

List Element Example Response

[
  {
    "id": 3128,
    "name": "Recurly",
    "key": "recurly",
    "description": "Add a Recurly Instance to connect your existing recurly account to the Billing Hub, allowing you to manage customers, invoices, and transactions across multiple elements. You will need your Recurly account to add an instance.",
    "image": "https://cloud.githubusercontent.com/assets/4119349/24875787/7ff95a3a-1de6-11e7-86c4-b844167212c1.png",
    "active": true,
    "deleted": false,
    "typeOauth": false,
    "trialAccount": false,
    "configuration": [],
    "transformationsEnabled": true,
    "bulkDownloadEnabled": true,
    "bulkUploadEnabled": true,
    "cloneable": true,
    "extendable": false,
    "beta": false,
    "authentication": {
      "type": "custom"
    },
    "extended": false,
    "hub": "billing",
    "protocolType": "http",
    "private": false
  }
]

Retrieve the OpenAPI Schema

GET /elements/{id}/docs

Retrieve the OpenAPI version 2 schema for an element by element id. Specify an operationId to return only a specific endpoint.

Retrieve the OpenAPI Schema Path Parameters

id	The element id is a unique numeric identifier for the element, distinct from the element key which is alphanumeric.

Retrieve the OpenAPI Schema Query Parameters

operationId

A unique string used that identifies a specific endpoint. For example, the OpenAPI specification for Salesforce Sales Cloud includes operationIDs like getAccountsActivities, createAccount, updateCampaignById, and many more.

Retrieve the OpenAPI Schema Response Fields

For descriptions see the OpenAPI specification.

Retrieve the OpenAPI Schema Example Request

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2/elements/23/docs?operationId=getAccountsActivities \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -H 'Content-Type: application/json' \

Retrieve the OpenAPI Schema Example Response

The response includes the OpenAPI specification file in the body. The following example is an abbreviated version.


{  
  "basePath":"/elements/api-v2/hubs/crm",
  "paths":{  },
  "host":"console.cloud-elements.com",
  "schemes":[  ],
  "definitions":{  },
  "swagger":"2.0",
  "info":{  },
  "tags":[  ]
}

GET /elements/{id}/metadata

GET /elements/{id}/metadata

Retrieve the metadata of a specific element by element id.

Path Parameters

id	The element id is a unique numeric identifier for the element, distinct from the element key which is alphanumeric.

Response Fields

The table below shows an abbreviated list of response fields.

id	The element id is a unique numeric identifier for the element, distinct from the element key which is alphanumeric.
name	The display name of the element.
key	The element key is a unique alphanumeric identifier for the element, distinct from the element id which is numeric.
description	A brief description of the element.
authenticationType	Identifies the type of authentication used.
events	An object that identifies whether events are supported and, if so, what kind (webhooks or polling).

Example Request

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2/elements/23/metadata \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -H 'Content-Type: application/json' \

Example Response


{
    "id": 23,
    "name": "Salesforce Sales Cloud",
    "key": "sfdc",
    "displayOrder": 100,
    "active": false,
    "beta": false,
    "description": "Add a Salesforce Instance to connect your existing Salesforce account to the CRM Hub, allowing you to manage contacts, leads, accounts, opportunities etc. across multiple CRM elements or your other Salesforce services. You will need your Salesforce account information to add an instance.",
    "transformations": false,
    "churros": false,
    "normalizedPaging": false,
    "swaggerValidated": false,
    "cloneable": false,
    "authenticationType": "custom",
    "events": {
        "supported": true,
        "methods": [
            "polling"
        ]
    },
    "resources": []
}

Retrieve a Specific Element

GET /elements/{keyOrId}

Retrieve a specific element by element id or element key.

Retrieve a Specific Element Path Parameters

keyOrId

The element key is a unique alphanumeric identifier for the element, while the element id is a unique numeric identifier for the element. Replace keyOrId with either identifier.

Retrieve a Specific Element Response Fields

The table below shows an abbreviated list of response fields.

id	The element id is a unique numeric identifier for the element, distinct from the element key which is alphanumeric.
name	The display name of the element.
key	The element key is a unique alphanumeric identifier for the element, distinct from the element id which is numeric.
description	A brief description of the element.
image	The branded image associated with the element.
configuration	Object containing the configuration of the element.
transformationsEnabled	Indicates whether resources at the API provider can be mapped to a virtual data resource.
bulkDownloadEnabled/ bulkUploadEnabled	Indicates whether the element supports bulk.
extendable	Indicates whether you can extend the element by adding resources.
authentication	Identifies the type of authentication used.
extended	Identifies whether you have added resources to the element or not.
hub	The hub in which the element is categorized.
private	Indicates whether the element is part of the public element catalog or not.

Retrieve a Specific Element Example Request

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2/elements/sfdc \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -H 'Content-Type: application/json' \

Retrieve a Specific Element Example Response


{  
  "id":23,
  "name":"Salesforce Sales Cloud",
  "hookName":"Salesforcecom",
  "key":"sfdc",
  "description":"Add a Salesforce Instance to connect your existing Salesforce account to the CRM Hub, allowing you to manage contacts, leads, accounts, opportunities etc. across multiple CRM elements or your other Salesforce services. You will need your Salesforce account information to add an instance.",
  "image":"elements/provider_sfdc.png",
  "active":true,
  "deleted":false,
  "typeOauth":true,
  "trialAccount":false,
  "signupURL":"https://developer.salesforce.com/en/signup",
  "configuration":[  ],
  "defaultTransformations":[  ],
  "resources":[  ],
  "objects":[  ],
  "models":[  ],
  "transformationsEnabled":true,
  "bulkDownloadEnabled":true,
  "bulkUploadEnabled":true,
  "cloneable":true,
  "extendable":true,
  "beta":false,
  "authentication":{  },
  "hooks":[  ],
  "extended":false,
  "hub":"crm",
  "protocolType":"http",
  "parameters":[  ],
  "private":false
}

GET /elements/{keyOrId}/instances

GET /elements/{keyOrId}/instances

Retrieve all authenticated element instances of an element specified by element key or element id.

Path Parameters

keyOrId

The element key is a unique alphanumeric identifier for the element, while the element id is a unique numeric identifier for the element. Replace keyOrId with either identifier.

Response Fields

The table below shows an abbreviated list of response fields.

id	The element instance id is a unique numeric identifier for the authenticated element instance.
name	The display name of the authenticated element instance.
token	The element instance token returned upon authenticating an element instance. You must include the element instance token in the Authorization header of requests to the element instance.
element	Information about the element.
configuration	Object containing the configuration of the element.
eventsEnabled	Indicates whether events are configured for the instance.
user	An object containing details about the user.

Example Request

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2/elements/23/instances \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -H 'Content-Type: application/json' \

Example Response


{  
  "id":436470,
  "name":"Instance Name",
  "token":"+s9zKQa+1EQB9BPfVR1WqaPJfg9UQFwMxeHh+ZcXDiE=",
  "element":{  },
  "tags":[  ],
  "valid":true,
  "disabled":false,
  "configuration":{  },
  "eventsEnabled":false,
  "externalAuthentication":"none",
  "user":{  }
}

Create an Element Instance

POST /elements/{keyOrId}/instances

Create a new authenticated element instance specified by element key or element id.

Alternatively, you can create an element instance with a POST /instances request.

Create an Element Instance Path Parameters

keyOrId

The element key is a unique alphanumeric identifier for the element, while the element id is a unique numeric identifier for the element. Replace keyOrId with either identifier.

Create an Element Instance Request Body Parameters

The body parameters differ based on the authentication type and parameters required by each individual element. For specific requirements, see the Authenticate or Create Instance section in the documentation for a specific element. We've provided some default parameters below for our two most common authentication types: Basic and OAuth 2.0.

Basic Authentication Default Parameters

username	The user name needed to authenticate an element instance with Basic authentication. See the Element Documentation's Setup section to identify what value at the provider is used as the username.
password	The password needed to authenticate an element instance with Basic authentication. See the Element Documentation's Setup section to identify what value at the provider is used as the password.
tags	User-defined tags to further identify or categorize the element instance.
name	The display name of the authenticated element instance.

OAuth 2.0 Authentication Default Parameters

providerData.code	The authorization grant code returned from the API provider in an OAuth 2.0 authentication workflow. Cloud Elements uses the code to retrieve the OAuth access and refresh tokens from the endpoint.
oauth.api.key	The API key or client ID obtained by registering your app with the provider. See the Element Documentation's Setup section to identify what value at the provider is used as the API key.
oauth.api.secret	The API or client secret obtained by registering your app with the API provider. See the Element Documentation's Setup section to identify what value at the provider is used as the API secret.
oauth.callback.url	The URL where the API provider returns the authorization grant code and also where a user returns after they authorize access.
tags	User-defined tags to further identify or categorize the element instance.
name	The display name of the authenticated element instance.

Create an Element Instance Response Fields

The table below shows an abbreviated list of response fields.

id	The element instance id is a unique numeric identifier for the authenticated element instance.
name	The display name of the authenticated element instance.
createdDate	The date and time of the initial authentication of the the element instance.
token	The element instance token returned upon authenticating an element instance. You must include the element instance token in the Authorization header of requests to the element instance.
element	Information about the element.
configuration	Object containing the configuration of the element.
eventsEnabled	Indicates whether events are configured for the instance.
user	An object containing details about the user.

Create an Element Instance Example Request

The following example requests represent generic requests using Basic and OAuth 2.0 authentication.

Basic Authentication Example Request

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2/elements/insightly/instances \
  -H 'authorization: User sAfK7LJGNz5ZHcNrvdJvLI=f03WbTbH6aRKc0HJ3oOIi, Organization 58168435e3b9959a929eb04b6218b9a2' \ \
  -H 'Content-Type: application/json' \
  -d '{
  "configuration": {
    "username": "claudeelements",
    "password": "password"
  },
  "tags": [
    "Docs"
  ],
  "name": "Element Instance Name"
}'

OAuth 2.0 Authentication Example Request


curl -X POST \
  https://api.cloud-elements.com/elements/api-v2/elements/onedrivev2/instances \
  -H 'Authorization: User zn96SWr/RjPPWztl+oQcFkT0mbKPpW7hEvPkYcRy6xM=, Organization 4c193728a11e2d03025e29992948b12c' \
  -H 'Content-Type: application/json' \
  -d '{
  "providerData":{  
    "code":"WCT3Ny3QRbA6HDXY "
  },
  "configuration":{  
    "oauth.api.key": "Rand0MAP1-key",
    "oauth.api.secret":"fak3AP1-s3Cr3t",
    "oauth.callback.url":"https://mycoolapp.com"
  },
  "tags":[  
    "Docs"
  ],
  "name":"Element Instance Name"
}
'

Create an Element Instance Example Response


{  
  "id":477858,
  "name":"New Element",
  "createdDate":"2018-04-11T18:25:46Z",
  "token":"s1GKjbAO37W1UNsBd4GI80RmUPXk/nzTPFmLKwL1Tws=",
  "element":{  },
  "elementId":5993,
  "tags":[  ],
  "provisionInteractions":[  ],
  "valid":true,
  "disabled":false,
  "maxCacheSize":0,
  "cacheTimeToLive":0,
  "configuration":{  },
  "eventsEnabled":false,
  "traceLoggingEnabled":false,
  "cachingEnabled":false,
  "externalAuthentication":"none",
  "user":{  }
}