Introduction to the Accounting 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 Accounting API endpoints listed below.

Here are the supported services, listed with service identifiers:

  • Accounting Services
    • QuickBooks Online: quickbooks
    • Xero: xero (coming soon: 6 October 2020)
    • Zoho Books: zoho_books (coming soon: 6 October 2020)
    • Sage: sage (coming soon: 6 October 2020)

NOTE: The Kloudless Unified Accounting API is coming soon with support for Invoices, Payments, Contacts and more. Please use our Data Mapper instead to prompt customers to map their objects in Accounting services such as QuickBooks to data in your application.


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.


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.

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.

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": {}
          }
        }
      ]
    }

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