Accounting API Docs

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

Here are the supported services, listed with service identifiers:

  • Accounting Services
    • QuickBooks Online: quickbooks
    • Xero: xero
    • Zoho Books: zoho_books
    • Sage: sage

The Accounting API has the following available object types:

  • account

  • contact

  • bill

  • invoice

  • payment

Each object type is documented below, with its standard Kloudless attributes listed. If an object type is not yet supported, please use our Data Mapper to prompt customers to map their objects, like QuickBooks’ Estimate object, to data in your application.

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.

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.

Accounts 

An Account object represents a component of a Chart of accounts and is part of a ledger. The Account object has the following metadata:

  • id Unique identifier for the account.

  • name Name of the account.

  • active Boolean. Indicates whether the account is active or not.

  • account_class The classification of an account. See Account Classes.

  • account_type A detailed account classification that specifies the use of this account. See Account Types.

  • code User-defined string to help identify the account.

  • currency A Currency object related to the account. It has the following attributes:

    • code: A three letter string representing the ISO 4217 code for the currency. For example, USD. (required)
    • name: The full name of the currency. For example, United States Dollar. (read-only)

  • balance A floating-point value that specifies the balance amount for the current account in the currency currency.

  • description Description of the account.

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

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

  • raw The raw object retrieved from the upstream service’s API.

  • type Always account.

  • api Always accounting.

Note: The balance and created fields are currently unavailable for xero.

Account Classification

Account Classes

account_class indicates the general classification of an account. The valid values for account_class are: asset, equity, expense, liability, and revenue.

Account Types

account_type describes a specific type of account_class. Each account_class can have one of the following types:

  • asset: accounts_receivable, bank, current_asset, non_current_asset, other_asset

  • equity: equity

  • expense: expense, other_expense, costs_of_sales

  • liability: accounts_payable, credit_card, current_liability, non_current_liability, other_liability

  • revenue: income, other_income

List Accounts 

list accountsGET /accounts/{account_id}/accounting/accounts/{?page,page_size,account_type}

Lists all accounts, optionally filterable by account_type.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/accounting/accounts/'

The response contains the following information, where each object is an Account:

  • count Integer. Number of objects on this page.

  • page String. 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 Array. List of objects.

  • Parameters
  • account_type
    string (optional) 

    Only accounts of this type are returned.

    page_size
    number (optional) Default: 100 

    Number of objects in each page. The page_size is treated as advisory and may not be strictly adhered to, depending on the upstream service’s capabilities. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "count": 1,
  "page": 1,
  "next_page": null,
  "objects": [
    {
      "id": "account_MTcxMDkwMzFiMGU4ODJiNg",
      "name": "example account",
      "active": true,
      "account_class": "asset",
      "account_type": "accounts_receivable",
      "code": "AR001",
      "currency": {
        "code": "USD",
        "name": "United States Dollar"
      },
      "balance": 9.99,
      "description": "my accounts receivable",
      "created": "2020-10-20T20:08:50Z",
      "modified": "2020-10-20T20:09:50Z",
      "type": "account",
      "api": "accounting"
    }
  ],
  "type": "object_list",
  "api": "accounting"
}

Retrieve an Account 

retrieve an accountGET /accounts/{account_id}/accounting/accounts/{account_id}

Retrieves metadata for an individual account when provided with its ID.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/accounting/accounts/account_MTcxMDkwMzFiMGU4ODJiNg'
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "account_MTcxMDkwMzFiMGU4ODJiNg",
  "name": "example account",
  "active": true,
  "account_class": "asset",
  "account_type": "accounts_receivable",
  "code": "AR001",
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "balance": 9.99,
  "description": "my accounts receivable",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "account",
  "api": "accounting"
}

Create an Account 

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

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

  • name (required): Name of the account.

  • account_class: The classification of the account.

  • account_type: A detailed account classification that specifies the use of this account.

  • code (required): User-defined string to help identify the account.

  • currency: A JSON object indicating the currency used for the account.

  • description: Description of the account.

  • raw: Raw attribute names and values that will be propagated during the request. Service-specific attributes can be specified here.

Example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/accounting/accounts/' \
    -XPOST -d '{
        "name": "example account",
        "account_class": "asset",
        "account_type": "accounts_receivable",
        "code": "AR001",
        "currency": {"code": "USD"},
        "description": "my accounts receivable",
        "raw": {
            "object": {
                "AccountAlias": "account-alias"
            }
        }
    }'
  • Response  201Toggle

  • Headers

    Content-Type: application/json

    Body

    {
        "id": "account_MTcxMDkwMzFiMGU4ODJiNg",
        "name": "example account",
        "active": true,
        "account_class": "asset",
        "account_type": "accounts_receivable",
        "code": "AR001",
        "currency":     {
                            "code": "USD",
                            "name": "United States Dollar"
                        },
        "balance": 9.99,
        "description": "my accounts receivable",
        "created": "2020-10-20T20:08:50Z",
        "modified": "2020-10-20T20:09:50Z",
        "type": "account",
        "api": "accounting"
    }
For `xero`, the attribute `account_type` uses a best-fit mapping. It is
higly recommended to use the `raw` attribute to properly specify what it should
be.

Update an Account 

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

To update an account, perform a PATCH request containing a JSON object with any of the following parameters:

  • name: Name of the account.

  • account_class: The classification of an account.

  • account_type: A detailed account classification that specifies the use of this account.

  • code: User-defined string to help identify the account.

  • currency: A JSON object indicating the currency for the account.

  • active: Boolean. The updated status of the account.

  • description: Description of the account.

  • raw: Raw attribute names and values that will be propagated during the request. Service-specific attributes can be specified here.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "name": "example account"
    }' \
    'https://api.kloudless.com/v1/accounts/me/accounting/accounts/account_MTcxMDkwMzFiMGU4ODJiNg'
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "account_MTcxMDkwMzFiMGU4ODJiNg",
  "name": "example account",
  "active": true,
  "account_class": "asset",
  "account_type": "accounts_receivable",
  "code": "AR001",
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "balance": 9.99,
  "description": "my accounts receivable",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "account",
  "api": "accounting"
}

Delete an Account 

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

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/me/accounting/accounts/account_MTcxMDkwMzFiMGU4ODJiNg
  • Response  204

Contacts 

A Contact object represents a person with whom you communicate in an organization. The Contact object has the following metadata:

  • id Unique identifier for the contact.

  • contact_type Type of contact. One of vendor, customer, or other.

  • name Name of the contact.

  • first_name First name of the contact.

  • middle_name Middle name of the contact.

  • last_name Last name of the contact.

  • company_name The name of the company the contact belongs to.

  • email Email of the contact.

  • phones A list of Phone objects. Phone objects have the following format:

    • phone_type Either default, mobile or fax.

    • number A string containing the phone number.

  • addresses A list of Address objects. Address objects have the following format:

    • address_type
      Type of address. One of billing, delivery, or other.

    • country
      The country.

    • city
      The city.

    • postal_code
      The postal code.

    • region
      An area, which could be the state, district, region, or county.

    • address_lines
      A list of address text strings.

  • currency A Currency object that relates to the contact. It has the following attributes:

    • code: A three letter string representing the ISO 4217 code for the currency. For example, USD. (required)
    • name: The full name of the currency. For example, United States Dollar. (read-only)

  • description Description of the contact.

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

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

  • raw The raw object retrieved from the upstream service’s API.

  • type Always contact.

  • api Always accounting.

Notes: For xero, the attribute contact_type will be set as other if the contact is both a customer and a vendor, or neither.

List Contacts 

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

Lists all contacts, optionally filterable by contact_type.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/accounting/contacts/'

The response contains the following information, where each object is a Contact:

  • count Integer. Number of objects on this page.

  • page String. 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 Array. List of objects.

  • Parameters
  • contact_type
    string (optional) 

    Only contacts of this type are returned.

    page_size
    number (optional) Default: 100 

    Number of objects in each page. The page_size is treated as advisory and may not be strictly adhered to, depending on the upstream service’s capabilities. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "count": 1,
  "page": 1,
  "next_page": null,
  "objects": [
    {
      "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
      "name": "Gary Payton",
      "contact_type": "customer",
      "first_name": "Gary",
      "middle_name": null,
      "last_name": "Payton",
      "company_name": "Seattle SuperSonics",
      "email": "gary@supersonics.com",
      "phones": [
        {
          "phone_type": "mobile",
          "number": "11111111"
        }
      ],
      "addresses": [
        {
          "address_type": "billing",
          "country": "USA",
          "city": "Seattle",
          "postal_code": "98101",
          "region": "WA",
          "address_lines": [
            "123 Some St."
          ]
        }
      ],
      "currency": {
        "code": "USD",
        "name": "United States Dollar"
      },
      "description": "he's pretty good at basketball",
      "created": "2020-10-20T20:08:50Z",
      "modified": "2020-10-20T20:09:50Z",
      "type": "contact",
      "api": "accounting"
    }
  ],
  "type": "object_list",
  "api": "accounting"
}

Retrieve a Contact 

retrieve a contactGET /accounts/{account_id}/accounting/contacts/{contact_id}

Retrieves metadata for an individual contact when provided with its ID.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/accounting/contacts/contact_MTcxMDkwMzFiMGU4ODJiNg'
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
  "name": "Gary Payton",
  "contact_type": "customer",
  "first_name": "Gary",
  "middle_name": null,
  "last_name": "Payton",
  "company_name": "Seattle SuperSonics",
  "email": "gary@supersonics.com",
  "phones": [
    {
      "phone_type": "mobile",
      "number": "11111111"
    }
  ],
  "addresses": [
    {
      "address_type": "billing",
      "country": "USA",
      "city": "Seattle",
      "postal_code": "98101",
      "region": "WA",
      "address_lines": [
        "123 Some St."
      ]
    }
  ],
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "description": "he's pretty good at basketball",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "contact",
  "api": "accounting"
}

Create a Contact 

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

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

  • name (required): Name of the contact.

  • contact_type (required): Type of the contact.

  • first_name: First name of the contact.

  • middle_name: Middle name of the contact.

  • last_name: Last name of the contact.

  • company_name: The name of the company the contact belongs to.

  • email: Email of the contact.

  • phones: A list of Phone objects.

  • addresses: A list of Address objects.

  • description: Description of the contact.

  • raw: Raw attribute names and values that will be propagated during the request. Service-specific attributes can be specified here.

Notes:

For xero, the attribute contact_type is read-only and changes based on the invoices associated with the contact.

Example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/accounting/contacts/' \
    -XPOST -d '{
        "name": "Gary Payton",
        "contact_type": "customer",
        "first_name": "Gary",
        "middle_name": null,
        "last_name": "Payton",
        "company_name": "Seattle SuperSonics",
        "email": "gary@supersonics.com",
        "phones": [{"phone_type": "mobile", "number": "11111111"}],
        "addresses": [{
            "address_type": "billing",
            "country": "USA",
            "city": "Seattle",
            "postal_code": "98101",
            "region": "WA",
            "address_lines": ["123 Some St."]
        }],
        "description": "he's pretty good at basketball"
    }'
  • Response  201Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
  "name": "Gary Payton",
  "contact_type": "customer",
  "first_name": "Gary",
  "middle_name": null,
  "last_name": "Payton",
  "company_name": "Seattle SuperSonics",
  "email": "gary@supersonics.com",
  "phones": [
    {
      "phone_type": "mobile",
      "number": "11111111"
    }
  ],
  "addresses": [
    {
      "address_type": "billing",
      "country": "USA",
      "city": "Seattle",
      "postal_code": "98101",
      "region": "WA",
      "address_lines": [
        "123 Some St."
      ]
    }
  ],
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "description": "he's pretty good at basketball",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "contact",
  "api": "accounting"
}

Update a Contact 

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

To update a contact, perform a PATCH request containing a JSON object with any of the following parameters:

  • name: Name of the contact.

  • contact_type: Type of the contact.

  • first_name: First name of the contact.

  • middle_name: Middle name of the contact.

  • last_name: Last name of the contact.

  • company_name: The name of the company the contact belongs to.

  • email: Email of the contact.

  • phones: A list of Phone objects.

  • addresses: A list of Address objects.

  • description: Description of the contact.

  • raw: Raw attribute names and values that will be propagated during the request. Service-specific attributes can be specified here.

Notes:

For xero, the attribute contact_type is read-only and changes based on the invoices associated with the contact.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "name": "Gary Payton",
        "email": "gary@supersonics.com"
    }' \
    'https://api.kloudless.com/v1/accounts/me/accounting/contacts/contact_MTcxMDkwMzFiMGU4ODJiNg'
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
  "name": "Gary Payton",
  "contact_type": "customer",
  "first_name": "Gary",
  "middle_name": null,
  "last_name": "Payton",
  "company_name": "Seattle SuperSonics",
  "email": "gary@supersonics.com",
  "phones": [
    {
      "phone_type": "mobile",
      "number": "11111111"
    }
  ],
  "addresses": [
    {
      "address_type": "billing",
      "country": "USA",
      "city": "Seattle",
      "postal_code": "98101",
      "region": "WA",
      "address_lines": [
        "123 Some St."
      ]
    }
  ],
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "description": "he's pretty good at basketball",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "contact",
  "api": "accounting"
}

Delete a Contact 

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

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/me/accounting/contacts/contact_MTcxMDkwMzFiMGU4ODJiNg
  • Response  204

Bills 

A Bill object is an AP (accounts payable) transaction representing a request-for-payment from a third party for goods/services rendered, received, or both. The Bill object has the following metadata:

  • id Unique identifier for the bill.

  • contact A Contact object related to the bill.

  • reference String. Reference number for the transaction.

  • currency A Currency object that relates to the bill. It has the following attributes:

    • code: A three letter string representing the ISO 4217 code for the currency. For example, USD. (required)
    • name: The full name of the currency. For example, United States Dollar. (read-only)

  • exchange_rate Float. Exchange rate for the currency used in the bill.

  • date ISO 8601 timestamp of the transaction (entered by the user).

  • due_date ISO 8601 timestamp indicating when the bill is due.

  • payments A list of Payment objects related to the bill.

  • sub_total Float. Total price of goods (excluding tax).

  • total_tax Float. Total amount of tax.

  • total_amount Float. Total amount (including tax).

  • amount_paid Float. Amount paid for the bill.

  • credits_applied Float. Amount of credits applied.

  • balance Float. Reflects any payments made against the transaction. A balance of 0 indicates that the bill is fully paid.

  • status The status of the bill. One of draft, open, paid, void, or other.

  • description Description of the bill.

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

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

  • raw The raw object retrieved from the upstream service’s API.

  • type Always bill.

  • api Always accounting.

Note: The balance field is currently unavailable for xero.

List Bills 

list billsGET /accounts/{account_id}/accounting/bills/{?page,page_size,contact_id,before,after,status}

Lists all bills, optionally filterable by contact_id, before, after, or status.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/accounting/bills/'

The response contains the following information, where each object is a Bill:

  • count Integer. Number of objects on this page.

  • page String. 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 Array. List of objects.

  • Parameters
  • contact_id
    string (optional) 

    Only bills related to the corresponding contact will be returned.

    before
    string (optional) 

    Only bills with a date before this ISO 8601 timestamp (exclusive) are returned. The default value is the current time.

    after
    string (optional) 

    Only bills with a date after this ISO 8601 timestamp (exclusive) are returned. The default value is the start of Unix Epoch Time (1970-01-01T00:00:00Z).

    status
    string (optional) 

    Only bills with the specified status will be returned.

    page_size
    number (optional) Default: 100 

    Number of objects in each page. The page_size is treated as advisory and may not be strictly adhered to, depending on the upstream service’s capabilities. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "count": 1,
  "page": 1,
  "next_page": null,
  "objects": [
    {
      "id": "bill_MTcxMDkwMzFiMGU4ODJiNg",
      "contact": {
        "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
        "name": "Gary Payton",
        "contact_type": "vendor",
        "first_name": "Gary",
        "middle_name": null,
        "last_name": "Payton",
        "company_name": "Seattle SuperSonics",
        "title": "Mr.",
        "email": "gary@supersonics.com",
        "phones": [
          {
            "phone_type": "mobile",
            "number": "11111111"
          }
        ],
        "addresses": [
          {
            "address_type": "billing",
            "country": "USA",
            "city": "Seattle",
            "postal_code": "98101",
            "region": "WA",
            "address_lines": [
              "123 Some St."
            ]
          }
        ],
        "currency": {
          "code": "USD",
          "name": "United States Dollar"
        },
        "description": "he's pretty good at basketball",
        "created": "2020-10-20T20:08:50Z",
        "modified": "2020-10-20T20:09:50Z",
        "type": "contact",
        "api": "accounting"
      },
      "reference": "BILL01",
      "currency": {
        "code": "USD",
        "name": "United States Dollar"
      },
      "exchange_rate": 30.1,
      "date": "2020-09-01T10:00:00Z",
      "due_date": "2020-11-01T10:00:00Z",
      "payments": [],
      "sub_total": null,
      "total_tax": null,
      "total_amount": null,
      "amound_paid": null,
      "credits_applied": null,
      "balance": null,
      "status": "open",
      "description": "an example of a bill",
      "created": "2020-10-20T20:08:50Z",
      "modified": "2020-10-20T20:09:50Z",
      "type": "bill",
      "api": "accounting"
    }
  ],
  "type": "object_list",
  "api": "accounting"
}

Retrieve a Bill 

retrieve a billGET /accounts/{account_id}/accounting/bills/{bill_id}

Retrieves metadata for an individual bill when provided with its ID.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/accounting/bills/bill_MTcxMDkwMzFiMGU4ODJiNg'
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "bill_MTcxMDkwMzFiMGU4ODJiNg",
  "contact": {
    "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
    "name": "Gary Payton",
    "contact_type": "vendor",
    "first_name": "Gary",
    "middle_name": null,
    "last_name": "Payton",
    "company_name": "Seattle SuperSonics",
    "title": "Mr.",
    "email": "gary@supersonics.com",
    "phones": [
      {
        "phone_type": "mobile",
        "number": "11111111"
      }
    ],
    "addresses": [
      {
        "address_type": "billing",
        "country": "USA",
        "city": "Seattle",
        "postal_code": "98101",
        "region": "WA",
        "address_lines": [
          "123 Some St."
        ]
      }
    ],
    "currency": {
      "code": "USD",
      "name": "United States Dollar"
    },
    "description": "he's pretty good at basketball",
    "created": "2020-10-20T20:08:50Z",
    "modified": "2020-10-20T20:09:50Z",
    "type": "contact",
    "api": "accounting"
  },
  "reference": "BILL01",
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "exchange_rate": 30.1,
  "date": "2020-09-01T10:00:00Z",
  "due_date": "2020-11-01T10:00:00Z",
  "payments": [],
  "sub_total": null,
  "total_tax": null,
  "total_amount": null,
  "amound_paid": null,
  "credits_applied": null,
  "balance": null,
  "status": "open",
  "description": "an example of a bill",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "bill",
  "api": "accounting"
}

Create a Bill 

create a billPOST /accounts/{account_id}/accounting/bills/

To create a bill, perform a POST request containing a JSON object with the following parameters:

  • contact (required): A Contact object related to the bill. Only id is required in the object.

  • reference: String. Reference number for the transaction.

  • currency: A Currency object that relates to the bill.

  • exchange_rate: Float. Exchange rate for the currency used in the bill.

  • date: ISO 8601 timestamp of the transaction.

  • due_date: ISO 8601 timestamp indicating when the bill is due.

  • status: The status of the bill.

  • description: Description of the bill.

  • raw: Raw attribute names and values that will be propagated during the request. Service-specific attributes can be specified here.

Notes:

xero Raw input LineItems objects are currently required by xero in order to create a bill. The type will be forced to ACCPAY for bills, and ACCREC for invoices.

Example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/accounting/bills/' \
    -XPOST -d '{
        "contact": {
            "id": "contact_MTcxMDkwMzFiMGU4ODJiNg"
        },
        "reference": "BILL01",
        "currency": {"code": "USD"},
        "exchange_rate": 30.1,
        "date": "2020-09-01T10:00:00Z",
        "due_date": "2020-11-01T10:00:00Z",
        "status": "open",
        "description": "an example of a bill",
        "raw": {
            "object": {
                "Line": []
            }
        }
    }'
  • Response  201Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "bill_MTcxMDkwMzFiMGU4ODJiNg",
  "contact": {
    "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
    "name": "Gary Payton",
    "contact_type": "vendor",
    "first_name": "Gary",
    "middle_name": null,
    "last_name": "Payton",
    "company_name": "Seattle SuperSonics",
    "title": "Mr.",
    "email": "gary@supersonics.com",
    "phones": [
      {
        "phone_type": "mobile",
        "number": "11111111"
      }
    ],
    "addresses": [
      {
        "address_type": "billing",
        "country": "USA",
        "city": "Seattle",
        "postal_code": "98101",
        "region": "WA",
        "address_lines": [
          "123 Some St."
        ]
      }
    ],
    "currency": {
      "code": "USD",
      "name": "United States Dollar"
    },
    "description": "he's pretty good at basketball",
    "created": "2020-10-20T20:08:50Z",
    "modified": "2020-10-20T20:09:50Z",
    "type": "contact",
    "api": "accounting"
  },
  "reference": "BILL01",
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "exchange_rate": 30.1,
  "date": "2020-09-01T10:00:00Z",
  "due_date": "2020-11-01T10:00:00Z",
  "payments": [],
  "sub_total": null,
  "total_tax": null,
  "total_amount": null,
  "amound_paid": null,
  "credits_applied": null,
  "balance": null,
  "status": "open",
  "description": "an example of a bill",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "bill",
  "api": "accounting"
}

Update a Bill 

update a billPATCH /accounts/{account_id}/accounting/bills/{bill_id}

To update a bill, perform a PATCH request containing a JSON object with any of the following parameters:

  • contact: A Contact object related to the bill. Only id is required in the object.

  • reference: String. Reference number for the transaction.

  • currency: A Currency object that relates to the bill.

  • exchange_rate: Float. Exchange rate for the currency used in the bill.

  • date: ISO 8601 timestamp of the transaction.

  • due_date: ISO 8601 timestamp indicating when the bill is due.

  • status: The status of the bill.

  • description: Description of the bill.

  • raw: Raw attribute names and values that will be propagated during the request. Service-specific attributes can be specified here.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "due_date": "2020-11-01T10:00:00Z",
        "description": "an example of a bill"
    }' \
    'https://api.kloudless.com/v1/accounts/me/accounting/bills/bill_MTcxMDkwMzFiMGU4ODJiNg'
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "bill_MTcxMDkwMzFiMGU4ODJiNg",
  "contact": {
    "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
    "name": "Gary Payton",
    "contact_type": "vendor",
    "first_name": "Gary",
    "middle_name": null,
    "last_name": "Payton",
    "company_name": "Seattle SuperSonics",
    "title": "Mr.",
    "email": "gary@supersonics.com",
    "phones": [
      {
        "phone_type": "mobile",
        "number": "11111111"
      }
    ],
    "addresses": [
      {
        "address_type": "billing",
        "country": "USA",
        "city": "Seattle",
        "postal_code": "98101",
        "region": "WA",
        "address_lines": [
          "123 Some St."
        ]
      }
    ],
    "currency": {
      "code": "USD",
      "name": "United States Dollar"
    },
    "description": "he's pretty good at basketball",
    "created": "2020-10-20T20:08:50Z",
    "modified": "2020-10-20T20:09:50Z",
    "type": "contact",
    "api": "accounting"
  },
  "reference": "BILL01",
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "exchange_rate": 30.1,
  "date": "2020-09-01T10:00:00Z",
  "due_date": "2020-11-01T10:00:00Z",
  "payments": [],
  "sub_total": null,
  "total_tax": null,
  "total_amount": null,
  "amound_paid": null,
  "credits_applied": null,
  "balance": null,
  "status": "open",
  "description": "an example of a bill",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "bill",
  "api": "accounting"
}

Delete a Bill 

delete a billDELETE /accounts/{account_id}/accounting/bills/{bill_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/me/accounting/bills/bill_MTcxMDkwMzFiMGU4ODJiNg
  • Response  204

Invoices 

An Invoice object represents a sales form where the customer pays for a product or service later. The Invoice object has the following metadata:

  • id Unique identifier for the invoice.

  • contact A Contact object related to the invoice.

  • reference String. Reference number for the transaction.

  • currency A Currency object that relates to the invoice. It has the following attributes:

    • code: A three letter string representing the ISO 4217 code for the currency. For example, USD. (required)
    • name: The full name of the currency. For example, United States Dollar. (read-only)

  • exchange_rate Float. Exchange rate for the currency used in the invoice.

  • date ISO 8601 timestamp of the transaction (entered by the user).

  • due_date ISO 8601 timestamp indicating when the invoice is due.

  • payments A list of Payment objects related to the invoice.

  • sub_total Float. Total price of goods (excluding tax).

  • total_tax Float. Total amount of tax.

  • total_amount Float. Total amount (including tax).

  • amount_paid Float. Amount paid for the invoice.

  • credits_applied Float. Amount of credits applied.

  • balance Float. Reflects any payments made against the transaction. A balance of 0 indicates that the invoice is fully paid.

  • status The status of the invoice. One of draft, open, paid, void, or other.

  • sent Boolean. Whether the invoice has already been sent or not.

  • description Description of the invoice.

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

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

  • raw The raw object retrieved from the upstream service’s API.

  • type Always invoice.

  • api Always accounting.

Note:

The balance field is currently unavailable for xero. Invoices with ACCREC type are unified as bills.

List Invoices 

list invoicesGET /accounts/{account_id}/accounting/invoices/{?page,page_size,contact_id,before,after,status}

Lists all invoices, optionally filterable by contact_id, before, after, or status.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/accounting/invoices/'

The response contains the following information, where each object is an Invoice:

  • count Integer. Number of objects on this page.

  • page String. 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 Array. List of objects.

  • Parameters
  • contact_id
    string (optional) 

    Only invoices related to the corresponding contact will be returned.

    before
    string (optional) 

    Only invoices with a date before this ISO 8601 timestamp (exclusive) are returned. The default value is the current time.

    after
    string (optional) 

    Only invoices with a date after this ISO 8601 timestamp (exclusive) are returned. The default value is the start of Unix Epoch Time (1970-01-01T00:00:00Z).

    status
    string (optional) 

    Only invoices with the specified status will be returned.

    page_size
    number (optional) Default: 100 

    Number of objects in each page. The page_size is treated as advisory and may not be strictly adhered to, depending on the upstream service’s capabilities. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "count": 1,
  "page": 1,
  "next_page": null,
  "objects": [
    {
      "id": "invoice_MTcxMDkwMzFiMGU4ODJiNg",
      "contact": {
        "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
        "name": "Gary Payton",
        "contact_type": "customer",
        "first_name": "Gary",
        "middle_name": null,
        "last_name": "Payton",
        "company_name": "Seattle SuperSonics",
        "title": "Mr.",
        "email": "gary@supersonics.com",
        "phones": [
          {
            "phone_type": "mobile",
            "number": "11111111"
          }
        ],
        "addresses": [
          {
            "address_type": "billing",
            "country": "USA",
            "city": "Seattle",
            "postal_code": "98101",
            "region": "WA",
            "address_lines": [
              "123 Some St."
            ]
          }
        ],
        "currency": {
          "code": "USD",
          "name": "United States Dollar"
        },
        "description": "he's pretty good at basketball",
        "created": "2020-10-20T20:08:50Z",
        "modified": "2020-10-20T20:09:50Z",
        "type": "contact",
        "api": "accounting"
      },
      "reference": "INV01",
      "currency": {
        "code": "USD",
        "name": "United States Dollar"
      },
      "exchange_rate": 30.1,
      "date": "2020-09-01T10:00:00Z",
      "due_date": "2020-11-01T10:00:00Z",
      "payments": [],
      "sub_total": null,
      "total_tax": null,
      "total_amount": null,
      "amound_paid": null,
      "credits_applied": null,
      "balance": null,
      "status": "open",
      "sent": false,
      "description": "an example of an invoice",
      "created": "2020-10-20T20:08:50Z",
      "modified": "2020-10-20T20:09:50Z",
      "type": "invoice",
      "api": "accounting"
    }
  ],
  "type": "object_list",
  "api": "accounting"
}

Retrieve an Invoice 

retrieve an invoiceGET /accounts/{account_id}/accounting/invoices/{invoice_id}

Retrieves metadata for an individual invoice when provided with its ID.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/accounting/invoices/invoice_MTcxMDkwMzFiMGU4ODJiNg'
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "invoice_MTcxMDkwMzFiMGU4ODJiNg",
  "contact": {
    "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
    "name": "Gary Payton",
    "contact_type": "customer",
    "first_name": "Gary",
    "middle_name": null,
    "last_name": "Payton",
    "company_name": "Seattle SuperSonics",
    "title": "Mr.",
    "email": "gary@supersonics.com",
    "phones": [
      {
        "phone_type": "mobile",
        "number": "11111111"
      }
    ],
    "addresses": [
      {
        "address_type": "billing",
        "country": "USA",
        "city": "Seattle",
        "postal_code": "98101",
        "region": "WA",
        "address_lines": [
          "123 Some St."
        ]
      }
    ],
    "currency": {
      "code": "USD",
      "name": "United States Dollar"
    },
    "description": "he's pretty good at basketball",
    "created": "2020-10-20T20:08:50Z",
    "modified": "2020-10-20T20:09:50Z",
    "type": "contact",
    "api": "accounting"
  },
  "reference": "INV01",
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "exchange_rate": 30.1,
  "date": "2020-09-01T10:00:00Z",
  "due_date": "2020-11-01T10:00:00Z",
  "payments": [],
  "sub_total": null,
  "total_tax": null,
  "total_amount": null,
  "amound_paid": null,
  "credits_applied": null,
  "balance": null,
  "status": "open",
  "sent": false,
  "description": "an example of an invoice",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "invoice",
  "api": "accounting"
}

Create an Invoice 

create an invoicePOST /accounts/{account_id}/accounting/invoices/

To create an invoice, perform a POST request containing a JSON object with the following parameters:

  • contact (required): A Contact object related to the invoice. Only id is required in the object.

  • reference: String. Reference number for the transaction.

  • currency: A Currency object that relates to the invoice.

  • exchange_rate: Float. Exchange rate for the currency used in the invoice.

  • date: ISO 8601 timestamp of the transaction.

  • due_date: ISO 8601 timestamp indicating when the invoice is due.

  • status: The status of the invoice.

  • description: Description of the invoice.

  • raw: Raw attribute names and values that will be propagated during the request. Service-specific attributes can be specified here.

Notes:

xero Raw input LineItems objects are currently required by xero in order to create an invoice. The type will be forced to ACCREC for invoices, and ACCPAY for bills.

Example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/accounting/invoices/' \
    -XPOST -d '{
        "contact": {
            "id": "contact_MTcxMDkwMzFiMGU4ODJiNg"
        },
        "reference": "INV01",
        "currency": {"code": "USD"},
        "exchange_rate": 30.1,
        "date": "2020-09-01T10:00:00Z",
        "due_date": "2020-11-01T10:00:00Z",
        "status": "open",
        "description": "an example of an invoice",
        "raw": {
            "object": {
                "Line": []
            }
        }
    }'
  • Response  201Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "invoice_MTcxMDkwMzFiMGU4ODJiNg",
  "contact": {
    "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
    "name": "Gary Payton",
    "contact_type": "customer",
    "first_name": "Gary",
    "middle_name": null,
    "last_name": "Payton",
    "company_name": "Seattle SuperSonics",
    "title": "Mr.",
    "email": "gary@supersonics.com",
    "phones": [
      {
        "phone_type": "mobile",
        "number": "11111111"
      }
    ],
    "addresses": [
      {
        "address_type": "billing",
        "country": "USA",
        "city": "Seattle",
        "postal_code": "98101",
        "region": "WA",
        "address_lines": [
          "123 Some St."
        ]
      }
    ],
    "currency": {
      "code": "USD",
      "name": "United States Dollar"
    },
    "description": "he's pretty good at basketball",
    "created": "2020-10-20T20:08:50Z",
    "modified": "2020-10-20T20:09:50Z",
    "type": "contact",
    "api": "accounting"
  },
  "reference": "INV01",
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "exchange_rate": 30.1,
  "date": "2020-09-01T10:00:00Z",
  "due_date": "2020-11-01T10:00:00Z",
  "payments": [],
  "sub_total": null,
  "total_tax": null,
  "total_amount": null,
  "amound_paid": null,
  "credits_applied": null,
  "balance": null,
  "status": "open",
  "sent": false,
  "description": "an example of an invoice",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "invoice",
  "api": "accounting"
}

Update an Invoice 

update an invoicePATCH /accounts/{account_id}/accounting/invoices/{invoice_id}

To update an invoice, perform a PATCH request containing a JSON object with any of the following parameters:

  • contact: A Contact object related to the invoice. Only id is required in the object.

  • reference: String. Reference number for the transaction.

  • currency: A Currency object that relates to the invoice.

  • exchange_rate: Float. Exchange rate for the currency used in the invoice.

  • date: ISO 8601 timestamp of the transaction.

  • due_date: ISO 8601 timestamp indicating when the invoice is due.

  • status: The status of the invoice.

  • description: Description of the invoice.

  • raw: Raw attribute names and values that will be propagated during the request. Service-specific attributes can be specified here.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "due_date": "2020-11-01T10:00:00Z",
        "description": "an example of an invoice"
    }' \
    'https://api.kloudless.com/v1/accounts/me/accounting/invoices/invoice_MTcxMDkwMzFiMGU4ODJiNg'
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "invoice_MTcxMDkwMzFiMGU4ODJiNg",
  "contact": {
    "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
    "name": "Gary Payton",
    "contact_type": "customer",
    "first_name": "Gary",
    "middle_name": null,
    "last_name": "Payton",
    "company_name": "Seattle SuperSonics",
    "title": "Mr.",
    "email": "gary@supersonics.com",
    "phones": [
      {
        "phone_type": "mobile",
        "number": "11111111"
      }
    ],
    "addresses": [
      {
        "address_type": "billing",
        "country": "USA",
        "city": "Seattle",
        "postal_code": "98101",
        "region": "WA",
        "address_lines": [
          "123 Some St."
        ]
      }
    ],
    "currency": {
      "code": "USD",
      "name": "United States Dollar"
    },
    "description": "he's pretty good at basketball",
    "created": "2020-10-20T20:08:50Z",
    "modified": "2020-10-20T20:09:50Z",
    "type": "contact",
    "api": "accounting"
  },
  "reference": "INV01",
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "exchange_rate": 30.1,
  "date": "2020-09-01T10:00:00Z",
  "due_date": "2020-11-01T10:00:00Z",
  "payments": [],
  "sub_total": null,
  "total_tax": null,
  "total_amount": null,
  "amound_paid": null,
  "credits_applied": null,
  "balance": null,
  "status": "open",
  "sent": false,
  "description": "an example of an invoice",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "invoice",
  "api": "accounting"
}

Delete an Invoice 

delete an invoiceDELETE /accounts/{account_id}/accounting/invoices/{invoice_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/me/accounting/invoices/invoice_MTcxMDkwMzFiMGU4ODJiNg
  • Response  204

Payments 

A Payment object represents a payment for invoices or bills, or a general payment to a customer or vendor. The Payment object has the following metadata:

  • id Unique identifier for the payment.

  • payment_type Type of payment. One of customer, vendor, customer_refund, vendor_refund, or other.

  • contact A Contact object related to the payment.

  • invoices A list of Bill objects or a list of Invoice objects that are related to the payment.

  • reference String. Reference number for the transaction.

  • currency A Currency object related to the account. It has the following attributes:

    • code: A three letter string representing the ISO 4217 code for the currency. For example, USD. (required)
    • name: The full name of the currency. For example, United States Dollar. (read-only)

  • exchange_rate Float. Exchange rate for the currency used in the payment.

  • date ISO 8601 timestamp of the transaction (entered by the user).

  • total_amount Float. The total payment amount.

  • method The payment method. One of cash, credit_card, check, bank, stripe, or other.

  • status Either success or failure.

  • description Description of the payment.

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

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

  • raw The raw object retrieved from the upstream service’s API.

  • type Always payment.

  • api Always accounting.

List Payments 

list paymentsGET /accounts/{account_id}/accounting/payments/{?page,page_size,payment_type,invoice_id,before,after}

Lists all payments, optionally filterable by payment_type, invoice_id, before, or after.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/accounting/payments/'

The response contains the following information, where each object is a Payment:

  • count Integer. Number of objects on this page.

  • page String. 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 Array. List of objects.

  • Parameters
  • payment_type
    string (optional) 

    Only payments of the specified type will be returned.

    invoice_id
    string (optional) 

    This could be an id of either a Bill or Invoice object. Only payments related to the corresponding bill/invoice will be returned.

    before
    string (optional) 

    Only payments with a date before this ISO 8601 timestamp (exclusive) are returned. The default value is the current time.

    after
    string (optional) 

    Only payments with a date after this ISO 8601 timestamp (exclusive) are returned. The default value is the start of Unix Epoch Time (1970-01-01T00:00:00Z).

    page_size
    number (optional) Default: 100 

    Number of objects in each page. The page_size is treated as advisory and may not be strictly adhered to, depending on the upstream service’s capabilities. The page_size must be between 1 and 1000.

    page
    string (optional) 

    Page to return. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "count": 1,
  "page": 1,
  "next_page": null,
  "objects": [
    {
      "id": "payment_MTcxMDkwMzFiMGU4ODJiNg",
      "payment_type": "customer",
      "contact": {
        "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
        "name": "Gary Payton",
        "contact_type": "customer",
        "first_name": "Gary",
        "middle_name": null,
        "last_name": "Payton",
        "company_name": "Seattle SuperSonics",
        "title": "Mr.",
        "email": "gary@supersonics.com",
        "phones": [
          {
            "phone_type": "mobile",
            "number": "11111111"
          }
        ],
        "addresses": [
          {
            "address_type": "billing",
            "country": "USA",
            "city": "Seattle",
            "postal_code": "98101",
            "region": "WA",
            "address_lines": [
              "123 Some St."
            ]
          }
        ],
        "currency": {
          "code": "USD",
          "name": "United States Dollar"
        },
        "description": "he's pretty good at basketball",
        "created": "2020-10-20T20:08:50Z",
        "modified": "2020-10-20T20:09:50Z",
        "type": "contact",
        "api": "accounting"
      },
      "invoices": [
        {
          "id": "invoice_MTcxMDkwMzFiMGU4ODJiNg",
          "contact": null,
          "reference": "INV01",
          "currency": {
            "code": "USD",
            "name": "United States Dollar"
          },
          "exchange_rate": 30.1,
          "date": "2020-09-01T10:00:00Z",
          "due_date": "2020-11-01T10:00:00Z",
          "payments": null,
          "sub_total": null,
          "total_tax": null,
          "total_amount": null,
          "amound_paid": null,
          "credits_applied": null,
          "balance": null,
          "status": "open",
          "sent": false,
          "description": "an example of an invoice",
          "created": "2020-10-20T20:08:50Z",
          "modified": "2020-10-20T20:09:50Z",
          "type": "invoice",
          "api": "accounting"
        }
      ],
      "reference": "PAY01",
      "currency": {
        "code": "USD",
        "name": "United States Dollar"
      },
      "exchange_rate": 30.1,
      "date": "2020-09-01T10:00:00Z",
      "total_amount": 9.99,
      "method": "cash",
      "status": "success",
      "description": "an example of a payment",
      "created": "2020-10-20T20:08:50Z",
      "modified": "2020-10-20T20:09:50Z",
      "type": "payment",
      "api": "accounting"
    }
  ],
  "type": "object_list",
  "api": "accounting"
}

Retrieve a Payment 

retrieve a paymentGET /accounts/{account_id}/accounting/payments/{payment_id}

Retrieves metadata for an individual payment when provided with its ID.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    'https://api.kloudless.com/v1/accounts/me/accounting/payments/payment_MTcxMDkwMzFiMGU4ODJiNg'
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "payment_MTcxMDkwMzFiMGU4ODJiNg",
  "payment_type": "customer",
  "contact": {
    "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
    "name": "Gary Payton",
    "contact_type": "customer",
    "first_name": "Gary",
    "middle_name": null,
    "last_name": "Payton",
    "company_name": "Seattle SuperSonics",
    "title": "Mr.",
    "email": "gary@supersonics.com",
    "phones": [
      {
        "phone_type": "mobile",
        "number": "11111111"
      }
    ],
    "addresses": [
      {
        "address_type": "billing",
        "country": "USA",
        "city": "Seattle",
        "postal_code": "98101",
        "region": "WA",
        "address_lines": [
          "123 Some St."
        ]
      }
    ],
    "currency": {
      "code": "USD",
      "name": "United States Dollar"
    },
    "description": "he's pretty good at basketball",
    "created": "2020-10-20T20:08:50Z",
    "modified": "2020-10-20T20:09:50Z",
    "type": "contact",
    "api": "accounting"
  },
  "invoices": [
    {
      "id": "invoice_MTcxMDkwMzFiMGU4ODJiNg",
      "contact": null,
      "reference": "INV01",
      "currency": {
        "code": "USD",
        "name": "United States Dollar"
      },
      "exchange_rate": 30.1,
      "date": "2020-09-01T10:00:00Z",
      "due_date": "2020-11-01T10:00:00Z",
      "payments": null,
      "sub_total": null,
      "total_tax": null,
      "total_amount": null,
      "amound_paid": null,
      "credits_applied": null,
      "balance": null,
      "status": "open",
      "sent": false,
      "description": "an example of an invoice",
      "created": "2020-10-20T20:08:50Z",
      "modified": "2020-10-20T20:09:50Z",
      "type": "invoice",
      "api": "accounting"
    }
  ],
  "reference": "PAY01",
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "exchange_rate": 30.1,
  "date": "2020-09-01T10:00:00Z",
  "total_amount": 9.99,
  "method": "cash",
  "status": "success",
  "description": "an example of a payment",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "payment",
  "api": "accounting"
}

Create a Payment 

create a paymentPOST /accounts/{account_id}/accounting/payments/

To create a payment, perform a POST request containing a JSON object with the following parameters:

  • payment_type (required): Type of payment.

  • contact (required for some): A Contact object related to the payment. Only id is required in the object.

  • invoices (required for some): A list of Bill objects or a list of Invoice objects that are related to the payment. Only the id is required for each Bill/Invoice object.

  • reference: Reference number for the transaction.

  • currency: A Currency object related to the account.

  • exchange_rate: Exchange rate for the currency used in the payment.

  • date: ISO 8601 timestamp of the transaction (entered by the user).

  • total_amount (required): The total payment amount.

  • method: The payment method.

  • description: The payment description.

  • raw: Raw attribute names and values that will be propagated during the request. Service-specific attributes can be specified here.

Example request:

curl -XPOST -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    'https://api.kloudless.com/v1/accounts/me/accounting/payments/' \
    -XPOST -d '{
        "payment_type": "customer",
        "contact": {
            "id": "contact_MTcxMDkwMzFiMGU4ODJiNg"
        },
        "invoices": [{
            "id": "invoice_MTcxMDkwMzFiMGU4ODJiNg"
        }],
        "reference": "PAY01",
        "currency": {"code": "USD"},
        "exchange_rate": 30.1,
        "date": "2020-09-01T10:00:00Z",
        "total_amount": 9.99,
        "description": "an example of a payment"
    }'
  • Response  201Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "payment_MTcxMDkwMzFiMGU4ODJiNg",
  "payment_type": "customer",
  "contact": {
    "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
    "name": "Gary Payton",
    "contact_type": "customer",
    "first_name": "Gary",
    "middle_name": null,
    "last_name": "Payton",
    "company_name": "Seattle SuperSonics",
    "title": "Mr.",
    "email": "gary@supersonics.com",
    "phones": [
      {
        "phone_type": "mobile",
        "number": "11111111"
      }
    ],
    "addresses": [
      {
        "address_type": "billing",
        "country": "USA",
        "city": "Seattle",
        "postal_code": "98101",
        "region": "WA",
        "address_lines": [
          "123 Some St."
        ]
      }
    ],
    "currency": {
      "code": "USD",
      "name": "United States Dollar"
    },
    "description": "he's pretty good at basketball",
    "created": "2020-10-20T20:08:50Z",
    "modified": "2020-10-20T20:09:50Z",
    "type": "contact",
    "api": "accounting"
  },
  "invoices": [
    {
      "id": "invoice_MTcxMDkwMzFiMGU4ODJiNg",
      "contact": null,
      "reference": "INV01",
      "currency": {
        "code": "USD",
        "name": "United States Dollar"
      },
      "exchange_rate": 30.1,
      "date": "2020-09-01T10:00:00Z",
      "due_date": "2020-11-01T10:00:00Z",
      "payments": null,
      "sub_total": null,
      "total_tax": null,
      "total_amount": null,
      "amound_paid": null,
      "credits_applied": null,
      "balance": null,
      "status": "open",
      "sent": false,
      "description": "an example of an invoice",
      "created": "2020-10-20T20:08:50Z",
      "modified": "2020-10-20T20:09:50Z",
      "type": "invoice",
      "api": "accounting"
    }
  ],
  "reference": "PAY01",
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "exchange_rate": 30.1,
  "date": "2020-09-01T10:00:00Z",
  "total_amount": 9.99,
  "method": "cash",
  "status": "success",
  "description": "an example of a payment",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "payment",
  "api": "accounting"
}

Update a Payment 

update a paymentPATCH /accounts/{account_id}/accounting/payments/{payment_id}

To update a payment, perform a PATCH request containing a JSON object with any of the following parameters:

  • payment_type: Type of payment.

  • contact: A Contact object related to the payment. Only id is required in the object.

  • invoices: A list of Bill objects or a list of Invoice objects that are related to the payment. Only the id is required for each Bill/Invoice object.

  • reference: Reference number for the transaction.

  • currency: A Currency object related to the account.

  • exchange_rate: Exchange rate for the currency used in the payment.

  • date: ISO 8601 timestamp of the transaction (entered by the user).

  • total_amount: Total amount of the payment.

  • method: The payment method.

  • description: The payment description.

  • raw: Raw attribute names and values that will be propagated during the request. Service-specific attributes can be specified here.

Example request:

curl -H 'Authorization: Bearer [TOKEN]' \
    -H 'Content-Type: application/json' \
    -XPATCH -d '{
        "payment_type": "customer",
        "total_amount": 9.99,
        "description": "an example of a payment"
    }' \
    'https://api.kloudless.com/v1/accounts/me/accounting/payments/payment_MTcxMDkwMzFiMGU4ODJiNg'
  • Response  200Toggle

  • Headers

    Content-Type: application/json

    Body

    {
  "id": "payment_MTcxMDkwMzFiMGU4ODJiNg",
  "payment_type": "customer",
  "contact": {
    "id": "contact_MTcxMDkwMzFiMGU4ODJiNg",
    "name": "Gary Payton",
    "contact_type": "customer",
    "first_name": "Gary",
    "middle_name": null,
    "last_name": "Payton",
    "company_name": "Seattle SuperSonics",
    "title": "Mr.",
    "email": "gary@supersonics.com",
    "phones": [
      {
        "phone_type": "mobile",
        "number": "11111111"
      }
    ],
    "addresses": [
      {
        "address_type": "billing",
        "country": "USA",
        "city": "Seattle",
        "postal_code": "98101",
        "region": "WA",
        "address_lines": [
          "123 Some St."
        ]
      }
    ],
    "currency": {
      "code": "USD",
      "name": "United States Dollar"
    },
    "description": "he's pretty good at basketball",
    "created": "2020-10-20T20:08:50Z",
    "modified": "2020-10-20T20:09:50Z",
    "type": "contact",
    "api": "accounting"
  },
  "invoices": [
    {
      "id": "invoice_MTcxMDkwMzFiMGU4ODJiNg",
      "contact": null,
      "reference": "INV01",
      "currency": {
        "code": "USD",
        "name": "United States Dollar"
      },
      "exchange_rate": 30.1,
      "date": "2020-09-01T10:00:00Z",
      "due_date": "2020-11-01T10:00:00Z",
      "payments": null,
      "sub_total": null,
      "total_tax": null,
      "total_amount": null,
      "amound_paid": null,
      "credits_applied": null,
      "balance": null,
      "status": "open",
      "sent": false,
      "description": "an example of an invoice",
      "created": "2020-10-20T20:08:50Z",
      "modified": "2020-10-20T20:09:50Z",
      "type": "invoice",
      "api": "accounting"
    }
  ],
  "reference": "PAY01",
  "currency": {
    "code": "USD",
    "name": "United States Dollar"
  },
  "exchange_rate": 30.1,
  "date": "2020-09-01T10:00:00Z",
  "total_amount": 9.99,
  "method": "cash",
  "status": "success",
  "description": "an example of a payment",
  "created": "2020-10-20T20:08:50Z",
  "modified": "2020-10-20T20:09:50Z",
  "type": "payment",
  "api": "accounting"
}

Delete a Payment 

delete a paymentDELETE /accounts/{account_id}/accounting/payments/{payment_id}

Example request:

curl -L -H 'Authorization: Bearer [TOKEN]' \
    -XDELETE https://api.kloudless.com/v1/accounts/me/accounting/payments/payment_MTcxMDkwMzFiMGU4ODJiNg
  • Response  204

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.

List Raw Objects 

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

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.

    encoded
    string (optional) 

    Represents key-value pairs that describe parent object identifiers or other identifiers required to list service_object_name objects. For example, some objects may be nested within other resources such as projects, organizations, or simply parent objects such as CRM Accounts. Since those IDs would be required to list sub-obejcts via this endpoint, they may be specified with their Kloudless-encoded IDs in the form encoded[{service_object_name}_id]={object_id}. Here is an example: encoded[project_id]=object_DIyNjkzNg.

    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. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

  • 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 is encoded in base64. 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 is encoded in base64. 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 is encoded in base64. 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. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

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

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. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

  • 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. If page is not specified, the first page is returned, containing page_size objects. To retrieve pages after the first page, set page to the value of next_page returned in the previous response.

  • 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 is encoded in base64. 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 is encoded in base64. 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 is encoded in base64. 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