Welcome to the Freshbooks Cloud Accounting Element

The Freshbooks Cloud Accounting element is available in the Finance hub. Connect a Freshbooks account to integrate with invoices, payments, customers, taxes, and more.

Element Details

Element Information Details
API Documentation Freshbooks API documentation
Authentication OAuth 2.0
Events Webhooks
Bulk Supported for both upload and download.
Transformations Supported. See Define Common Resources and Transformations for more information about transforming your Freshbooks Cloud Accounting data.
Rate Limits Freshbooks Cloud Accounting rate limit documentation

Base URL

The Cloud Element Base URL for all API calls is https://api.cloud-elements.com/elements/api-v2.

HTTP requests to the REST API are protected with HTTP Custom authentication with your Organization and User secret and an Element Instance token. We use many standard HTTP features, like HTTP verbs, understood by most HTTP clients. JSON is returned in all responses from the API, including errors. The APIs have predictable, straightforward URLs and use HTTP response codes to indicate API errors.

Authenticating with Cloud Elements

To authenticate with Cloud Elements, you need to know your Organization Secret and User Secret. When making some calls, you also need to know the Element Instance token.

When you create an account with us, we assign you an Organization Secret and a User Secret. An Organization is a customer of Cloud Elements (/organizations). The User and Organization secrets represent your account with Cloud Elements.

To find your Organization and User Secret open the profile menu. Search

Alternatively, use the/users/{emailOrId} endpoint:

curl -X GET \
  https://staging.cloud-elements.com/elements/api-v2/users/4370 \
  -H 'authorization: User <ADMINISTRATOR_USER_SECRET>, Organization <ORGANIZATION_SECRET>' \
  -H 'content-type: application/json' \
  -H 'elements-user-password: <USER_PASSWORD>' \

When you create a new connection to an endpoint, you will receive an Element Instance token. After you create an instance, Cloud Elements automatically refreshes the token behind the scenes so that you won't need to connect your application again.

To find your Element instance token:

    GET /instances/<INSTANCE_ID>

An Element Instance token and a User secret are required to execute one of our Hub API calls (e.g. /hubs/documents/files or /hubs/crm/contacts). For more information about Hubs, see the Hub API docs in the navigation area.

Pass tokens and secrets as basic HTTP Header values.

  • To make a Platform or API call, include the following in the header:

    Authorization: User <INSERT_USER_SECRET>, Organization <INSERT_USER_SECRET>
    
  • To make a Hub API call, include the following in the header:

    User <INSERT_USER_SECRET>, Element <INSERT_ELEMENT_INSTANCE_TOKEN>
    

Error Codes

Errors are never fun. To save you time we took a list of error codes from our service providers and normalized them. If a response returns a message that includes a specific detail about the method call, we send our normalized error code along with any additional data included in the body of the message. Below is a sample message from a service provider that would be included with our normalized error code.

{
   "message": "Failed to upload file. File with the same name already exists. Change the name of the file you're uploading or set the overwrite query parameter to true.",
   "requestId": "53dbca9430045c016b46566c",
   "providerMessage": "Item with the same name already exists"
}

We provide the following normalized error codes:

Response Code Error
200 OK – Everything worked as expected.
400 Bad Request – Often due to a missing request parameter.
401 Unauthorized – An invalid element token, user secret and/or org secret provided.
403 Forbidden – Access to the resource by the provider is forbidden.
404 Not found - The requested resource is not found
405 Method Not Allowed – Incorrect HTTP verb used, e.g., GET used when POST expected.
406 Not Acceptable – The response content type does not match the “Accept” header value.
409 Conflict – A resource being created already exists.
415 Unsupported Media Type – The server cannot handle the requested Content-Type.
500 Server Error – Something went wrong on the Cloud Elements server.

Get started by setting up the API provider.