List crew sheets

GET 
/api/v1/crew_sheets

Retrieve the sheet status of the users whose sheets you are allowed to work on, for one period. This is the data behind the Crew Entry screen, which is also known as timekeeping.

The collection is a list of users, not of sheets. Each row names one user and carries that user's sheet in each entry type for the period containing sheet_date. A user appears once per page whether they have three sheets, one, or none.

Required abilities

You must hold at least one of Authority - Timekeeper, Authority - Expensekeeper, or Authority - Custom Entry keeper, or be an administrator. Without one of these the request is refused with 403 Forbidden.

These abilities are group-scoped, so holding one is not enough on its own: you see a given user only when you and that user both belong to a group that carries the role granting you the ability. Each entry type is scoped separately, so you can be able to keep one user's time but not their expenses. Administrators see every user who can log their own time.

Administrators are not exempt over OAuth

On a Bearer-token request the administrator ability is suppressed, so the group-scoped rule above applies to administrators too. An administrator connecting an OAuth app sees only the users reached by the keeper roles they hold explicitly, and the groups those roles are in — which may be none, in which case the response is 200 OK with an empty results array rather than an error. See Administrators are not privileged over OAuth.

Only users who can log time for themselves are ever returned, that is, users holding Authority - User or Authority - Basic Time User. Users who exist purely to run reports or approve sheets are not crew.

Choosing the period and the entry types

Use sheet_date to pick the period and sheet_types to pick which entry types to report on. Both are described under Parameters below.

Filtering

This is a standard collection, so $filter, $top, $skip, and $orderBy work as they do elsewhere. Remember that all string literals in $filter must be JSON-encoded.

In addition to the user fields, this endpoint accepts a sheet_state filter, which selects users by the state of their sheets:

Value	Matches
open	A sheet exists and is open for entry
submitted	A sheet is submitted and awaiting approval
approved	A sheet has been approved
rejected	An approver sent a sheet back
no_sheet	The user has no sheet at all for the period

Note that no_sheet is a status in its own right and is not included in open. Asking for open alone will not return people who have not started a sheet; ask for both when you want everyone with unfinished work.

A user matches when any of the requested entry types is in one of the requested states. The same list then decides which blocks appear on the row, so a user who matched on their time sheet does not also show an approved expense sheet you did not ask about.

Other fields you can filter on:

Filter	Example
User name	fullname contains "Alice"
Sign-in name	user_login eq "alice"
User status	status intersects ["active"]
Group membership	groups intersects ["64BBA147B9AC41D9978062300826C89F"]
Project access	shared_groups_projects intersects ["27C1F8B3D5A9426E9D0F5B41A8E2"]
Role	role_names.pname eq "Timekeeper"
Ability	ability_names.id eq "timekeeper"
User custom field	users_attribs:users_dept eq "Sales"

Any user custom field can be filtered on by its ID, whether or not an administrator has enabled it as a search option and whether or not it is configured as a column.

Sorting

Sort on the user's own columns, for example fullname (the default, which is also accepted under the name pname) or user_login, and on role_names.pname. The three sheet columns (time, expense, custom) and the sheet_state filter are not sortable, because each is composed per row rather than selected from a column; asking for them returns 400 Bad Request. Note also that sorting uses the bare column name, so fullname asc works where id_user_properties.fullname asc does not.

Response shape and paging

A page holds at most 100 rows, which is lower than most collections because every row costs a sheet lookup in each requested entry type. A larger $top is reduced to 100 rather than rejected. Follow @nextLink for the rest.

The row shape is fixed by the Crew Entry screen's column configuration rather than by the request, so the $keys parameter has no effect here. Add or remove columns with the Screen settings endpoints; the approval plan names, entry screen names, and user custom field values are each returned only when a matching column is configured, because each one costs an extra lookup.

Set $screenInclude=1 to also receive the screen object, which reports the column configuration along with which entry types you may keep. A client that only reads sheet data does not need it.

Request

Responses

200

A successful response from a paged collection; see the results array in the response for the list of results for this page. Additional pages may be available and can be fetched using the @nextLink URL.

Note that the examples given may include keys (fields) that may not always be present in the response, depending on the fields requested in the $keys parameter, the user's permissions, and other system settings.

400

A 400 Bad Request is returned when the client request was malformed, invalid, or otherwise could not be processed as-is. Usually, the cause for the error is included in the error.message field of the response, and the client should correct the request and try again.

See also Core Concepts#Error Responses.

401

Not authenticated - you must be signed in to access this resource. Please check the section of the documentation on authentication.

403

A 403 Forbidden response means that you are not authorized to perform this action or access this object, or the object does not exist at all.

The client request may have been valid but the client does not have permission to access the requested resource or perform the requested action.

403 Forbidden also used when objects don't exist

In most cases, the system will not return a 404 Not Found error response; it returns 403 Forbidden both when the object doesn't exist at all, and also when it exists but the client does not have permission to access it. This is a security measure to prevent unauthorized users from determining whether an object exists or not.

See also Core Concepts#Error Responses.

404

Not found - the requested resource could not be found or does not exist. This may also include cases where the resource does exist, but the client does not have permission to access that resource.

403 Forbidden also used when objects don't exist

In most cases, the system will not return a 404 Not Found error response; it returns 403 Forbidden both when the object doesn't exist at all, and also when it exists but the client does not have permission to access it. This is a security measure to prevent unauthorized users from determining whether an object exists or not.

See also Core Concepts#Error Responses.

500

Internal server error; an unexpected error occurred on the server. This could be due to a temporary condition or might be the result of a bug in the server software. Also, in some cases, an incorrect client input can trigger this error, and can be resolved by correcting the input.

If the error persists, please contact support along along with the following details when possible:

• any error messages received from the server
• the full request and response details (full headers and body)
• a description of the steps that led to the error
• the time range when it occurred.

503

Service unavailable - the server is currently unable to handle the request, usually due to maintenance activity on the server. Check if the server's web interface is currently available, or try again later.