Get Timesheet

This endpoint returns one timesheet by ID, with all of its timecards and daily hours.

Endpoint

GET /v1/timesheets/timesheets/:id

Authentication

Include your API key in the x-api-key header. See Authentication.

Required Scope

timesheets:read

Path Parameters

Parameter	Type	Required	Description
`id`	`string`	Yes	Timesheet ID in the format `<tenantId>#<userId>#<YYYYMMDD>_<YYYYMMDD>`, URL-encoded. For example, `tenant-123#user-a#20221231_20230106` becomes `tenant-123%23user-a%2320221231_20230106`. See Timesheet IDs.

Request Body

This endpoint does not accept a request body.

Example Request

curl "https://api.crewsum.com/v1/timesheets/timesheets/tenant-123%23user-a%2320221231_20230106" \
  -H "x-api-key: $CREWSUM_API_KEY"

const timesheetId = "tenant-123#user-a#20221231_20230106";
const response = await fetch(
  `https://api.crewsum.com/v1/timesheets/timesheets/${encodeURIComponent(timesheetId)}`,
  {
    headers: { "x-api-key": process.env.CREWSUM_API_KEY },
  },
);
const result = await response.json();

GET /v1/timesheets/timesheets/tenant-123%23user-a%2320221231_20230106 HTTP/1.1
Host: api.crewsum.com
x-api-key: <your-api-key>

Response

On success, the API returns HTTP 200 OK.

Example Response

The example shows one timecard. Each timecard has an entry for all seven days, from Saturday to Friday.

{
  "message": "Successfully fetched timesheet",
  "data": {
    "timesheetId": "tenant-123#user-a#20221231_20230106",
    "tenantId": "tenant-123",
    "userId": "tenant-123#user-a",
    "userFullName": "User Full Name",
    "periodStart": "2022-12-31",
    "periodEnd": "2023-01-06",
    "submittedAt": "2023-01-07T00:00:00.000Z",
    "resubmissionAllowed": false,
    "supplierId": "supplier-stu123vwx4567890",
    "supplierName": "Supplier Name",
    "userCustomFields": {},
    "timeCards": [
      {
        "timesheetId": "tenant-123#user-a#20221231_20230106",
        "userId": "tenant-123#user-a",
        "projectId": "project-mno123pqr4567890",
        "taskId": "task-pqr123stu4567890",
        "status": "pending",
        "data": {
          "Saturday": {
            "isoDate": "2022-12-31T00:00:00.000Z",
            "hours": 0,
            "description": null,
            "review": null,
            "reviewComment": null
          },
          "Sunday": {
            "isoDate": "2023-01-01T00:00:00.000Z",
            "hours": 0,
            "description": null,
            "review": null,
            "reviewComment": null
          },
          "Monday": {
            "isoDate": "2023-01-02T00:00:00.000Z",
            "hours": 8,
            "description": "Worked on implementation",
            "review": null,
            "reviewComment": null
          },
          "Tuesday": {
            "isoDate": "2023-01-03T00:00:00.000Z",
            "hours": 8,
            "description": "Worked on implementation",
            "review": null,
            "reviewComment": null
          },
          "Wednesday": {
            "isoDate": "2023-01-04T00:00:00.000Z",
            "hours": 8,
            "description": "Worked on implementation",
            "review": null,
            "reviewComment": null
          },
          "Thursday": {
            "isoDate": "2023-01-05T00:00:00.000Z",
            "hours": 8,
            "description": "Worked on implementation",
            "review": null,
            "reviewComment": null
          },
          "Friday": {
            "isoDate": "2023-01-06T00:00:00.000Z",
            "hours": 8,
            "description": "Worked on implementation",
            "review": null,
            "reviewComment": null
          }
        },
        "projectName": "Project Name",
        "projectBillingCategory": null,
        "isDefault": false,
        "taskName": "Task Name",
        "taskBillingCategory": null,
        "userFullName": "User Full Name",
        "managerComments": null,
        "reviewedAt": null,
        "approverName": null,
        "approverEmail": null,
        "clientId": "client-ghi123jkl4567890",
        "clientName": "Client Name",
        "clientCustomFields": {},
        "projectCustomFields": {}
      }
    ]
  }
}

Response Fields

Field	Type	Description
`userId`	`string`	Internal user ID in the format `<tenantId>#<userId>`. List Timesheets returns the external ID instead.
`submittedAt`	`string \| null`	Submission time. `null` for a saved draft that was never submitted.
`resubmissionAllowed`	`boolean`	Whether the user may submit this timesheet again.
`supplierId`, `supplierName`	`string \| null`	The supplier the timesheet was submitted under, if any.
`timeCards[].status`	`string`	`draft`, `pending`, `approved`, or `rejected`.
`timeCards[].data.<Day>.isoDate`	`string`	The day’s date as a full ISO 8601 timestamp.
`timeCards[].data.<Day>.review`	`boolean \| null`	`true` if the day was approved, `false` if rejected, `null` if not reviewed.
`timeCards[].data.<Day>.reviewComment`	`string \| null`	Rejection reason for the day, if any.
`timeCards[].managerComments`	`string \| null`	Reviewer comments for the timecard.
`timeCards[].reviewedAt`	`string \| null`	Time of the last review.
`timeCards[].approverName`, `approverEmail`	`string \| null`	Reviewer identity. Always `null` for reviews made through the API.

Behavior

The endpoint returns saved drafts as well as submitted timesheets.

Error Responses

Status	Meaning
`400`	The ID path segment was empty (for example, a trailing slash). Message: `Timesheet ID not found`.
`404`	No timesheet has this ID. Message: `Timesheet with ID <id> not found`. This also happens if the `#` characters in the ID were not URL-encoded.
`500`	Crewsum could not fetch the timesheet. Message: `Error fetching timesheet`.

Authentication and scope failures are described in Errors.

This endpoint does not trigger a webhook.