---
title: "Create a contractor timesheet"
method: POST
path: "/v1/contractors/employments/{employment_id}/timesheets"
tags: ["Timesheets"]
---

# Create a contractor timesheet

`POST /v1/contractors/employments/{employment_id}/timesheets`

## Request

- Base URL: `https://gateway.remote.com`
- URL: `https://gateway.remote.com/v1/contractors/employments/{employment_id}/timesheets`
- Auth: one of:
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `https://gateway.remote.com/company.manage`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `timesheet:write`
  - OAuth 2
    - Authorization code: `/auth/oauth2/authorize`
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `timesheet:write`
  - OAuth 2
    - Client credentials
    - Token URL: `/auth/oauth2/token` scopes: `all:write`
  - HTTP bearer

Creates a timesheet on behalf of a contractor employment.

The timesheet is created as an `open` draft, matching a timesheet the contractor creates
themselves: the contractor can still edit the hours, and the customer approves them through the
contractor's invoice rather than the timesheet. Contractor timesheets can't be submitted or
approved through the API.

The hours are immediately available to the contractor in the Remote UI for
self-serve invoice creation (Invoices → Create invoice → "Use Time Tracking").

This endpoint is restricted to contractor employments. Calls against EOR or Global Payroll
employments are rejected with `422`.

## Authentication

This endpoint accepts any one of the following token types:

- **Company-scoped access token** (`OAuth2AuthorizationCode`) — obtained by a company manager through the Authorization Code flow or the Refresh Token flow. See [Authentication for partners](https://developer.remote.com/docs/authentication-for-partners).
- **Company-scoped access token (assertion)** (`OAuth2CompanyManagerAssertion`) — obtained through the `urn:ietf:params:oauth:grant-type:jwt-bearer` grant for a company manager. See [OAuth Assertion](https://developer.remote.com/docs/authorization-method-oauth-assertion).
- **Customer API token** (`CustomerAPIToken`) — generated by the customer on their Integration Settings page, with the scopes they choose there. See [Authorization for customers](https://developer.remote.com/docs/authorization-for-customers).

## Scopes

Any one of the scopes in a token type's row is enough. `all:write` works too.

| Token type | Category | Read only Scope | Write only Scope (read access implicit) |
|---|---|---|---|
| Company-scoped access token | Manage timeoffs (`time_and_attendance`) | - | Manage timesheets (`timesheet:write`) |
| Company-scoped access token (assertion) | Manage timeoffs (`time_and_attendance`) | - | Manage timesheets (`timesheet:write`) |
| Customer API token | Manage timeoffs (`time_and_attendance`) | - | Manage timesheets (`timesheet:write`) |

## Path parameters

- `employment_id` string, required

## Request body

- ContractorCreateTimesheetParams: Parameters for creating a timesheet on behalf of a contractor employment. The target employment is taken from the URL path, not the request body. Allowed `time_trackings.type` values are restricted to the contractor subset: `regular_hours`, `on_call`, `break`.
  - `end_date` string, date, required: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
  - `start_date` string, date, required: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
  - `time_trackings` ContractorTimeTrackingParams[], required: One or more time tracking entries to include in the timesheet.
    - `clock_in` string, date-time, required: UTC date time in [ISO 8601][] format. [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
    - `clock_out` string, date-time, required: UTC date time in [ISO 8601][] format. [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
    - `notes` string, nullable: Optional free-text notes about this time entry, such as project or task details.
    - `timezone` string, required: [TZ identifier](https://www.iana.org/time-zones)
    - `type` 'regular_hours' | 'on_call' | 'break', required: The category of time being tracked. Contractors are restricted to `regular_hours`, `on_call`, or `break`.

## Response `200`

Success

- ContractorTimesheetResponse: Response returned after creating a contractor timesheet.
  - `data` object
    - `timesheet` ContractorTimesheet, required: A contractor timesheet, returned by the contractor create endpoint. Only contains fields relevant to the contractor flow — EOR-only fields (overtime, night/weekend/holiday hours, approval flag) are not included.
      - `break_hours` HoursAndMinutes, required: A duration expressed as hours and minutes.
        - `hours` integer: The number of whole hours.
        - `minutes` integer: The number of remaining minutes (0-59).
      - `country_code` string, required: Country code according to ISO 3166-1 3-digit alphabetic codes.
      - `employment_id` string, uuid, required: A unique identifier in UUID v4 format.
      - `end_date` string, date, required: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
      - `id` string, uuid, required: A unique identifier in UUID v4 format.
      - `notes` string, nullable, required: Optional notes attached to the timesheet.
      - `on_call_hours` HoursAndMinutes, required: A duration expressed as hours and minutes.
        - `hours` integer: The number of whole hours.
        - `minutes` integer: The number of remaining minutes (0-59).
      - `regular_hours` HoursAndMinutes, required: A duration expressed as hours and minutes.
        - `hours` integer: The number of whole hours.
        - `minutes` integer: The number of remaining minutes (0-59).
      - `start_date` string, date, required: UTC date in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) format
      - `status` 'open', required: Timesheets created through the API are open drafts: the contractor can still edit them, and the customer approves the hours through the contractor's invoice.
      - `submitted_at` string, datetime, nullable, required: The timestamp the timesheet was submitted. Always `null` for timesheets created through this endpoint, since they are created open.
      - `time_trackings` ContractorTimeTracking[], required: The individual time tracking entries that make up this timesheet.
        - `clock_in` string, date-time, required: UTC date time in [ISO 8601][] format. [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
        - `clock_out` string, date-time, required: UTC date time in [ISO 8601][] format. [ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601
        - `notes` string, nullable, required: Optional notes about this entry.
        - `timezone` string, required: [TZ identifier](https://www.iana.org/time-zones)
        - `total_hours` HoursAndMinutes, required: A duration expressed as hours and minutes.
          - `hours` integer: The number of whole hours.
          - `minutes` integer: The number of remaining minutes (0-59).
        - `type` 'regular_hours' | 'on_call' | 'break', required: The category of time being tracked. One of `regular_hours`, `on_call`, `break`.
      - `total_hours` HoursAndMinutes, required: A duration expressed as hours and minutes.
        - `hours` integer: The number of whole hours.
        - `minutes` integer: The number of remaining minutes (0-59).

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/remote-com/apis/time-attendance.md) - [All operations](https://skmtc.dev/remote-com/apis/time-attendance/llms.txt) - [OpenAPI document](https://skmtc.dev/remote-com/apis/time-attendance/revisions/84de0ccef126?raw)