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 begin making 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
  • Pipedrive: pipedrive

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. Behind the scenes, the Data Mapper uses the Custom Mappings API. See our Data Mapper Guide for more information.

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 

Create an Account 

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
            }
        }
    }'

Retrieve an Account 

Update an Account 

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='

Delete an Account 

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

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 

Create a Contact 

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."
            }
        }
    }'

Retrieve a Contact 

Update a Contact 

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='

Delete a Contact 

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

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.

Connector-specific notes:

• pipedrive: Pipedrive does not support accessing Lead objects with tokens provisioned through OAuth. See the the Pipedrive release notes for further information.

List Leads 

Create a Lead 

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"
            }
        }
    }'

Retrieve a Lead 

Update a Lead 

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='

Delete a Lead 

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

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 

Create an Opportunity 

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"
            }
        }
    }'

Retrieve an Opportunity 

Update an Opportunity 

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='

Delete an Opportunity 

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

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.

• pipedrive: Pipedrive does not support Campaign objects.

List Campaigns 

Create a Campaign 

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%"
            }
        }
    }'

Retrieve a Campaign 

Update a Campaign 

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

Delete a Campaign 

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

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 

Create a Task 

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
            }
        }
    }'

Retrieve a Task 

Update a Task 

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='

Delete a Task 

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

Raw Object 

The Raw 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 Raw Object API endpoints defined within the /crm/ namespace can check the migration guide for more information on switching to the /object/ namespace.

List Raw Objects 

Create a Raw Object 

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"
    }'

Retrieve a Raw object 

Update a Raw object 

Delete a Raw Object 

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

• pipedrive

• zoho

List Schemas 

Retrieve a Schema 

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 

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

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

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 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

Batch Requests 

Batch Requests 

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'

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 Always transform.

Once a Transform is defined, an application can perform CRUD operations to objects of that custom 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 

Create a Transform 

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"
        }
    }'

Retrieve a Transform 

Update a Transform 

Delete a Transform 

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 

Create a Unified Object 

Retrieve a Unified Object 

Update a Unified Object 

Delete a Unified Object