Introduction to the CRM API 

Start with our Core API docs for an introduction to the Kloudless API and more information on connecting user accounts and performing API requests.

Once an account is connected to your application, your application can perform API requests to the CRM API endpoints listed below.

Here are the supported services, listed with service identifiers:

  • CRM Services
    • Salesforce CRM: salesforce
    • Microsoft Dynamics: dynamics
    • Oracle Sales Cloud: oracle
    • Pipeliner CRM: pipeliner
    • Zoho CRM: zoho
    • HubSpot CRM: hubspot
    • SugarCRM: sugarcrm

The CRM API has the following available object types:

  • account

  • contact

  • campaign

  • lead

  • opportunity

  • task

Each object type is documented below, with its standard Kloudless attributes listed.

In addition, we can provide the original JSON response from the upstream service, which we call raw data. Please set the raw data header option when performing API requests, and the server will return the raw data in the the JSON response object under the raw key field.

Similarly, raw data can be sent directly to the upstream service via the API when creating or updating objects. This is primarily for attributes that are not unified in the Kloudless APIs. The request body must contain a nested JSON object with the upstream attribute names and values. Please see the example below:

javascript
{
    "raw": {
        "object": {
            ...
            "upstream-name": "upstream-values",
            ...
        }
    }
}

We define this nested object with the shorthand: raw -> object.

Check out Account creation for an example.


Data Mapper 

The Kloudless Data Mapper enables an app’s users to map their cloud data to and from the app.

Check out our Data Mapper Guide for more information.

Behind the scenes, the Data Mapper uses the Custom Mappings API documented below.


CRM Accounts 

An account represents a Company, Department, or Person within the company, with which your organization is currently involved with. You can associate an account with Contacts and Opportunities.

*Note: This is not to be confused with the Accounts resource, which represents a software service account connected to your Kloudless application.

  • id Unique identifier for this account

  • name Account name

  • owner Identifier of the user that owns this account

  • industry_code Six-digit North American Industry Classification System (NAICS) code

  • industry Industry of account

  • employees Number of employees

  • rating Rating of the account

  • fax Fax number of the account

  • phone Phone number of the account

  • website URL of the company’s Web site

  • annual_revenue Annual revenue of the account

  • billing_address Billing address of the account to deliver the shipment

  • shipping_address Shipping address of the account to deliver the shipment

  • created ISO 8601 timestamp indicating when the account object was created.

  • modified ISO 8601 timestamp indicating when the account object was modified.

  • description Additional details about the Account

  • type Type of object. Always account.

  • raw Underlying object retrieved from the service.

  • api Always crm.

  • href The absolute URL to get the object’s metadata.

List Accounts 

list accountsGET /accounts/{account_id}/crm/accounts{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of account objects

  • type Always object_list

  • api Always crm

  • Parameters
  • page_size
    number (optional) Default: 100 

    Number of objects in each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "count": 1,
      "page": 1,
      "next_page": null,
      "objects": [
        {
          "id": "FxglejHI8xUDiI8L61mPawyjoRZNjDP7-acJTHpvzcrA=",
          "created": "2018-11-16T06:24:39Z",
          "modified": "2018-11-16T06:24:39Z",
          "type": "account",
          "api": "crm",
          "name": "Simplynk, Inc.",
          "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
          "industry_code": "541519",
          "industry": "Information Technology",
          "employees": 4,
          "rating": "Hot",
          "fax": null,
          "phone": null,
          "website": "https://angel.co/simplynk",
          "annual_revenue": null,
          "billing_address": null,
          "shipping_address": null,
          "description": "Location-based professional networking",
          "href": "https://api.kloudless.com/v1/accounts/123/crm/accounts/FxglejHI8xUDiI8L61mPawyjoRZNjDP7-acJTHpvzcrA="
        }
      ],
      "type": "object_list",
      "api": "crm"
    }

Create an Account 

create an accountPOST /accounts/{account_id}/crm/accounts

To create an account, perform a POST request with a JSON object of the following parameters:

  • name: Name of the account (required)

  • owner: Identifier of the user that owns this account

  • industry_code: Six-digit North American Industry Classification System (NAICS) code

  • industry: Industry of the account

  • employees: Number of employees

  • rating: Rating of the account

  • fax: Fax number of the account

  • phone: Phone number of the account

  • website: URL of the company’s Web site

  • annual_revenue: Annual revenue of the account

  • billing_address: Billing address of the account to deliver the shipment

  • shipping_address: Shipping address of the account to deliver the shipment

  • description: Details about the account

  • raw: Raw attribute names and values that will be propagated during request

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/crm/accounts' \
    -XPOST -d '{
        "name":"Simplynk, Inc.",
        "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
        "industry_code": "541519",
        "industry": "Information Technology",
        "employees": 4,
        "rating": "Hot",
        "website": "https://angel.co/simplynk",
        "description": "Location-based professional networking",
        "raw": {
            "object": {
                "BillingCity": "San Francisco",
                "IsPartner": true
            }
        }
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "name": "Simplynk, Inc.",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "industry_code": "541519",
      "industry": "Information Technology",
      "employees": 4,
      "rating": "Hot",
      "website": "https://angel.co/simplynk",
      "description": "Location-based professional networking",
      "raw": {
        "object": {
          "BillingCity": "San Francisco",
          "IsPartner": true
        }
      }
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "FxglejHI8xUDiI8L61mPawyjoRZNjDP7-acJTHpvzcrA=",
      "created": "2018-11-16T06:24:39Z",
      "modified": "2018-11-16T06:24:39Z",
      "type": "account",
      "api": "crm",
      "name": "Simplynk, Inc.",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "industry_code": "541519",
      "industry": "Information Technology",
      "employees": 4,
      "rating": "Hot",
      "fax": null,
      "phone": null,
      "website": "https://angel.co/simplynk",
      "annual_revenue": null,
      "billing_address": null,
      "shipping_address": null,
      "description": "Location-based professional networking",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/accounts/FxglejHI8xUDiI8L61mPawyjoRZNjDP7-acJTHpvzcrA="
    }

Retrieve an Account 

retrieve an accountGET /accounts/{account_id}/crm/accounts/{account_id}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "FxglejHI8xUDiI8L61mPawyjoRZNjDP7-acJTHpvzcrA=",
      "created": "2018-11-16T06:24:39Z",
      "modified": "2018-11-16T06:24:39Z",
      "type": "account",
      "api": "crm",
      "name": "Simplynk, Inc.",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "industry_code": "541519",
      "industry": "Information Technology",
      "employees": 4,
      "rating": "Hot",
      "fax": null,
      "phone": null,
      "website": "https://angel.co/simplynk",
      "annual_revenue": null,
      "billing_address": null,
      "shipping_address": null,
      "description": "Location-based professional networking",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/accounts/FxglejHI8xUDiI8L61mPawyjoRZNjDP7-acJTHpvzcrA="
    }

Update an Account 

update an accountPATCH /accounts/{account_id}/crm/accounts/{account_id}

To update an account, create a JSON object with any of the following properties:

  • name

  • industry_code

  • industry

  • employees

  • rating

  • fax

  • phone

  • website

  • annual_revenue

  • billing_address

  • shipping_address

  • description

  • raw

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "employees": 4,
        "description": "Location-based professional networking",
        "raw": {
            "object": {
                "IsPartner": false
            }
        }
    }' \
    'https://api.kloudless.com/v1/accounts/15/crm/accounts/FxglejHI7xUDiI8L61mPawyjoRZNjDP7-acJTHpvzcrA='
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "employees": 4,
      "description": "Location-based professional networking",
      "raw": {
        "object": {
          "IsPartner": false
        }
      }
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "FxglejHI8xUDiI8L61mPawyjoRZNjDP7-acJTHpvzcrA=",
      "created": "2018-11-16T06:24:39Z",
      "modified": "2018-11-16T06:24:39Z",
      "type": "account",
      "api": "crm",
      "name": "Simplynk, Inc.",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "industry_code": "541519",
      "industry": "Information Technology",
      "employees": 4,
      "rating": "Hot",
      "fax": null,
      "phone": null,
      "website": "https://angel.co/simplynk",
      "annual_revenue": null,
      "billing_address": null,
      "shipping_address": null,
      "description": "Location-based professional networking",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/accounts/FxglejHI8xUDiI8L61mPawyjoRZNjDP7-acJTHpvzcrA="
    }

Delete an Account 

delete an accountDELETE /accounts/{account_id}/crm/accounts/{account_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/34/crm/accounts/FxglejHI7xUDiI8L61mPawyjoRZNjDP7-acJTHpvzcrA=
  • Response  204

CRM Contacts 

A contact represents a person with whom you communicate in an organization, either in pursuit of a business opportunity or for personal reasons.

  • id Unique identifier for this contact

  • account Identifier of the associated account

  • owner Identifier of the user that owns this contact

  • first_name First name of the contact

  • middle_name Middle name of the contact

  • last_name Last name of the contact (required)

  • name Name of the contact

  • title Title of the contact

  • department Department of the contact

  • email Email of the contact

  • fax Fax of the contact

  • phone Phone of the contact

  • mailing_address Mailing address of the contact

  • created ISO 8601 timestamp indicating when the contact object was created.

  • modified ISO 8601 timestamp indicating when the contact object was modified.

  • description Additional details about the Contact

  • type Type of object. Always contact

  • raw Underlying object retrieved from the service

  • api Always crm.

  • href The absolute URL to get the object’s metadata.

List Contacts 

list contactsGET /accounts/{account_id}/crm/contacts{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of contact objects

  • type Always object_list

  • api Always crm

  • Parameters
  • page_size
    number (optional) Default: 100 

    Number of objects in each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

    account
    string (optional) 

    Filter by associated account id. Note: this is only supported in hubspot

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "count": 1,
      "page": 1,
      "next_page": null,
      "objects": [
        {
          "id": "FCmbbsCTdOD_vOzcZTTTViotQ-lb0AivJvLUslhqOve8=",
          "created": "2018-11-16T10:05:51Z",
          "modified": "2018-11-16T10:05:51Z",
          "type": "contact",
          "api": "crm",
          "account": "FMrg5coFKyiInkR2g1PnYWCrYZY9zWwUWk7yO_B1Viog=",
          "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
          "first_name": "David",
          "last_name": "Yu",
          "name": "Yu David",
          "title": "Customer Service Advisor",
          "department": "Support",
          "email": "hello@kloudless.com",
          "fax": null,
          "phone": null,
          "mailing_address": null,
          "description": "Support of Kloudless, Inc.",
          "href": "https://api.kloudless.com/v1/accounts/123/crm/contacts/FCmbbsCTdOD_vOzcZTTTViotQ-lb0AivJvLUslhqOve8="
        }
      ],
      "type": "object_list",
      "api": "crm"
    }

Create a Contact 

create a contactPOST /accounts/{account_id}/crm/contacts

To create a contact, perform a POST request with a JSON object of the following parameters:

  • first_name: First name of the contact

  • middle_name: Middle name of the contact

  • last_name: Last Name of the contact (required)

  • name: Name of the contact

  • account: Identifier of the associated account

  • owner: Identifier of the user that owns this contact

  • title: Title of the contact

  • department: Department of the contact

  • email: Email of the contact

  • fax: Fax of the contact

  • phone: Phone of the contact

  • mailing_address: Mailing address of the account to deliver the shipment

  • description: Additional details about the Contact

  • raw: Raw attribute names and values that will be propagated during request

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/crm/contacts' \
    -XPOST -d '{
        "account": "FMrg5coFKyiInkR2g1PnYWCrYZY9zWwUWk7yO_B1Viog=",
        "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
        "first_name": "David",
        "last_name": "Yu",
        "title": "Customer Service Advisor",
        "department": "Support",
        "email": "hello@kloudless.com",
        "description": "Support of Kloudless, Inc.",
        "raw": {
            "object": {
                "Suffix": "M.S."
            }
        }
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "account": "FMrg5coFKyiInkR2g1PnYWCrYZY9zWwUWk7yO_B1Viog=",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "first_name": "David",
      "last_name": "Yu",
      "title": "Customer Service Advisor",
      "department": "Support",
      "email": "hello@kloudless.com",
      "description": "Support of Kloudless, Inc.",
      "raw": {
        "object": {
          "Suffix": "M.S."
        }
      }
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "FCmbbsCTdOD_vOzcZTTTViotQ-lb0AivJvLUslhqOve8=",
      "created": "2018-11-16T10:05:51Z",
      "modified": "2018-11-16T10:05:51Z",
      "type": "contact",
      "api": "crm",
      "account": "FMrg5coFKyiInkR2g1PnYWCrYZY9zWwUWk7yO_B1Viog=",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "first_name": "David",
      "last_name": "Yu",
      "name": "Yu David",
      "title": "Customer Service Advisor",
      "department": "Support",
      "email": "hello@kloudless.com",
      "fax": null,
      "phone": null,
      "mailing_address": null,
      "description": "Support of Kloudless, Inc.",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/contacts/FCmbbsCTdOD_vOzcZTTTViotQ-lb0AivJvLUslhqOve8="
    }

Retrieve a Contact 

retrieve a contactGET /accounts/{account_id}/crm/contacts/{contact_id}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "FCmbbsCTdOD_vOzcZTTTViotQ-lb0AivJvLUslhqOve8=",
      "created": "2018-11-16T10:05:51Z",
      "modified": "2018-11-16T10:05:51Z",
      "type": "contact",
      "api": "crm",
      "account": "FMrg5coFKyiInkR2g1PnYWCrYZY9zWwUWk7yO_B1Viog=",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "first_name": "David",
      "last_name": "Yu",
      "name": "Yu David",
      "title": "Customer Service Advisor",
      "department": "Support",
      "email": "hello@kloudless.com",
      "fax": null,
      "phone": null,
      "mailing_address": null,
      "description": "Support of Kloudless, Inc.",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/contacts/FCmbbsCTdOD_vOzcZTTTViotQ-lb0AivJvLUslhqOve8="
    }

Update a Contact 

update a contactPATCH /accounts/{account_id}/crm/contacts/{contact_id}

To update a contact, create a JSON object with any of the following properties:

  • account

  • owner

  • first_name

  • middle_name

  • last_name

  • title

  • department

  • email

  • fax

  • phone

  • mailing_address

  • description

  • raw

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "description": "Support of Kloudless, Inc."
    }' \
    'https://api.kloudless.com/v1/accounts/15/crm/contacts/FCmbbsCTdOD_vOzcZTTTViotQ-lb0AivJvLUslhqOve8='
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "description": "Support of Kloudless, Inc."
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "FCmbbsCTdOD_vOzcZTTTViotQ-lb0AivJvLUslhqOve8=",
      "created": "2018-11-16T10:05:51Z",
      "modified": "2018-11-16T10:05:51Z",
      "type": "contact",
      "api": "crm",
      "account": "FMrg5coFKyiInkR2g1PnYWCrYZY9zWwUWk7yO_B1Viog=",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "first_name": "David",
      "last_name": "Yu",
      "name": "Yu David",
      "title": "Customer Service Advisor",
      "department": "Support",
      "email": "hello@kloudless.com",
      "fax": null,
      "phone": null,
      "mailing_address": null,
      "description": "Support of Kloudless, Inc.",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/contacts/FCmbbsCTdOD_vOzcZTTTViotQ-lb0AivJvLUslhqOve8="
    }

Delete a Contact 

delete a contactDELETE /accounts/{account_id}/crm/contacts/{contact_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/34/crm/contacts/FCmbbsCTdOD_vOzcZTTTViotQ-lb0AivJvLUslhqOve8=
  • Response  204

CRM Leads 

A lead represents details about individuals or representatives of organizations who might be potential opportunities.

  • id Unique identifier for this lead

  • owner Identifier of the user that owns this contact

  • name Name of the lead

  • first_name First name of the lead

  • middle_name Middle name of the lead

  • last_name Last name of the lead

  • title Title of the lead

  • status Status of the lead

  • address Address of the lead

  • company Company of the lead

  • industry Industry of the company of the lead

  • annual_revenue Annual revenue of the company

  • rating Rating of the lead

  • email Email of the lead

  • fax Fax of the lead

  • phone Phone of the lead

  • created ISO 8601 timestamp indicating when the lead object was created.

  • modified ISO 8601 timestamp indicating when the lead object was modified.

  • description Additional details about the Lead

  • type Type of object. Always lead

  • raw Underlying object retrieved from the service

  • api Always crm.

  • href The absolute URL to get the object’s metadata.

List Leads 

list leadsGET /accounts/{account_id}/crm/leads{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of lead objects

  • type Always object_list

  • api Always crm

  • Parameters
  • page_size
    number (optional) Default: 100 

    Number of objects in each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "count": 1,
      "page": 1,
      "next_page": null,
      "objects": [
        {
          "id": "Fn10s8MlRoroahRxLYcemdz-BpJ_Gs4ALDgycki6xhyA=",
          "created": "2018-11-16T10:38:10Z",
          "modified": "2018-11-16T10:38:10Z",
          "type": "lead",
          "api": "crm",
          "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
          "name": "Chandru Vinod",
          "first_name": "Vinod",
          "last_name": "Chandru",
          "title": "Developer",
          "status": "Contacted",
          "address": null,
          "company": "Kloudless, Inc.",
          "industry": "Information Technology",
          "annual_revenue": null,
          "rating": "Hot",
          "email": "hello@kloudless.com",
          "fax": null,
          "phone": null,
          "description": "Good contact for Sharepoint",
          "href": "https://api.kloudless.com/v1/accounts/123/crm/leads/Fn10s8MlRoroahRxLYcemdz-BpJ_Gs4ALDgycki6xhyA="
        }
      ],
      "type": "object_list",
      "api": "crm"
    }

Create a Lead 

create a leadPOST /accounts/{account_id}/crm/leads

To create a lead, perform a POST request with a JSON object of the following parameters:

  • first_name: First name of the lead

  • middle_name: Middle name of the lead

  • last_name: Last name of the lead (required)

  • title: Title of the lead

  • status: Status of the lead

  • address: Address of the lead

  • company: Company of the lead (required)

  • industry: Industry of the company of the lead

  • annual_revenue: Annual revenue of the company

  • rating: Rating of the lead

  • email: Email of the lead

  • fax: Fax of the lead

  • phone: Phone of the lead

  • description: Additional details about the Lead

  • raw: Raw attribute names and values that will be propagated during request

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/crm/leads' \
    -XPOST -d '{
        "first_name": "Vinod",
        "last_name": "Chandru",
        "title": "Developer",
        "status": "Contacted",
        "company": "Kloudless, Inc.",
        "industry": "Information Technology",
        "rating": "Hot",
        "email": "hello@kloudless.com",
        "description": "Good contact for Sharepoint"
        "raw": {
            "object": {
                "State": "CA"
            }
        }
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "first_name": "Vinod",
      "last_name": "Chandru",
      "title": "Developer",
      "status": "Contacted",
      "company": "Kloudless, Inc.",
      "industry": "Information Technology",
      "rating": "Hot",
      "email": "hello@kloudless.com",
      "description": "Good contact for Sharepoint",
      "raw": {
        "object": {
          "State": "CA"
        }
      }
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "Fn10s8MlRoroahRxLYcemdz-BpJ_Gs4ALDgycki6xhyA=",
      "created": "2018-11-16T10:38:10Z",
      "modified": "2018-11-16T10:38:10Z",
      "type": "lead",
      "api": "crm",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "name": "Chandru Vinod",
      "first_name": "Vinod",
      "last_name": "Chandru",
      "title": "Developer",
      "status": "Contacted",
      "address": null,
      "company": "Kloudless, Inc.",
      "industry": "Information Technology",
      "annual_revenue": null,
      "rating": "Hot",
      "email": "hello@kloudless.com",
      "fax": null,
      "phone": null,
      "description": "Good contact for Sharepoint",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/leads/Fn10s8MlRoroahRxLYcemdz-BpJ_Gs4ALDgycki6xhyA="
    }

Retrieve a Lead 

retrieve a leadGET /accounts/{account_id}/crm/leads/{lead_id}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "Fn10s8MlRoroahRxLYcemdz-BpJ_Gs4ALDgycki6xhyA=",
      "created": "2018-11-16T10:38:10Z",
      "modified": "2018-11-16T10:38:10Z",
      "type": "lead",
      "api": "crm",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "name": "Chandru Vinod",
      "first_name": "Vinod",
      "last_name": "Chandru",
      "title": "Developer",
      "status": "Contacted",
      "address": null,
      "company": "Kloudless, Inc.",
      "industry": "Information Technology",
      "annual_revenue": null,
      "rating": "Hot",
      "email": "hello@kloudless.com",
      "fax": null,
      "phone": null,
      "description": "Good contact for Sharepoint",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/leads/Fn10s8MlRoroahRxLYcemdz-BpJ_Gs4ALDgycki6xhyA="
    }

Update a Lead 

update a leadPATCH /accounts/{account_id}/crm/leads/{lead_id}

To update an lead, create a JSON object with any of the following properties:

  • name

  • title

  • status

  • address

  • company

  • industry

  • annual_revenue

  • rating

  • email

  • fax

  • phone

  • description

  • raw

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "description": "Good contact for Sharepoint"
    }' \
    'https://api.kloudless.com/v1/accounts/15/crm/leads/Fn10s8MlRoroahRxLYcemdz-BpJ_Gs4ALDgycki6xhyA='
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "description": "Good contact for Sharepoint"
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "Fn10s8MlRoroahRxLYcemdz-BpJ_Gs4ALDgycki6xhyA=",
      "created": "2018-11-16T10:38:10Z",
      "modified": "2018-11-16T10:38:10Z",
      "type": "lead",
      "api": "crm",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "name": "Chandru Vinod",
      "first_name": "Vinod",
      "last_name": "Chandru",
      "title": "Developer",
      "status": "Contacted",
      "address": null,
      "company": "Kloudless, Inc.",
      "industry": "Information Technology",
      "annual_revenue": null,
      "rating": "Hot",
      "email": "hello@kloudless.com",
      "fax": null,
      "phone": null,
      "description": "Good contact for Sharepoint",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/leads/Fn10s8MlRoroahRxLYcemdz-BpJ_Gs4ALDgycki6xhyA="
    }

Delete a Lead 

delete a leadDELETE /accounts/{account_id}/crm/leads/{lead_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/34/crm/leads/Fn10s8MlRoroahRxLYcemdz-BpJ_Gs4ALDgycki6xhyA=
  • Response  204

CRM Opportunities 

An opportunity represents a business deal with companies or people that generate real revenue for your organization.

  • id Unique identifier for this opportunity

  • account Identifier of the associated account

  • campaign Identifier of the campaign associated with this opportunity

  • owner Identifier of the user that owns this campaign

  • name Name for this opportunity

  • stage_name Current stage of this record

  • closing_date Date when the opportunity is expected to close

  • next_step Description of the next step in closing opportunity

  • amount Estimated total sale amount

  • probability Probability (%) of closing an opportunity

  • opportunity_type Type of opportunity

  • created ISO 8601 timestamp indicating when the account object was created.

  • modified ISO 8601 timestamp indicating when the account object was modified.

  • description Additional details about the Opportunity

  • type Type of object. Always opportunity

  • raw Underlying object retrieved from the service

  • api Always crm.

  • href The absolute URL to get the object’s metadata.

List Opportunities 

list opportunitiesGET /accounts/{account_id}/crm/opportunities{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of opportunity objects

  • type Always object_list

  • api Always crm

  • Parameters
  • page_size
    number (optional) Default: 100 

    Number of objects in each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

    account
    string (optional) 

    Filter by associated account id. Note: this is only supported in hubspot

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "count": 1,
      "page": 1,
      "next_page": null,
      "objects": [
        {
          "id": "FVe6WGOASp8PBXhhPN-HDnAfLmf12B7bOPPb7Ru9qHow=",
          "created": "2018-11-17T12:43:17Z",
          "modified": "2018-11-17T12:43:17Z",
          "type": "opportunity",
          "api": "crm",
          "account": "FMrg5coFKyiInkR2g1PnYWCrYZY9zWwUWk7yO_B1Viog=",
          "campaign": "FMQTADT0E6ehHME207tURBF5jv3_Brz740FboFJYRGAU=",
          "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
          "name": "Integration with Cloud CRM Services",
          "stage_name": "Prospect",
          "closing_date": "2016-01-01",
          "next_step": "Contact development team for progress of integration",
          "amount": 7777777,
          "probability": 77,
          "opportunity_type": "Existing Business",
          "description": "Adding support for Microsoft Dynamics",
          "href": "https://api.kloudless.com/v1/accounts/123/crm/opportunities/FVe6WGOASp8PBXhhPN-HDnAfLmf12B7bOPPb7Ru9qHow="
        }
      ],
      "type": "object_list",
      "api": "crm"
    }

Create an Opportunity 

create an opportunityPOST /accounts/{account_id}/crm/opportunities

To create an opportunity, perform a POST request with a JSON object of the following parameters:

  • name: Name for this opportunity (required)

  • owner: Identifier of the user that owns this contact

  • stage_name: Current stage of this record (required)

  • close_date: Date when the opportunity is expected to close (required)

  • account: Identifier of the associated account

  • campaign: Identifier of the campaign associated with this opportunity

  • next_step: Description of the next step in closing opportunity

  • amount: Estimated total sale amount

  • probability: Probability (%) of closing an opportunity

  • opportunity_type: Type of opportunity

  • description: Details about the opportunity

  • raw: Raw attribute names and values that will be propagated during request

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/crm/opportunities' \
    -XPOST -d '{
        "account": "FMrg5coFKyiInkR2g1PnYWCrYZY9zWwUWk7yO_B1Viog=",
        "campaign": "FMQTADT0E6ehHME207tURBF5jv3_Brz740FboFJYRGAU=",
        "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
        "name": "Integration with Cloud CRM Services",
        "stage_name": "Prospect",
        "closing_date": "2016-01-01T01:01:01.010000Z",
        "next_step": "Contact development team for progress of integration",
        "amount": 7777777,
        "probability": 77,
        "opportunity_type": "Existing Business",
        "description": "Adding support for Microsoft Dynamics",
        "raw": {
            "object": {
                "Fiscal": "2018 4"
            }
        }
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "account": "FMrg5coFKyiInkR2g1PnYWCrYZY9zWwUWk7yO_B1Viog=",
      "campaign": "FMQTADT0E6ehHME207tURBF5jv3_Brz740FboFJYRGAU=",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "name": "Integration with Cloud CRM Services",
      "stage_name": "Prospect",
      "closing_date": "2016-01-01T01:01:01.010000Z",
      "next_step": "Contact development team for progress of integration",
      "amount": 7777777,
      "probability": 77,
      "opportunity_type": "Existing Business",
      "description": "Adding support for Microsoft Dynamics",
      "raw": {
        "object": {
          "Fiscal": "2018 4"
        }
      }
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "FVe6WGOASp8PBXhhPN-HDnAfLmf12B7bOPPb7Ru9qHow=",
      "created": "2018-11-17T12:43:17Z",
      "modified": "2018-11-17T12:43:17Z",
      "type": "opportunity",
      "api": "crm",
      "account": "FMrg5coFKyiInkR2g1PnYWCrYZY9zWwUWk7yO_B1Viog=",
      "campaign": "FMQTADT0E6ehHME207tURBF5jv3_Brz740FboFJYRGAU=",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "name": "Integration with Cloud CRM Services",
      "stage_name": "Prospect",
      "closing_date": "2016-01-01",
      "next_step": "Contact development team for progress of integration",
      "amount": 7777777,
      "probability": 77,
      "opportunity_type": "Existing Business",
      "description": "Adding support for Microsoft Dynamics",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/opportunities/FVe6WGOASp8PBXhhPN-HDnAfLmf12B7bOPPb7Ru9qHow="
    }

Retrieve an Opportunity 

retrieve an opportunityGET /accounts/{account_id}/crm/opportunities/{opportunity_id}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "FVe6WGOASp8PBXhhPN-HDnAfLmf12B7bOPPb7Ru9qHow=",
      "created": "2018-11-17T12:43:17Z",
      "modified": "2018-11-17T12:43:17Z",
      "type": "opportunity",
      "api": "crm",
      "account": "FMrg5coFKyiInkR2g1PnYWCrYZY9zWwUWk7yO_B1Viog=",
      "campaign": "FMQTADT0E6ehHME207tURBF5jv3_Brz740FboFJYRGAU=",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "name": "Integration with Cloud CRM Services",
      "stage_name": "Prospect",
      "closing_date": "2016-01-01",
      "next_step": "Contact development team for progress of integration",
      "amount": 7777777,
      "probability": 77,
      "opportunity_type": "Existing Business",
      "description": "Adding support for Microsoft Dynamics",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/opportunities/FVe6WGOASp8PBXhhPN-HDnAfLmf12B7bOPPb7Ru9qHow="
    }

Update an Opportunity 

update an opportunityPATCH /accounts/{account_id}/crm/opportunities/{opportunity_id}

To update an opportunity, create a JSON object with any of the following properties:

  • account

  • campaign

  • owner

  • name

  • stage_name

  • closing_date

  • next_step

  • amount

  • probability

  • opportunity_type

  • description

  • raw

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "stage_name": "Prospect",
        "description": "Adding support for Microsoft Dynamics"
    }' \
    'https://api.kloudless.com/v1/accounts/15/crm/opportunities/FVe6WGOASp8PBXhhPN-HDnAfLmf12B7bOPPb7Ru9qHow='
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "stage_name": "Prospect",
      "description": "Adding support for Microsoft Dynamics"
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "FVe6WGOASp8PBXhhPN-HDnAfLmf12B7bOPPb7Ru9qHow=",
      "created": "2018-11-17T12:43:17Z",
      "modified": "2018-11-17T12:43:17Z",
      "type": "opportunity",
      "api": "crm",
      "account": "FMrg5coFKyiInkR2g1PnYWCrYZY9zWwUWk7yO_B1Viog=",
      "campaign": "FMQTADT0E6ehHME207tURBF5jv3_Brz740FboFJYRGAU=",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "name": "Integration with Cloud CRM Services",
      "stage_name": "Prospect",
      "closing_date": "2016-01-01",
      "next_step": "Contact development team for progress of integration",
      "amount": 7777777,
      "probability": 77,
      "opportunity_type": "Existing Business",
      "description": "Adding support for Microsoft Dynamics",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/opportunities/FVe6WGOASp8PBXhhPN-HDnAfLmf12B7bOPPb7Ru9qHow="
    }

Delete an Opportunity 

delete an opportunityDELETE /accounts/{account_id}/crm/opportunities/{opportunity_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/34/crm/opportunities/FVe6WGOASp8PBXhhPN-HDnAfLmf12B7bOPPb7Ru9qHow=
  • Response  204

CRM Campaigns 

A campaign is a container to plan, execute and monitor the progress of marketing activities.

  • id Unique identifier for this campaign

  • owner Identifier of the user that owns this campaign

  • parent Identifier of the parent object

  • name Name of campaign

  • campaign_type Type of campaign

  • start Start date of campaign

  • end End date of campaign

  • status Status of campaign

  • expected_revenue Expected revenue

  • actual_cost Actual cost of campaign

  • budgeted_cost Budgeted cost of campaign

  • created ISO 8601 timestamp indicating when the campaign object was created.

  • modified ISO 8601 timestamp indicating when the campaign object was modified.

  • description Additional details about the Campaign

  • type Type of object. Always campaign

  • raw Underlying object retrieved from the service

  • api Always crm.

  • href The absolute URL to get the object’s metadata.

Connector-specific notes:

  • hubspot: The Hubspot API only supports listing and retrieving email campaign data. Email campaigns are created/updated by Hubspot internally. As always, use the X-Kloudless-Raw-Data: true header to retrieve the full raw response body from Hubspot.

List Campaigns 

list campaignsGET /accounts/{account_id}/crm/campaigns{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of campaign objects

  • type Always object_list

  • api Always crm

  • Parameters
  • page_size
    number (optional) Default: 100 

    Number of objects in each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "count": 1,
      "page": 1,
      "next_page": null,
      "objects": [
        {
          "id": "Feu0c3LEe8G0yzYt4n4EiOiQWKSN77D6XZS9wOYbAHDo=",
          "created": "2018-11-17T13:30:18Z",
          "modified": "2018-11-17T13:30:18Z",
          "type": "campaign",
          "api": "crm",
          "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
          "parent": "FMQTADT0E6ehHME207tURBF5jv3_Brz740FboFJYRGAU=",
          "name": "Marketing Services",
          "campaign_type": "Referral",
          "start": "2015-11-01",
          "end": "2016-11-01",
          "status": "Planned",
          "expected_revenue": 100000,
          "actual_cost": null,
          "budgeted_cost": 1000,
          "description": "Revamp marketing partnerships",
          "href": "https://api.kloudless.com/v1/accounts/123/crm/campaigns/Feu0c3LEe8G0yzYt4n4EiOiQWKSN77D6XZS9wOYbAHDo="
        }
      ],
      "type": "object_list",
      "api": "crm"
    }

Create a Campaign 

create a campaignPOST /accounts/{account_id}/crm/campaigns

To create a campaign, perform a POST request with a JSON object of the following parameters:

  • name: Name of campaign (required)

  • owner: Identifier of the user that owns this campaign

  • parent: Identifier of the parent object

  • campaign_type: Type of campaign

  • start: Start date of campaign

  • end: End date of campaign

  • status: Status of campaign

  • expected_revenue: Expected revenue

  • actual_cost: Actual cost of campaign

  • budgeted_cost: Budgeted cost of campaign

  • description: Additional details about the Campaign

  • raw: Raw attribute names and values that will be propagated during request

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/crm/campaigns' \
    -XPOST -d '{
        "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
        "campaign_type": "Referral",
        "name": "Marketing Services",
        "parent": "FMQTADT0E6ehHME207tURBF5jv3_Brz740FboFJYRGAU=",
        "start": "2015-11-01T23:12:69.864353Z",
        "end": "2016-11-01T23:12:69.132442Z",
        "status": "Planned",
        "expected_revenue": 100000,
        "budgeted_cost": 1000,
        "description": "Revamp marketing partnerships",
        "raw": {
            "object":{
                "ExpectedResponse": "40%"
            }
        }
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "campaign_type": "Referral",
      "name": "Marketing Services",
      "parent": "FMQTADT0E6ehHME207tURBF5jv3_Brz740FboFJYRGAU=",
      "start": "2015-11-01T23:12:69.864353Z",
      "end": "2016-11-01T23:12:69.132442Z",
      "status": "Planned",
      "expected_revenue": 100000,
      "budgeted_cost": 1000,
      "description": "Revamp marketing partnerships",
      "raw": {
        "object": {
          "ExpectedResponse": "40%"
        }
      }
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "Feu0c3LEe8G0yzYt4n4EiOiQWKSN77D6XZS9wOYbAHDo=",
      "created": "2018-11-17T13:30:18Z",
      "modified": "2018-11-17T13:30:18Z",
      "type": "campaign",
      "api": "crm",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "parent": "FMQTADT0E6ehHME207tURBF5jv3_Brz740FboFJYRGAU=",
      "name": "Marketing Services",
      "campaign_type": "Referral",
      "start": "2015-11-01",
      "end": "2016-11-01",
      "status": "Planned",
      "expected_revenue": 100000,
      "actual_cost": null,
      "budgeted_cost": 1000,
      "description": "Revamp marketing partnerships",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/campaigns/Feu0c3LEe8G0yzYt4n4EiOiQWKSN77D6XZS9wOYbAHDo="
    }

Retrieve a Campaign 

retrieve a campaignGET /accounts/{account_id}/crm/campaigns/{campaign_id}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "Feu0c3LEe8G0yzYt4n4EiOiQWKSN77D6XZS9wOYbAHDo=",
      "created": "2018-11-17T13:30:18Z",
      "modified": "2018-11-17T13:30:18Z",
      "type": "campaign",
      "api": "crm",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "parent": "FMQTADT0E6ehHME207tURBF5jv3_Brz740FboFJYRGAU=",
      "name": "Marketing Services",
      "campaign_type": "Referral",
      "start": "2015-11-01",
      "end": "2016-11-01",
      "status": "Planned",
      "expected_revenue": 100000,
      "actual_cost": null,
      "budgeted_cost": 1000,
      "description": "Revamp marketing partnerships",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/campaigns/Feu0c3LEe8G0yzYt4n4EiOiQWKSN77D6XZS9wOYbAHDo="
    }

Update a Campaign 

update a campaignPATCH /accounts/{account_id}/crm/campaigns/{campaign_id}

To update a campaign, create a JSON object with any of the following properties:

  • owner

  • campaign_type

  • name

  • parent

  • start

  • end

  • status

  • expected_revenue

  • actual_cost

  • budgeted_cost

  • description

  • raw

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "status": "Planned"
    }' \
    'https://api.kloudless.com/v1/accounts/15/crm/campaigns/Feu0c3LEe8G0yzYt4n4EiOiQWKSN77D6XZS9wOYbAHDo='
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "status": "Planned"
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "Feu0c3LEe8G0yzYt4n4EiOiQWKSN77D6XZS9wOYbAHDo=",
      "created": "2018-11-17T13:30:18Z",
      "modified": "2018-11-17T13:30:18Z",
      "type": "campaign",
      "api": "crm",
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "parent": "FMQTADT0E6ehHME207tURBF5jv3_Brz740FboFJYRGAU=",
      "name": "Marketing Services",
      "campaign_type": "Referral",
      "start": "2015-11-01",
      "end": "2016-11-01",
      "status": "Planned",
      "expected_revenue": 100000,
      "actual_cost": null,
      "budgeted_cost": 1000,
      "description": "Revamp marketing partnerships",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/campaigns/Feu0c3LEe8G0yzYt4n4EiOiQWKSN77D6XZS9wOYbAHDo="
    }

Delete a Campaign 

delete a campaignDELETE /accounts/{account_id}/crm/campaigns/{campaign_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/34/crm/campaigns/Feu0c3LEe8G0yzYt4n4EiOiQWKSN77D6XZS9wOYbAHDo=
  • Response  204

CRM Tasks 

A task represents a business activity like a todo item.

  • id Unique identifier for this task

  • account Identifier of the associated account

  • owner Identifier of the user that owns this task

  • status Status of task

  • priority Priority of task

  • subject Subject of task

  • created ISO 8601 timestamp indicating when the task object was created.

  • modified ISO 8601 timestamp indicating when the task object was modified.

  • description Additional details about the Task

  • type Type of object. Always task

  • raw Underlying object retrieved from the service

  • api Always crm.

  • href The absolute URL to get the object’s metadata.

List Tasks 

list taskGET /accounts/{account_id}/crm/tasks{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of task objects

  • type Always object_list

  • api Always crm

  • Parameters
  • page_size
    number (optional) Default: 100 

    Number of objects in each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "count": 1,
      "page": 1,
      "next_page": null,
      "objects": [
        {
          "id": "FHmAiEj2nigWSUY38iXaadEOCthkbYcfkrNf1ueMX-Pk=",
          "created": "2018-11-17T13:47:52Z",
          "modified": "2018-11-17T13:47:52Z",
          "type": "task",
          "api": "crm",
          "account": null,
          "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
          "status": "Completed",
          "priority": "Low",
          "subject": "finish marketing report for 2015-06-01",
          "description": "Bi-weekly marketing report",
          "href": "https://api.kloudless.com/v1/accounts/123/crm/tasks/FHmAiEj2nigWSUY38iXaadEOCthkbYcfkrNf1ueMX-Pk="
        }
      ],
      "type": "object_list",
      "api": "crm"
    }

Create a Task 

create a taskPOST /accounts/{account_id}/crm/tasks

To create a task, perform a POST request with a JSON object of the following parameters:

  • status: Status of task (required)

  • priority: Priority of task (required)

  • account: Identifier of the associated account

  • owner: Identifier of the user that owns this task

  • subject: Actual subject of task

  • description: Additional details about the Task

  • raw: Raw attribute names and values that will be propagated during request

Here is an example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/crm/tasks' \
    -XPOST -d '{
        "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
        "status": "Completed",
        "priority": "low",
        "subject": "finish marketing report for 2015-06-01",
        "description": "Bi-weekly marketing report",
        "raw": {
            "object": {
                "Type": 3
            }
        }
    }'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "status": "Completed",
      "priority": "low",
      "subject": "finish marketing report for 2015-06-01",
      "description": "Bi-weekly marketing report",
      "raw": {
        "object": {
          "Type": 3
        }
      }
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "FHmAiEj2nigWSUY38iXaadEOCthkbYcfkrNf1ueMX-Pk=",
      "created": "2018-11-17T13:47:52Z",
      "modified": "2018-11-17T13:47:52Z",
      "type": "task",
      "api": "crm",
      "account": null,
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "status": "Completed",
      "priority": "Low",
      "subject": "finish marketing report for 2015-06-01",
      "description": "Bi-weekly marketing report",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/tasks/FHmAiEj2nigWSUY38iXaadEOCthkbYcfkrNf1ueMX-Pk="
    }

Retrieve a Task 

retrieve a taskGET /accounts/{account_id}/crm/tasks/{task_id}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "FHmAiEj2nigWSUY38iXaadEOCthkbYcfkrNf1ueMX-Pk=",
      "created": "2018-11-17T13:47:52Z",
      "modified": "2018-11-17T13:47:52Z",
      "type": "task",
      "api": "crm",
      "account": null,
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "status": "Completed",
      "priority": "Low",
      "subject": "finish marketing report for 2015-06-01",
      "description": "Bi-weekly marketing report",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/tasks/FHmAiEj2nigWSUY38iXaadEOCthkbYcfkrNf1ueMX-Pk="
    }

Update a Task 

update a taskPATCH /accounts/{account_id}/crm/tasks/{task_id}

To update a task, create a JSON object with any of the following properties:

  • account

  • owner

  • status

  • priority

  • subject

  • description

  • raw

The new object will be returned on success.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "status": "Completed"
    }' \
    'https://api.kloudless.com/v1/accounts/15/crm/tasks/FHmAiEj2nigWSUY38iXaadEOCthkbYcfkrNf1ueMX-Pk='
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "status": "Completed"
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "id": "FHmAiEj2nigWSUY38iXaadEOCthkbYcfkrNf1ueMX-Pk=",
      "created": "2018-11-17T13:47:52Z",
      "modified": "2018-11-17T13:47:52Z",
      "type": "task",
      "api": "crm",
      "account": null,
      "owner": "uMDA1N0YwMDAwMDQxQXpnUUFF",
      "status": "Completed",
      "priority": "Low",
      "subject": "finish marketing report for 2015-06-01",
      "description": "Bi-weekly marketing report",
      "href": "https://api.kloudless.com/v1/accounts/123/crm/tasks/FHmAiEj2nigWSUY38iXaadEOCthkbYcfkrNf1ueMX-Pk="
    }

Delete a Task 

delete a campaignDELETE /accounts/{account_id}/crm/tasks/{task_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/34/crm/tasks/FHmAiEj2nigWSUY38iXaadEOCthkbYcfkrNf1ueMX-Pk=
  • Response  204

Any Object 

This Generic Object API enables CRUD operations on any standard or custom object available in the upstream service, regardless of whether Kloudless unifies that object’s type.

First, use the Schema API endpoints to determine which object types exist in the upstream service. These “raw” object types can then be used with the API endpoints below to list, create, retrieve, update, or delete objects of that type.

Kloudless does not unify any attributes, other than the ID, for these “raw” upstream objects. Each object therefore has the following attributes:

  • id The ID of the object. Used to reference the object during create, update, or delete operations using the endpoints below.

  • raw Underlying object retrieved from the upstream service.

  • api Always object.

  • type Always object.

Note: Existing developers using the Generic Objects API endpoints defined within the /crm/ namespace can check the migration guide for more information on switching to the /object/ namespace.

List Raw Objects 

list raw objectsGET /accounts/{account_id}/object/raw/{service_object_name}{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of objects

  • type Always object_list

  • api Always object
  • Parameters
  • service_object_name
    string (required) 

    The raw name of the object in the upstream service. URL-encode the service_object_name to ensure it can be transmitted correctly via the URL.

    page_size
    number (optional) Default: 100 

    Number of objects in each page. For some services, the page_size is only treated as advisory and not strictly adhered to. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "count": 100,
      "page": 1,
      "next_page": null,
      "type": "object_list",
      "api": "object",
      "objects": [
        {
          "api": "object",
          "type": "object",
          "id": "object_MDAxMngwMDAwMDY4YlB3QUFJ",
          "raw": {
            "object": {},
            "type": "Account",
            "id": "0012x0000068bPwAAI"
          }
        }
      ]
    }

Create a Raw Object 

create a raw objectPOST /accounts/{account_id}/object/raw/{service_object_name}

Here is an example request to create a Salesforce Asset , which has the raw object type Asset:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/object/raw/Asset' \
    -XPOST -d '{
        "AccountId": "0017F00001GFkTxQAL",
        "Name": "Car",
        "Quantity": 50,
        "Status": "Shipped"
    }'

The attributes, such as AccountId, are directly transmitted to the upstream Salesforce API endpoint.

  • Parameters
  • service_object_name
    string (required) 

    The raw name of the object in the upstream service. URL-encode the service_object_name to ensure it can be transmitted correctly via the URL.

  • RequestToggle
  • Headers

    Content-Type: application/json
    Authorization: Bearer [TOKEN]

    Body

    {}
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "api": "object",
      "type": "object",
      "id": "object_MDAxMngwMDAwMDY4YlB3QUFJ",
      "raw": {
        "object": {},
        "type": "Account",
        "id": "0012x0000068bPwAAI"
      }
    }

Retrieve a Raw Object 

retrieve a raw objectGET /accounts/{account_id}/object/raw/{service_object_name}/{object_id}
  • Parameters
  • service_object_name
    string (required) 

    The raw name of the object in the upstream service. URL-encode the service_object_name to ensure it can be transmitted correctly via the URL.

    object_id
    string (required) 

    The object’s ID (encoded by Kloudless). Every object includes an ID that can be used to reference it. This ID can be located by listing all objects of this type, for example, to retrieve the Unified API response data returned for an object of this type.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "api": "object",
      "type": "object",
      "id": "object_MDAxMngwMDAwMDY4YlB3QUFJ",
      "raw": {
        "object": {},
        "type": "Account",
        "id": "0012x0000068bPwAAI"
      }
    }

Update a Raw Object 

update a raw objectPATCH /accounts/{account_id}/object/raw/{service_object_name}/{object_id}
  • Parameters
  • service_object_name
    string (required) 

    The raw name of the object in the upstream service. URL-encode the service_object_name to ensure it can be transmitted correctly via the URL.

    object_id
    string (required) 

    The object’s ID (encoded by Kloudless). Every object includes an ID that can be used to reference it. This ID can be located by listing all objects of this type, for example, to retrieve the Unified API response data returned for an object of this type.

  • RequestToggle
  • Headers

    Content-Type: application/json
    Authorization: Bearer [TOKEN]

    Body

    {}
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "api": "object",
      "type": "object",
      "id": "object_MDAxMngwMDAwMDY4YlB3QUFJ",
      "raw": {
        "object": {},
        "type": "Account",
        "id": "0012x0000068bPwAAI"
      }
    }

Delete a Raw Object 

delete a raw objectDELETE /accounts/{account_id}/object/raw/{service_object_name}/{object_id}
  • Parameters
  • service_object_name
    string (required) 

    The raw name of the object in the upstream service. URL-encode the service_object_name to ensure it can be transmitted correctly via the URL.

    object_id
    string (required) 

    The object’s ID (encoded by Kloudless). Every object includes an ID that can be used to reference it. This ID can be located by listing all objects of this type, for example, to retrieve the Unified API response data returned for an object of this type.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
  • Response  204

Schema 

The Schema endpoints provide a list of all raw objects in the upstream service as well as information on all raw fields in each object.

Each Schema object also includes information on the default Kloudless Unified object type and fields that the raw object’s type or fields are mapped to, if any. Custom mappings created via the Transform API endpoints will not be included, however, and should instead be retrieved via the Transform API endpoints.

Use the Generic Object API endpoints above to perform CRUD operations for objects corresponding to each raw type returned.

The following services are currently supported:

  • salesforce

  • dynamics

  • hubspot

  • oracle

List Schemas 

list schemasGET /accounts/{account_id}/object/schemas{?page_size,page}

Returns information on all known objects within the upstream service. The raw response from the service provider is included and may also contain all field information, such as field name and data type.

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of objects

  • type Always object_list

  • api Always object

Each object in the objects list has the following properties:

  • service_object_name: The name of the object in the upstream service. This can be used as the raw object type in other API endpoints such as when creating any object, or via the Pass-through API.

  • kloudless_object_name: The name of the Kloudless Unified API object that this object type is mapped to by default. May be null if Kloudless does not map an object to a unified object by default. Custom-defined mappings (Transforms) are not included.

  • raw The original information from the upstream service’s response.

  • Parameters
  • page_size
    number (optional) Default: 100 

    Number of objects in each page. For some services, the page_size is only treated as advisory and not strictly adhered to. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "count": 100,
      "page": 1,
      "next_page": null,
      "type": "object_list",
      "api": "object",
      "objects": [
        {
          "api": "object",
          "type": "object_type_map",
          "kloudless_object_name": "account",
          "service_object_name": "Account",
          "raw": {
            "object": {},
            "type": "Account"
          }
        }
      ]
    }

Retrieve a Schema 

retrieve a schemaGET /accounts/{account_id}/object/schemas/{service_object_name}

Returns information on all fields present in objects with the raw object type service_object_name.

The response contains the following information:

  • service_object_name: The name of the object in the upstream service. This can be used as the raw object type in other API endpoints such as when creating any object, or via the Pass-through API.

  • kloudless_object_name: The name of the Kloudless Unified API object that this object type is mapped to by default. May be null if Kloudless does not map an object to a unified object by default. Custom-defined mappings (Transforms) are not included.

  • fields: A list of objects, each of which includes the following keys:

    • service_field_name: The raw name of the field in the upstream service. This can be sent in raw data in requests to the Unified API in order to modify its value for the corresponding object. May be null if a Kloudless Unified field has no appropriate default mapping to a field in the upstream service.
    • kloudless_field_name: The name of the field in the Kloudless Unified API. Only present for object types that are present in the Unified API in the first place. May be null if Kloudless does not map a field to a unified field for this specific object type, even if the raw object type itself is mapped to a unified object type.
    • raw: The original field data may be included on a per-field basis if available.
  • Parameters
  • service_object_name
    string (required) 

    The raw name of the object in the upstream service. URL-encode the service_object_name to ensure it can be transmitted correctly via the URL.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "api": "object",
      "type": "object_type_map",
      "kloudless_object_name": "account",
      "service_object_name": "Account",
      "raw": {
        "object": {},
        "type": "Account"
      },
      "fields": [
        {
          "service_field_name": "Rating",
          "kloudless_field_name": "rating",
          "raw": {
            "object": {}
          }
        }
      ]
    }

Activity Monitoring 

Track changes to objects via the Activity API and webhooks.

Activity API required: These endpoints require your Kloudless subscription to include access to the Activity API.


Users and Groups 

The Team API provides information on users and groups.


CRM Search 

Search for CRM contentGET /accounts/{account_id,account_id,...}/crm/search{?q,lang,page_size,page}

The CRM Search endpoint allows your application to perform searches for both standard Kloudless object types as well as using service-specific query languages.

The following services are currently supported:

  • salesforce

  • dynamics

  • oracle

Check out the Parameters section below for more information on the required parameters.

The response contains the following information:

  • count Number of file objects in search results.

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of file objects in search results, in decreasing order of relevancy.

  • errors Contains account IDs mapped to error responses for any accounts that failed the API request. Only present when performing multi-account searches (see below).

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/123/crm/search?q=hello+world'

This endpoint supports comma-separated Account IDs. Resources under multiple accounts can be searched by separating the account IDs with commas:

curl -H 'Authorization: Bearer [TOKEN1],[TOKEN2],[TOKEN3]' \
    'https://api.kloudless.com/v1/accounts/123,456,789/crm/search?q=eliot+sun'

Search Query Languages

More information on each of the supported values for the lang parameter is provided below.

Keyword Search (lang=keyword)

Kloudless attempts to find matching objects of the types supported by the unified Kloudless API using the best mechanism available. This option is usually less efficient than a service-specific query language as multiple object types must be checked.

Supported by:

  • dynamics

  • salesforce (uses SOSL string search)

Default lang for:

  • dynamics

Salesforce Object Query Language (lang=SOQL)

You can find Salesforce’s SOQL documentation here.

Supported by:

  • salesforce

Default lang for:

  • salesforce

Salesforce Object Search Language (lang=SOSL)

You can find Salesforce’s SOSL documentation here.

Supported by:

  • salesforce

Default lang for:

  • None

Dynamics Query Language (lang=DQL)

Kloudless has created a query language to convert a query statement into the OData protocol used by Dynamics to search for specific fields. Keywords are case-sensitive, and logical operators (AND, OR) are only supported in the WHERE clause.

Supported by:

  • dynamics

Default lang for:

  • None

Example queries and a list of supported keywords are below.

SELECT accountid, name, numberofemployees FROM account WHERE name LIKE '%kloud%' ORDER BY name ASC
SELECT leadid, fullname, emailaddress1, statuscode FROM lead WHERE fullname LIKE '%kloud%' AND emailaddress1 != '' ORDER BY fullname ASC
SELECT opportunityid, name, stepname, parentaccountid.accountid FROM opportunity WHERE name LIKE '%kloud%' ORDER BY name ASC
  • SELECT: Required keyword to begin the query ($select)

    • Use with <property names>: A comma delimited list of properties that will be returned in the response
    • Note: For single-valued and collection-valued navigation properties, suffix the property name with a . along with any additional property names of the related entity. EX: parentaccountid.accountid Equivalent OData parameter: $select
  • FROM: Required keyword to denote which entity to query

    • Use with <entity name>: The case-sensitive name of an entity to query
  • WHERE: Optional keyword to filter properties based on values ($filter)

    • <property name> LIKE '%keyword%': filter property to containkeyword`
      • EX: WHERE name LIKE '%kloud%'
    • <property name><operator><value>: filter property on value with operator
      • EX: WHERE name='kloudless'
  • ORDER BY: Optional keyword to order results ($orderby)

    • <property name> <ordering>: Either ASC or DESC to sort results
      • EX: ORDER BY fullname ASC

Kloudless Query Language (lang=KQL)

Kloudless now provides a new search language, KQL, to give a unified experience for querying data from CRM services. It uses a subset of SQL-92. Keywords and object types are case-sensitive and varies depending on upstream services. Logical operators (AND, OR) are only supported in the WHERE clause.

Supported by:

  • dynamics

  • salesforce

  • sugarcrm

Example queries and a list of supported keywords are below.

SELECT id, name, website FROM Accounts WHERE name LIKE 'Jim%' ORDER BY name DESC LIMIT 100 OFFSET 200
SELECT id, name, email, status FROM Leads WHERE name LIKE '%kloudless%' AND email != '' ORDER BY name ASC
  • SELECT: Required keyword to begin the query.

    • Use with <property names>: A comma delimited list of properties that will be returned in the response. The property names must be aligned with upstream services. Unified property names are currently not supported.
    • Note: Aliases such as SELECT _something_ AS another are not part of KQL and will be ignored if presented. Selecting literal values such as SELECT 1, 'single-quoted' will be treated as general property names.
    • Note: Selecting specific field names are encouraged instead of SELECT *. Some upstream services, such as salesforce, do not support wildcard in field selection.
    • Note: Functions are not supported. For example, SELECT COUNT(*) FROM Leads is not available.
  • FROM: Required keyword to denote which object type to query.

    • Use with <object type>: The case-sensitive name of an object type to query.
    • Note: Only one type is allowed each query. That means any forms of JOIN are also not supported. And similar to SELECT, aliases will be ignored.
    • Note: Object type names could vary accross different upstream services. For example, SugarCRM accepts Accounts while Salesforce accepts Account.
  • WHERE: Optional keyword to filter properties based on values.

    • <property name> LIKE '%keyword%': filter property to contain keyword. Three formats of wildcards are supported: '%keyword', 'keyword%', and '%keyword%'. Mixed formats like '%keyword%more' and the single character wildcard, _, are not supported.
      • EX: `WHERE name LIKE ‘%kloud%’
      • EX: `WHERE name LIKE ‘kloud%’
      • EX: `WHERE name LIKE ‘%kloudless’
    • <property name> <operator> <value>: filter property on value with operator. Operators: =, <, >, <=, >=, !=.
      • EX: WHERE name = 'kloudless'
    • <filter expression> AND/OR <filter expression>: Combine multiple filter expressions.
      • EX: WHERE name = 'kloudless' AND email LIKE '%kloudless.com'
    • <property name> IN/NOT IN (<values>): filter property on a limited list of values.
      • EX: WHERE name IN ('kloudless', 'cloudless', 'chloudless')
    • <property name> IS NULL/IS NOT NULL: filter property on null values.
      • EX: WHERE website IS NOT NULL
    • Datetime values: Please use ISO-8601 format with single-quote.
      • EX: WHERE created_at >= '2018-02-23T03:05:45+00:00'
    • Note: Arithmetic (WHERE 100 > amount/10) and functions are not supported.
    • Note: sugarcrm has limited support for NOT: NOT LIKE and NOT (<filters>) are not supported, while IS NOT NULL and NOT IN are.
  • ORDER BY: Optional keyword to sort results.

    • <property name> <ordering>: Either ASC or DESC to sort results. Defaults to ASC if omitted. Supports comma separated multiple ordering.
      • EX: ORDER BY name ASC, amount DESC
  • LIMIT/OFFSET: Optional keywords for pagination.

    • LIMIT <limit number>: Limit the number of rows returned.
    • OFFSET <offset number>: The row offset into the result set returned by the query.
    • Note: Using KQL, the page_size and page from request parameters will be ignored. Use LIMIT and OFFSET to paginate results.
      • EX: LIMIT 100
      • EX: LIMIT 100 OFFSET 200
  • Parameters
  • q
    string (required) 

    The terms to search for.

    lang
    string (required) 

    The query language used to search. Refer to the Search Query Languages section above for more information.

    Choices: keyword soql dql kql

    page_size
    number (optional) Default: 30 

    Number of objects on each page. For some services, the page_size isn’t respected. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "count": 2,
      "next_page": null,
      "api": "crm",
      "objects": [
        {
          "type": "object",
          "raw": {
            "object": {
              "attributes": {
                "url": "/services/data/v37.0/sobjects/Asset/02i7F000009HtYeQAK",
                "type": "Asset"
              },
              "Id": "02i7F000009HtYeQAK"
            },
            "type": "asset",
            "id": "02i7F000009HtYeQAK"
          },
          "api": "crm"
        },
        {
          "id": "FCmbbsCTdOD_vOzcZTTTViotQ-lb0AivJvLUslhqOve8=",
          "type": "contact",
          "raw": {
            "object": {
              "attributes": {
                "url": "/services/data/v37.0/sobjects/Contact/0037F0000151Y3zQAE",
                "type": "Contact"
              },
              "Id": "0037F0000151Y3zQAE"
            },
            "type": "contact",
            "id": "0037F0000151Y3zQAE"
          },
          "api": "crm"
        }
      ],
      "type": "object_list",
      "page": 1
    }

Batch Requests 

Batch Requests 

Perform a batch request for CRM contentPOST /accounts/{account_id}/crm/batch

Allows you to perform a series of API requests through a single batch request for all CRM content pertaining to leads, opportunities, campaigns, contacts, etc. The batch endpoint accepts a JSON object with the following format:

  • requests: an array of objects with the required fields:
    • id - A unique identifier for the request
    • headers - Optional headers for the request (coming soon)
    • method - The http method of the request (required)
    • url_data - A JSON object of data to construct the url of the request (required)
      • for a custom object:
        • raw_id - The custom object id
        • raw_type - The custom object type (required)
      • for a kloudless unified object:
        • id - The object id
        • type - The object type (required)
      • params - A JSON object of any query params to be appended to the url
    • data - The data of the request (binary data is currently unsupported)

The response contains the following information:

  • responses an array of objects corresponding to each request with the following format:

    • objects If a collection, will return objects (if available)
      • raw any raw response for each object
    • object If a resource, will return the object (if available)
      • raw any raw response for the object
  • errors Any errors encountered will be returned (if available)

The following services are currently supported:

  • salesforce

  • dynamics

  • oracle

Service-specific notes:

  • dynamics only allows up to two concurrent batch requests to a tenant. It is therefore highly likely to encounter rate-limiting if batch requests are made to dynamics accounts.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPOST -d '{
        "requests": [{
            "id": "92fae13",
            "method": "GET",
            "url_data": {
                "raw_type": "Account"
            }
        },{
            "id": "c23a87f",
            "method": "GET",
            "url_data": {
                "raw_type": "Asset",
                "id": "02i7F000009HtYeQAK",
                "params": {
                    "fields": "Status"
                }
            }
        }]
    }' \
    'https://api.kloudless.com/v1/accounts/15/crm/batch'
  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
    Content-Type: application/json

    Body

    {
      "requests": [
        {
          "id": "92fae13",
          "method": "GET",
          "url_data": {
            "raw_type": "Account"
          }
        },
        {
          "id": "c23a87f",
          "method": "GET",
          "url_data": {
            "raw_type": "Asset",
            "id": "02i7F000009HtYeQAK",
            "params": {
              "fields": "Status"
            }
          }
        }
      ]
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "responses": [
        {
          "objects": [
            {
              "type": "account",
              "raw": {
                "object": {
                  "attributes": {
                    "url": "/services/data/v37.0/sobjects/Account/0017F00001GFkMZQA1",
                    "type": "Account"
                  },
                  "Id": "0017F00001GFkMZQA1",
                  "Name": "Simplynk, Inc."
                },
                "type": "Account",
                "id": "0017F00001GFkMZQA1"
              },
              "api": "crm"
            },
            {
              "type": "account",
              "raw": {
                "object": {
                  "attributes": {
                    "url": "/services/data/v37.0/sobjects/Account/0017F00001MpkM2QAJ",
                    "type": "Account"
                  },
                  "Id": "0017F00001MpkM2QAJ",
                  "Name": "Kloudless, Inc."
                },
                "type": "Account",
                "id": "0017F00001MpkM2QAJ"
              },
              "api": "crm"
            },
          ]
        },
        {
          "object": {
            "type": "object",
            "raw": {
              "object": {
                "Status": "Shipped",
                "attributes": {
                  "url": "/services/data/v37.0/sobjects/Asset/02i7F000009HtYeQAK",
                  "type": "Asset"
                },
                "Id": "02i7F000009HtYeQAK"
              },
              "type": "Asset",
              "id": "02i7F000009HtYeQAK"
            },
            "api": "crm"
          }
        }
      ]
    }

Custom Mappings 

The Kloudless API provides a set of “unified” data models that map to objects in each connector supported by the Kloudless API. Each unified data model’s fields map to fields in the corresponding upstream object in each connector.

Applications that wish to extend these unified data models, or define new unified data models of their own, can use the Transforms API endpoints below to define custom mappings.

A Transform represents a mapping between a “raw” upstream object type in a connected account and a “unified” object type defined in the Kloudless API abstraction layer. Kloudless will use the Transform to convert data between the raw object and the unified object in all API requests that reference the unified object type.

Each Transform has the following attributes:

  • kloudless_object_name The name of the object in the Kloudless Unified API. May be any existing default Unified API object type, or an entirely new object type.

  • service_object_name The raw name of the object in the upstream service. List all object names via the Schemas API endpoints to find available object names and fields.

  • bidirectional A 1-1 mapping of fields present in the unified object to the fields present in the raw object in this account. See the Bidirectional field mapping section below for details.

  • created_at ISO 8601 timestamp indicating when the Transform was created.

  • updated_at ISO 8601 timestamp indicating when the Transform was last updated.

  • api Always object.

  • type Type of object. Always transform.

Once a Transform is defined, an application can perform CRUD operations to objects of that type using the “Any Unified Object” API endpoints.

Bidirectional field mapping

A Transform’s bidirectional attribute represents the bidirectional mapping of fields between the unified object and the raw object. Each key is the name of a field in the unified object, and its value is the corresponding name of a field in the upstream object.

Here is an example that maps the unified field, is_deleted, to the raw field, IsDeleted:

{"is_deleted": "IsDeleted"}

Nested fields can also be defined by using periods (.) to separate each object level. For example, consider the raw object below:

{"Profile": {"Rating": 123}}

The following bidirectional mapping will assign this example object’s profile rating, 123, to a rating field in the unified object mapped to in Kloudless:

{"rating": "Profile.Rating"}

The nested field syntax works for both unified field names as well as raw field names.

If the field name has existing . characters, escape them with a back-slash (\). For example, accessing name in the example object below requires the field mapping to specify 1\.0.name, thus escaping the existing . within 1.0:

{"1.0": {"name": "First version."}}

List Transforms 

list TransformsGET /accounts/{account_id}/object/transforms{?page_size,page}

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of objects

  • type Always object_list

  • api Always object
  • Parameters
  • page_size
    number (optional) Default: 100 

    Number of objects in each page. For some services, the page_size is only treated as advisory and not strictly adhered to. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "count": 100,
      "page": 1,
      "next_page": null,
      "type": "object_list",
      "api": "object",
      "objects": [
        {
          "kloudless_object_name": "account",
          "service_object_name": "Account",
          "bidirectional": {},
          "api": "object",
          "type": "transform",
          "created_at": "2020-07-01T07:08:40.577615Z",
          "updated_at": "2020-07-01T07:08:40.577615Z"
        }
      ]
    }

Create a Transform 

create a transformPOST /accounts/{account_id}/object/transforms

To create a transform, perform a POST request with a JSON object of the following parameters:

  • kloudless_object_name: The unified object name. Use an existing Kloudless-defined unified object type to override any of the default mappings for that object type, or use a new unique name to extend the Unified API with a new unified object type.

  • service_object_name: The raw object name. Specify the object in the upstream service to map to. All available object types can be listed using the Schema API endpoints.

  • bidirectional: An object representing 1-1 field mappings.

Here is an example that creates a Transform for the unified object, account. The Transform represents a mapping that maps the unified field, is_deleted, to the raw field isDeleted of the raw object, Account.

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/123/object/transforms' \
    -XPOST -d '{
        "kloudless_object_name": "account",
        "service_object_name": "Account",
        "bidirectional": {
            "is_deleted": "isDeleted"
        }
    }'

If this were a CRM account, Kloudless’ default mapping for account (which is a default Unified CRM API type) would be overridden/extended to include this new Unified API attribute. Other attribute mappings would remain unchanged.

In general, creating a Transform where the kloudless_object_name equals an existing Kloudless object type results in the new mapping merging into the existing default one, overriding any existing fields if necessary. Retrieve a Transform with the full=true query parameter to get the final combined result that represents the mapping used by Kloudless.

  • RequestToggle
  • Headers

    Content-Type: application/json
    Authorization: Bearer [TOKEN]

    Body

    {
      "kloudless_object_name": "account",
      "service_object_name": "Account",
      "bidirectional": {}
    }
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "kloudless_object_name": "account",
      "service_object_name": "Account",
      "bidirectional": {},
      "api": "object",
      "type": "transform",
      "created_at": "2020-07-01T07:08:40.577615Z",
      "updated_at": "2020-07-01T07:08:40.577615Z"
    }

Retrieve a Transform 

retrieve a transformGET /accounts/{account_id}/object/transforms/{kloudless_object_name}{?full}
  • Parameters
  • kloudless_object_name
    string (required) 

    The unified object name defined in the Transform.

    full
    boolean (optional) Default: false 

    If full=true, Kloudless will return a mapping of all unified API fields to raw fields after merging the Transform’s definition with any default mapping present. Default mappings exist when a Transform is created with a kloudless_object_name that matches any default Kloudless Unified API object type, for example.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "kloudless_object_name": "account",
      "service_object_name": "Account",
      "bidirectional": {},
      "api": "object",
      "type": "transform",
      "created_at": "2020-07-01T07:08:40.577615Z",
      "updated_at": "2020-07-01T07:08:40.577615Z"
    }

Update a Transform 

update a transformPUT /accounts/{account_id}/object/transforms/{kloudless_object_name}

The request body is the same as when creating a Transform.

Be sure to provide the complete Transform, similar to when creating the Transform, because this operation overwrites the original Transform entirely.

  • Parameters
  • kloudless_object_name
    string (required) 

    The unified object name defined in the Transform.

  • RequestToggle
  • Headers

    Content-Type: application/json
    Authorization: Bearer [TOKEN]

    Body

    {
      "kloudless_object_name": "account",
      "service_object_name": "Account",
      "bidirectional": {}
    }
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "kloudless_object_name": "account",
      "service_object_name": "Account",
      "bidirectional": {},
      "api": "object",
      "type": "transform",
      "created_at": "2020-07-01T07:08:40.577615Z",
      "updated_at": "2020-07-01T07:08:40.577615Z"
    }

Delete a Transform 

delete a transformDELETE /accounts/{account_id}/object/transforms/{kloudless_object_name}
  • Parameters
  • kloudless_object_name
    string (required) 

    The unified object name defined in the Transform.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
  • Response  204

Any Unified Object 

The Kloudless Unified API may be extended by defining custom mappings via the Transform API endpoints. Similar to the rest of the Unified API, CRUD operations can then be performed with these custom-defined object types to access or modify the corresponding upstream object.

The endpoints below may be used to perform CRUD operations given any default or custom-defined Kloudless Unified object type. However, since default Kloudless Unified API objects already possess their own CRUD API endpoints above, this API is most useful to perform CRUD operations on custom-defined Unified object types (Transforms).

Note: To instead directly perform CRUD operations given a raw upstream object type, see the Generic Object API endpoints instead.

The exact attributes present in each object depend on the Unified object type. Default Kloudless Unified API objects are documented above and custom-defined Transforms each have their own attributes as well. In either case, the following attributes are always present:

  • id The ID of the object

  • raw Underlying object retrieved from the upstream service. Set the X-Kloudless-Raw-Data request header to true to retrieve this information.

  • api Always object

  • type Always object

List Unified Objects 

list unified objectsGET /accounts/{account_id}/object/unified/{kloudless_object_name}{?page_size,page}

All Unified API object types available by default in the Kloudless API are documented in the sections above along with their Unified API endpoints.

For objects that are instead unified via a custom-defined mapping, retrieve their Transform using the query parameter full=true to obtain the full structure of the custom-defined Unified API object. This provides information on all attributes available on that object.

The response contains the following information:

  • count Number of objects on this page

  • page Page identifier

  • next_page The value to provide in the request’s page query parameter for the next page. This will be null if there are no more pages.

  • objects List of objects

  • type Always object_list

  • api Always object
  • Parameters
  • kloudless_object_name
    string (required) 

    The name of the Unified API object. Defined either by Kloudless or in a custom Transform.

    page_size
    number (optional) Default: 100 

    Number of objects in each page. For some services, the page_size is only treated as advisory and not strictly adhered to. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. Do not provide a page parameter when retrieving the first page. To retrieve pages after the first page, set page to the value of next_page found in the previous page of data retrieved.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "count": 100,
      "page": 1,
      "next_page": null,
      "type": "object_list",
      "api": "object",
      "objects": [
        {
          "api": "object",
          "type": "object",
          "id": "object_MDAxMngwMDAwMDY4YlB3QUFJ",
          "raw": {
            "object": {},
            "type": "Account",
            "id": "0012x0000068bPwAAI"
          }
        }
      ]
    }

Create a Unified Object 

create a unified objectPOST /accounts/{account_id}/object/unified/{kloudless_object_name}

All Unified API object types available by default in the Kloudless API are documented in the sections above along with their Unified API endpoints.

For objects that are instead unified via a custom-defined mapping, retrieve their Transform using the query parameter full=true to obtain the full structure of the custom-defined Unified API object. This provides information on all attributes available on that object.

  • Parameters
  • kloudless_object_name
    string (required) 

    The name of the Unified API object. Defined either by Kloudless or in a custom Transform.

  • RequestToggle
  • Headers

    Content-Type: application/json
    Authorization: Bearer [TOKEN]

    Body

    {}
  • Response  201Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "api": "object",
      "type": "object",
      "id": "object_MDAxMngwMDAwMDY4YlB3QUFJ",
      "raw": {
        "object": {},
        "type": "Account",
        "id": "0012x0000068bPwAAI"
      }
    }

Retrieve a Unified Object 

retrieve a unified objectGET /accounts/{account_id}/object/unified/{kloudless_object_name}/{object_id}

All Unified API object types available by default in the Kloudless API are documented in the sections above along with their Unified API endpoints.

For objects that are instead unified via a custom-defined mapping, retrieve their Transform using the query parameter full=true to obtain the full structure of the custom-defined Unified API object. This provides information on all attributes available on that object.

  • Parameters
  • kloudless_object_name
    string (required) 

    The name of the Unified API object. Defined either by Kloudless or in a custom Transform.

    object_id
    string (required) 

    The object’s ID (encoded by Kloudless). Every object includes an ID that can be used to reference it. This ID can be located by listing all objects of this type, for example, to retrieve the Unified API response data returned for an object of this type.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "api": "object",
      "type": "object",
      "id": "object_MDAxMngwMDAwMDY4YlB3QUFJ",
      "raw": {
        "object": {},
        "type": "Account",
        "id": "0012x0000068bPwAAI"
      }
    }

Update a Unified Object 

update a unified objectPATCH /accounts/{account_id}/object/unified/{kloudless_object_name}/{object_id}

All Unified API object types available by default in the Kloudless API are documented in the sections above along with their Unified API endpoints.

For objects that are instead unified via a custom-defined mapping, retrieve their Transform using the query parameter full=true to obtain the full structure of the custom-defined Unified API object. This provides information on all attributes available on that object.

  • Parameters
  • kloudless_object_name
    string (required) 

    The name of the Unified API object. Defined either by Kloudless or in a custom Transform.

    object_id
    string (required) 

    The object’s ID (encoded by Kloudless). Every object includes an ID that can be used to reference it. This ID can be located by listing all objects of this type, for example, to retrieve the Unified API response data returned for an object of this type.

  • RequestToggle
  • Headers

    Content-Type: application/json
    Authorization: Bearer [TOKEN]

    Body

    {}
  • Response  200Toggle
  • Headers

    Content-Type: application/json

    Body

    {
      "api": "object",
      "type": "object",
      "id": "object_MDAxMngwMDAwMDY4YlB3QUFJ",
      "raw": {
        "object": {},
        "type": "Account",
        "id": "0012x0000068bPwAAI"
      }
    }

Delete a Unified Object 

delete a unified objectDELETE /accounts/{account_id}/object/unified/{kloudless_object_name}/{object_id}
  • Parameters
  • kloudless_object_name
    string (required) 

    The name of the Unified API object. Defined either by Kloudless or in a custom Transform.

    object_id
    string (required) 

    The object’s ID (encoded by Kloudless). Every object includes an ID that can be used to reference it. This ID can be located by listing all objects of this type, for example, to retrieve the Unified API response data returned for an object of this type.

  • RequestToggle
  • Headers

    Authorization: Bearer [TOKEN]
  • Response  204