List users

GEThttps://<your-url>/api/v2/users

MCP id users.index

Returns the organisation's people, by name A→Z, the order plnnrly's user list uses.

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. view=detail makes it 3. Adds: q +2.
Also: If-None-Match answers 304 when 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

Request

Example: Find a colleague by name

curl -G \
  'https://<your-url>/api/v2/users' \
  --data-urlencode 'q=Jansen' \
  -H 'Authorization: Bearer <token>' \
  -H 'Accept: application/json'

const response = await fetch('https://<your-url>/api/v2/users?q=Jansen', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer <token>',
    'Accept': 'application/json',
  },
});

use Illuminate\Support\Facades\Http;

$response = Http::withToken('<token>')
    ->acceptJson()
    ->get('https://<your-url>/api/v2/users?q=Jansen');

import requests
response = requests.request(
    'GET',
    'https://<your-url>/api/v2/users?q=Jansen',
    headers={'Authorization': 'Bearer <token>', 'Accept': 'application/json'},
)

Response

The shape of the response, with sample values.

{
  "data": [
    {
      "id": 1,
      "name": "…",
      "email": "…",
      "color": "…",
      "job_title": "…",
      "phone_number": "…",
      "timezone": "…",
      "date_employed": "2026-03-04",
      "birthday": "2026-03-04",
      "profitability_target_percentage": 1,
      "created_at": "2026-03-04T09:15:00Z",
      "updated_at": "2026-03-04T09:15:00Z",
      "deleted_at": "2026-03-04T09:15:00Z",
      "links": {
        "…": "1 field of UserLinks"
      }
    }
  ],
  "meta": {
    "page": {
      "per_page": 1,
      "next_cursor": "…",
      "prev_cursor": "…",
      "total": 1,
      "current_page": 1,
      "last_page": 1
    }
  },
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1",
    "next": "https://<your-url>/api/v2/work-items/1",
    "prev": "https://<your-url>/api/v2/work-items/1"
  }
}

Search by name or email address with q, which is the practical way to resolve a colleague to the user_id every other collection filters on. Service accounts are never listed. Roles, permissions and teams are not part of this payload and no filter narrows by them. The working week is a detail-view field: send view=detail to get working_hours. ?include= is not accepted: this resource expands no relation, and company_branch in particular belongs to customers, not to users. Soft-deleted users are excluded by default; trashed=with includes them and trashed=only returns just the departed, which is how an incremental sync learns somebody left.

Query parameters

Unknown parameters are refused with 400, naming the parameter.

21 parameters in 6 groups

Views

viewstring

Which field set to render.

summarydefaultdetail

Pagination

per_pageinteger1 to 100

Rows per page. At most 25 when include names a to-many relation; a larger value is 400 invalid-query-parameter.

Default: 25

cursorstring

Opaque keyset cursor from a previous page's links.next. Never construct one by hand.

pageinteger1 to 1000

Opt in to page-number paging: 1-based, at most 1000. Omit it, the default, to page by opaque cursor, which is what links.next hands you. Cannot be combined with cursor. Published only on collections that count their rows on every request.

Filters

=: equals
[null]: true or false: whether it is empty
[gte][lte][lt]: at least, at most, less than

filter[birthday]date (YYYY-MM-DD)=[gte][lte][null]

Date of birth. null selects the users whose birthday was never recorded.

Whether the field is null.

filter[created_at]timestamp (YYYY-MM-DDThh:mm:ssZ)=[gte][lt]

Creation timestamp. Pair with sort=id for a stable full export.

filter[date_employed]date (YYYY-MM-DD)=[gte][lte][null]

First day of employment. null selects the users whose start date was never recorded.

Whether the field is null.

filter[updated_at]timestamp (YYYY-MM-DDThh:mm:ssZ)=[gte][lt]

Last-write timestamp. Use for incremental sync.

Search

qstring

Free-text search over name, email, in that order of relevance. At most one substring match per request: q together with a contains filter is 400 invalid-query-parameter.

Sorting

sortstring

Up to three keys, comma-separated, each optionally prefixed with - for descending.

Default: name

Key	Sorts by
`name`	Full name, A→Z, the order plnnrly's people list uses.
`date_employed`	First day of employment, earliest first; the users with none sort with the nulls.
`birthday`	Date of birth, oldest first; the users with none sort with the nulls.
`id`	Id, ascending. An id never changes, so use this for a stable full export.
`updated_at`	Last-write timestamp; pair with the id tiebreaker for sync.

Prefix a key with - for descending.

Other

trashedstring

Whether soft-deleted rows are included.

withoutdefaultwithonly

Request headers

X-Request-Idstringpattern

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.

If-None-Matchstring

The ETag a read is conditional on. A match is answered 304 with no body.

Response 200

Returns a page of UserList rows.

dataarray of UserList

The rows, each a UserList.

meta.pagePage

per_page, next_cursor, prev_cursor, total, current_page, last_page.

linksPageLinks

self, next, prev.

Each row is a UserList: 14 fields.

Headers

ETag: A weak validator (W/"…") of the rendered page.
RateLimit: The IETF httpapi-ratelimit-headers form 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

idinteger

Unique identifier.

namestring≤ 255

Full name as shown throughout plnnrly. Searchable with ?q=.

emailstring≤ 255

Work email address, unique within the organisation. Searchable with ?q=, which is the practical way to resolve a person to an id.

colorstring≤ 255

The user's identifying colour, as a CSS colour string. Used by plnnrly's calendars and avatars; render it or ignore it.

job_titlestring≤ 255

Job title, e.g. Project Manager.

phone_numberstring or null≤ 255

Phone number as entered, in no normalised format.

timezonestring or null≤ 255

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.

date_employeddate (YYYY-MM-DD) or null

First day of employment, or null where it was never recorded. A calendar date with no clock, so it is never converted to UTC.

birthdaydate (YYYY-MM-DD) or null

Date of birth, or null where it was never recorded.

profitability_target_percentageinteger or null

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.

working_hoursarray of object or nullDetail only

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.

work_locationsobjectDetail only

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

work_locations.mondaystring

Monday.

officeremoteclient

New values may be added.

work_locations.tuesdaystring

Tuesday.

officeremoteclient

New values may be added.

work_locations.wednesdaystring

Wednesday.

officeremoteclient

New values may be added.

work_locations.thursdaystring

Thursday.

officeremoteclient

New values may be added.

work_locations.fridaystring

Friday.

officeremoteclient

New values may be added.

work_locations.saturdaystring

Saturday.

officeremoteclient

New values may be added.

work_locations.sundaystring

Sunday.

officeremoteclient

New values may be added.

created_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Creation timestamp.

updated_attimestamp (YYYY-MM-DDThh:mm:ssZ)

Last-write timestamp; use for incremental sync.

deleted_attimestamp (YYYY-MM-DDThh:mm:ssZ) or null

Soft-delete timestamp, null while the user is active.

linksUserLinks

Show 1 child field

links.selfurl

The canonical URI of this record.

Errors

403 Forbidden.

forbidden-by-policy insufficient-permission insufficient-token-scope

8 errors every operation can return: 304, 400, 401, 404, 406, 429, 500, 503

304 Not modified.

400 Bad request.

idempotency-key-required invalid-cursor invalid-query-parameter malformed-request unsupported-parameter

401 Unauthenticated.

token-expired unauthenticated

404 Not found.

endpoint-not-found resource-not-found

406 Not acceptable.

not-acceptable

429 Too many requests.

rate-limit-exceeded

500 Server error.

internal-error

503 Service unavailable.

tenant-unavailable

This path allows GET. Anything else answers 405.

Something wrong or missing on this page? Tell us

Access

Query parameters

Views

Pagination

Filters

Search

Sorting

Other

Request headers

Response 200

Headers

Errors