Read a user
GEThttps://
Returns one user.
Access
- Token scope
- api:
read: users Without it:
403 insufficient-token-scope. - Permission
- users::
read Without it:
403 insufficient-permission. - Rate cost
- 1 unit, read bucket.
- Also
If-None-Matchanswers304when nothing changed. Never cached:private, no-store. Unknown query parameters are refused, never ignored.
Both are checked, scope first. A token never does more than its user. How access is checked
The detail view adds working_hours; everything else is in both views. A caller without users::read gets 404, never 403: a 403 on an id confirms the id exists, so the two answers would enumerate the organisation's people. A service account is 404 for the same reason it is absent from the list. A soft-deleted user is 404 unless you pass trashed=with; trashed=only returns a departed user and 404s a current one, which makes it an existence probe for a sync client and nothing else. There is no restore action on this resource, and reading a trashed row needs only users::read.
Path parameters
Query parameters
Unknown parameters are refused with 400, naming the parameter.
Request headers
A correlation id of your own. It is recorded in our logs next to the server's request id but never returned: the response header always carries the server's id. A value that does not match the pattern is discarded silently, never rejected.
Response 200
Returns a User in the detail view.
Headers
ETag- A strong validator of exactly this representation.
RateLimit- The IETF
httpapi-ratelimit-headersform of your remaining allowance on the tightest bucket this request touched. RateLimit-Policy- The ceiling and window of that bucket, as
<limit>;w=<seconds>. X-Request-Id- The server-generated ULID correlating this response with our logs.
Every response also carries Cache-Control, Vary, X-Content-Type-Options, X-Plnnrly-Api-Version, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Headers and versioning
Work email address, unique within the organisation. Searchable with ?q=, which is the practical way to resolve a person to an id.
The user's identifying colour, as a CSS colour string. Used by plnnrly's calendars and avatars; render it or ignore it.
The user's own IANA timezone, e.g. Europe/Amsterdam. Null means the organisation's default applies. Every timestamp in this API is UTC regardless; this is the zone a client renders them in for this person.
First day of employment, or null where it was never recorded. A calendar date with no clock, so it is never converted to UTC.
Share of available hours this person is expected to bill, 1 to 100, or null where no target is set. Read by the profitability report; a user without a target is still reported on, just not judged against one.
The contracted working week, one entry per shift, in week order. A weekday may carry several entries (a split day is two ranges), and a weekday that is not worked simply has none. Null or empty means no schedule has been recorded.
Where the user usually works on each weekday, keyed monday through sunday. The stored pattern lists only the days away from the office, so a weekday it does not name reads as office here. A single day's override from the agenda is not reflected.
Show 7 child fields
Soft-delete timestamp, null while the user is active.
Errors
8 errors every operation can return: 304, 400, 401, 404, 406, 429, 500, 503
304 Not modified.
400 Bad request.
idempotency-key-requiredinvalid-cursorinvalid-query-parametermalformed-requestunsupported-parameter
401 Unauthenticated.
404 Not found.
406 Not acceptable.
429 Too many requests.
500 Server error.
503 Service unavailable.
This path allows GET. Anything else answers 405.
Something wrong or missing on this page? Tell us