Below is an overview of our REST API, including endpoints related to our general ledger and other components of SoftLedger's accounting software.

SoftLedger has the following endpoints.

Please contact support@softledger.com to request access to the API.

Previous versions documentation of the API are available at the linke below

APIv1 Docs are available here

Note that these docs are deprecated and will reach end of life on April 30th, 2024.

SoftLedger API uses OAuth2.0 to access it's API. For any request to the API, you'll need to pass a JWT.

Prior to making any API request you'll need to request an OAuth token.

After you receive a token, add the following headers to every subsequent request:

{
  "Authorization": "Bearer {access_token}",
  "Content-Type": "application/json"
}

Actions performed by the api will have their audit logs labelled with the name of the api key generated by the SoftLedger team.

Performing requests on behalf of users / Labeling audit log entries

If you would like to use an alternate label, or perform actions on behalf of a user, you can pass the x-softledger-auditlabel header with the email of a user or a string label. This label will then be used in the audit log entry.

• The audit entry will still retain information to know that this was an API request and not performed directly by a user in the SoftLedger UI.
• This header is ignored for tokens generated by a user initiated OAuth flow.

Requests to the SoftLedger API are rate limited to 200 requests per minute.

A rate limited request will return a HTTP Status of 429.

Every request to the API will return the following headers:

X-RateLimit-Remaining: String<integer> - The number of api requests left during the interval.

X-RateLimit-RetryAfter: String<integer> - The number of seconds remaining until the next interval.

The query paramaters for most GET requests limit and cursor allow pagination through large sets of data.

By default limit is set to 25

In order to page forward set the cursor query param to the cursor value returned in the previous requests response data.

Building the filter statement

The query parameter filter and filterType for most GET endpoints allows you to filter on the requested data.

The filter paramater should be a JSON.stringified key: value object.

The filterType should be one of all or any. It defaults to all. If set to all all results that match ALL filters are returned. If set to any all restults that match ANY filters are returned.

For example, if we wanted to get all Invoices that were paid, the where clause would be:

{
  "status": {
    "equals": "paid"
  }
}

This would then be stringified prior to attaching in the URL

let tmp = JSON.stringify({
  status: {
    equals: "paid"
  }
});

Then the request URL would look as follows

https://api.softledger.com/api/invoices?filter=tmp&filterType=any

Available Filter Options

Example

Get all created or approved bills posted after "2020-01-01"

{
  "status": {
    "in": ["created", "approved"]
  },
  "postingDate": {
    "gt": "2020-01-01"
  }
}

Successful API request responses will be described inline throughout the document 401,403,404 Messages will not contain a body as the error is implied. Other 4xx error codes will return as following:

{
  error: "Error Message"
}

Webhooks

Webhooks allow you to subscribe to events that happen in SoftLedger. When one of those events is triggered, we'll send an HTTP POST payload to the webhook's configured URL. Webhooks are sent with an 'at-least' once method. We recommend utilizing the uuid field to ensure that you do not process the same webhook multiple times.

Webhook endpoints should be respond immediately with a http 200 status code. The system that receives the webhook should then process the webhook asynchronously and not wait for its work to complete prior to responding to the webhook request. If the endpoint is slow to respond or returns a non 200 status code, the webhook endpoint will be blacklisted by SoftLedger. Please contact support@softledger.com to resolve the issue if this occurs.

Webhook Payload

The webhook payload will be sent as a JSON object with the following structure:

{
  "uuid": "Unique identifier for the webhook",
  "date": "ISO timestamp for when the webhook was triggered",
  "tenantId": "The tenantUUID that triggered the webhook",
  "objectType": "The type of object that triggered the webhook",
  "objectId": "The _id of the object that triggered the webhook",
  "action": "The action that triggered the webhook",
}

What webhooks are sent?

Each endpoint below specifies what webhooks are sent for each request. The list will contain the objectType and action that will be sent in the webhook payload.