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:

UI API

Creating Common Resources via API

A common resource is a resource with normalized fields that you can use in place of specific elements to facilitate one-to-many integrations. In this section you will learn how to create a common resource at the organization level and map element resource data to it for transformation. You can create a common resource based on an existing resource (template, element resource, or existing common resource) or as an entirely new resource. This guide includes instructions for both methods.

Important: Only users at the organization level can create common resources, but users at any level can create transformations at the instance level. If you are not a user at the organization level, skip to Creating Transformations.

You can test the APIs described in this section using our interactive documentation. Open Cloud Elements, and then click in the header. Under Platform API Documentation, open organizations for common resources and transformations .

To create a common resource, go to the steps that match how you plan to create the resource:

Create a New Common Resource for steps to create an entirely new common resource.
Create a Common Resource Based on Another Common Resource for steps to create a resource based on an existing resource. You might create copies of resources to provide different common resources for different accounts.
Create a Common Resource Based on an Element Instance Resource for steps to create a common resource based on an element resource. You might use element instance resources because you want your common resource to be based on a certain element.
Create a Common Resource Based on a Cloud Elements Template for steps to create a common resource based on a Cloud Elements template. Cloud Elements templates represent typical common resources.

Create a New Common Resource

Follow the instructions in this section to create an entirely new common resource. When finished, you will have a common resource with a single default field called id.

To create a new common resource:

Construct a JSON body as shown below (see New Common Resource JSON Parameters):

{
  "<objectName>": {
    "fields": [
      {
        "path": "<fieldName>",
        "type": "<dataType>"
      }
    ]
  }
}

Call the following, including the JSON body you constructed in the previous step:
```
  POST /organizations/objects/definition
```
Continue to the next step: map fields to the common resource.

New Common Resource JSON Parameters

Parameter	Description
objectName	The name of the new common resource.
fields	An object containing the field names and data types of the common resource.
path	The name of the field.
type	The data type of the field.

cURL Example

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2/organizations/objects/definitions \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json' \
  -d '
  {
    "myContacts": {
      "fields": [
        {
          "path": "id",
          "type": "string"
        }
      ]
    }
  }'

Create a Common Resource Based on Another Common Resource

You can create a common resource based on other common resources in your organization. You might do this to create variations of a common resource for multiple different accounts.

To set up a common resource based on an existing common resource:

Call the following, replacing {objectName} with the name of the common resource that you want to copy:
```
  GET /organizations/objects/{objectName}/definitions
```
Copy the fields array in the response to the JSON body for POST /organizations/objects/definitions (see Create a New Common Resource).
Continue to the next step: map fields to create a transformation.

cURL Example

1. Get the Existing Common Resource Payload

curl --request GET \
  --url https://staging.cloud-elements.com/elements/api-v2/organizations/objects/[COMMON_RESOURCE_NAME]/definitions \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json' \

2. Create the Copy of the Common Resources

curl -X POST \
  https://api.cloud-elements.com/elements/api-v2/organizations/objects/definitions \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json' \
  -d '
  {
    "Copy_of_existing_resource": {
    "fields": [
      {
        "type": "string",
        "path": "FirstName"
      },
      {
        "type": "string",
        "path": "id"
      },
      {
        "type": "string",
        "path": "LastName"
      }
      ]
    }
  }
'

Create a Common Resource Based on an Element Instance Resource

You can create a new common resource based on an element resource. For example, if you know that you want all of your contacts to match the contacts in the Salesforce Contact resource, you would create a new resource based on the Salesforce Contact resource.

To set up a common resource based on an existing element instance:

Call the following to get the element token (token) for the instance:
```
  GET /instances/{id}
```
Or if you do not know the instance ID, you can call:
```
GET /instances
```
Save the element token to use in the header of the next API call.
Call the following, replacing {objectName} with the name of the element instance resource, to get the fields that comprise the resource:
```
  GET /objects/{objectName}/metadata
```
Note: Make sure that you include the token from GET /instances/{id} in the header.
Copy the vendorPath and type fields to a new JSON body.
Rename vendorPath to path.
Use the new JSON body for POST /organizations/objects/definitions (see Create a New Common Resource).
Continue to the next step: map fields to the common resource.

cURL Example

1. Get the Element Token

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2/instances/{INSTANCE_ID} \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json' \

2. Get the Fields in the Resource

curl --request GET \
  --url https://api.cloud-elements.com/elements/api-v2/hubs/crm/objects/{RESOURCE}/metadata \
  --H 'authorization: User [USER_SECRET], Element [ELEMENT_TOKEN]' \
  --H 'content-type: application/json' \

3. Create the Common Resource Based on the Element Resource

  curl -X POST \
    https://api.cloud-elements.com/elements/api-v2/organizations/objects/definitions \
    -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
    -H 'content-type: application/json' \
    -d '
  {
    "Element_Instance_Resource": {
    "fields": [
      {
        "type": "string",
        "path": "FirstName"
      },
      {
        "type": "string",
        "path": "id"
      },
      {
        "type": "string",
        "path": "LastName"
      }
      ]
    }
  }
  '

Create a Common Resource Based on a Cloud Elements Template

Cloud Elements provides templates for several frequently used resources like accounts and contacts. You can use these templates as a starting point for your own definitions of a common resource.

To set up a common resource based on a Cloud Elements template:

Call the following to get a list of Cloud Elements templates and their fields.
```
  GET /organizations/objects/definitions?systemOnly=true
```
Locate the template that you want to use.
Copy the fields array to the JSON body for POST /organizations/objects/definitions (see Create a New Common Resource).
Continue to the next step: map fields to the common resource.

cURL Example

1. Get the List of Cloud Elements Templates

curl -X GET \
  https://api.cloud-elements.com/elements/api-v2//organizations/objects/definitions?systemOnly=true \
  -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
  -H 'content-type: application/json' \

2. Create the Common Resource Based on the Element Resources

  curl -X POST \
    https://api.cloud-elements.com/elements/api-v2/organizations/objects/definitions \
    -H 'authorization: User {USER_SECRET}, Organization {ORGANIZATION_SECRET}' \
    -H 'content-type: application/json' \
    -d '
  {
    "Resource_Based_on_Template_API2": {
    "fields": [
      {
        "type": "string",
        "path": "name"
      },
      {
        "type": "string",
        "path": "lastName"
      },
      {
        "type": "string",
        "path": "email"
      },
      {
        "type": "string",
        "path": "id"
      },
      {
        "type": "boolean",
        "path": "active"
      },
      {
        "type": "string",
        "path": "phone"
      },
      {
        "type": "string",
        "path": "notes"
      }
      ]
    }
  }
  '