July 22, 2024

Billed status on Time Entries

GET Timesheets

Endpoints:

• https://api.karbonhq.com/v3/Timesheets
• https://api.karbonhq.com/v3/Timesheets/{TimeSheetKey}

When used with the GET method and the query string parameter $expand=TimeEntries, these endpoints will now include an additional BilledStatus property in the collection of TimeEntries returned. This status can be used to determine if the time entry has been billed, returning one of the following Unbilled, Draft, InterimBilled or Billed.

Refer to the Timesheets API documentation for a full example of the response from this endpoint.

Example use case

You want to build a report of work for each of your clients, broken down by billed or unbilled time.

You’ll need:

• A list of WorkItem keys you want the time entries for - you can use the WorkItems endpoint to get this
• A list of TimeSheets related to those WorkItems - you can use WorkItemKey filtering on the TimeSheets endpoint to get this , e.g. $filter=WorkItemKeys/any(x: x in ('3bfwkMBgL8rz'))

Make a call to https://api.karbonhq.com/v3/TimeSheets/2zgGcqrC9JcD?$expand=TimeEntries. This will return a response containing a time sheet and it’s corresponding time entries. Each item in the array of TimeEntries include a billed status, for example:

{
    "TimesheetKey": "2zgGcqrC9JcD",
    "StartDate": "2023-02-20T00:00:00Z",
    "EndDate": "2023-02-26T00:00:00Z",
    "UserKey": "3bxT8HkHxHCG",
    "Status": "Submitted",
    "WorkItemKeys": [
        "3bfwkMBgL8rz"
    ],
    "TimeEntries": [
        {
            "TimeEntryKey": "2hYhcb9VDXtB-3bfwkMBgL8rz-3bxT8HkHxHCG-4cDMPvqnsPJj-2vlSLxVWmxCY-2zgGcqrC9JcD-4",
            "EntityKey": "3bfwkMBgL8rz",
            "WorkItemKey": "3bfwkMBgL8rz",
            "ClientKey": "3dVWVdTQx2cs",
            "ClientType": "Organization",
            "RoleName": "Admin",
            "TaskTypeName": "Admin",
            "Minutes": 384,
            "HourlyRate": 86.0000,
            "Descriptions": [],
            "BilledStatus": "Billed"
        }
    ]
}

List and download files

GET File List and GET File

Endpoints:

• https://api.karbonhq.com/v3/FileList/{EntityType}?EntityKey={Key}
• https://api.karbonhq.com/v3/Files?token={token}

These new endpoints allow the listing and downloading of files associated with Work, Contacts and Organizations in Karbon.

Files retrievable with the FileList endpoint are those shown on:

• a WorkItem (under the Documents tab), or
• a Contact or Organization (under the Details tab)

Refer to the Files API documentation for a full example of the response from this endpoint.

Example use case

You want to automate the downloading a number of files associated with WorkItems in Karbon for archiving in another system.

To retrieve a list of Files associated with the WorkItem key 3bXVhdMHgc9P, make a call to https://api.karbonhq.com/v3/FileList/WorkItem?EntityKey=3bXVhdMHgc9P. This will return a reponse that includes an array of Attachments, each with details of each associated File, e.g.:

{
    "@odata.context": "https://api-dev.karbonhq.com/v3/$metadata#FileList/$entity",
    "EntityKey": "3bXVhdMHgc9P",
    "EntityType": "WorkItem",
    "Attachments": [
        {
            "FileContextKey": "S8bsBjvCRJ3",
            "FileName": "image.jpeg",
            "FileSize": 7316,
            "MimeType": "image/jpeg",
            "DownloadUrl": "/V3/Files?token=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJGaWxlQ29udGV4dFBlcm1hS2V5IjoiUzhic0JqdkNSSjMiLCJpYXQiOjE3MjE1NTUzNjIuMCwiZXhwIjoxNzIxNTU2MjYyLjB9.AtYCQLz_uik7r3nAjwPR-lfJTh6Kf6Dz_9fhWvZVD8Q",
            "DateCreated": "2024-07-18T23:44:26Z"
        }
    ]
}

To start the file download of image.jpeg make a request to the Files endpoint using the token from the FileList endpoint response, e.g. https://api.karbonhq.com/v3/Files?token=yJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJGaWxlQ29udGV4dFBlcm1hS2V5IjoiUzhic0JqdkNSSjMiLCJpYXQiOjE3MjE1NTUzNjIuMCwiZXhwIjoxNzIxNTU2MjYyLjB9.AtYCQLz_uik7r3nAjwPR-lfJTh6Kf6Dz_9fhWvZVD8Q. If required, the filename can be found in the response Content-Disposition header, e.g. inline; filename=image.jpeg.

Note:

• Tokens will only work to download a file for 15 minutes from the point they are generated in the FileList request. When the token has expired, you will receive a HTTP 400 response from the endpoint.
• There is some rate limiting applied to downloads, you should attempt no more than a maximum of two concurrent downloads at a time. Exceeding this limit may result in throttling of your API requests.
• Archived files are shown in the FileList response, but not yet clearly marked as having been archived.