# July 22, 2024 

** The July 22, 2024 Karbon API release includes updates to the Timesheets API to show billed status, and new endpoints to List and Download Files. **
---

## 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](https://karbonhq.github.io/karbon-api-reference/#get-/v3/Timesheets) 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:

```JSON
{
    "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](https://karbonhq.github.io/karbon-api-reference/#tag--Files) 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.:

```JSON
{
    "@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.