July 22, 2024

Billed status on Time Entries

GET Timesheets

Endpoints:

• JSONCopyCopied!

  https://api.karbonhq.com/v3/Timesheets
• JSONCopyCopied!

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

When used with the

method and the query string parameter , these endpoints will now include an additional property in the collection of returned. This status can be used to determine if the time entry has been billed, returning one of the following , , or .

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
  JSONCopyCopied!

  WorkItem
  keys you want the time entries for - you can use the
  JSONCopyCopied!

  WorkItems
  endpoint to get this
• A list of
  JSONCopyCopied!

  TimeSheets
  related to those
  JSONCopyCopied!

  WorkItems
  - you can use
  JSONCopyCopied!

  WorkItemKey
  filtering on the
  JSONCopyCopied!

  TimeSheets
  endpoint to get this , e.g.
  JSONCopyCopied!

  $filter=WorkItemKeys/any(x: x in ('3bfwkMBgL8rz'))

Make a call to

. 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:

JSONCopyCopied!
{
    "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:

• JSONCopyCopied!

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

  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

key , make a call to . This will return a reponse that includes an array of , each with details of each associated File, e.g.:

JSONCopyCopied!
{
    "@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

make a request to the Files endpoint using the token from the endpoint response, e.g. . If required, the filename can be found in the response header, e.g. .

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
  JSONCopyCopied!

  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.