Skip to main content
Workforce reads require workforce:read. A platform grant reads every homed row; an org-unit grant reads that unit and its descendants. An unhomed position is invisible. Missing and invisible get IDs both return 404. IDs stay in legacy space. Position assignments include assignment and worker IDs, nullable canonical personId, worker name and worker type. Position outputs exclude instructions, skills, tool permissions, governance overrides and billing data. These operations do not expose the raw worker/person directory; Get worker reads one worker seat, and People lists workers and reads and manages people at the platform scope. Lists default to 50 rows and take a limit of at most 100; a larger one is 400 too_big. Lists scan legacy IDs past rows the caller cannot see until a page holds limit visible rows or the source ends, so a page is short or empty only when it is the last page. Continue using meta.nextCursor while meta.hasMore is true. Cursors and non-empty IDs are opaque strings, and a cursor never names a row the caller cannot see. Customer organizations, the org units under them and positions homed in either are never returned: lists omit them, single reads answer 404 like a missing ID, and joins and counts never name them. Duplicate query keys, empty values, invalid limits and unknown status enums return 400. Component or enrichment faults remain server failures; successful absence alone becomes 404 or nullable enrichment.

Org-unit and position commands

Five commands change the org structure and require org:manage, which the credential’s scopes must reach. Because each answers a workforce read projection, the credential’s scopes must also reach workforce:read. Each needs org:manage and workforce:read at the home the Console checks: the platform scope for creating and moving org units, setting a position’s agent-assignable flag and its reporting edge, and the target org unit for creating a position. A grant below that home is 403. Each success answers the WorkforceOrgUnit or WorkforcePosition above. Customer organizations, the org units under them, positions homed in either and positions without an org unit are 404, like a missing ID. Every refusal the org structure’s own integrity rules would raise is decided first, as a 400 or 409, and writes nothing. Bodies are strict: head-of-unit, role and instructions are not machine inputs. Seating a person or agent in a position is a position assignment command. With an Idempotency-Key, a same-key retry within 24 hours returns the recorded result only while the caller still holds the same authority and can see the row; otherwise 409 idempotency_result_unavailable. If an outcome is unknown, repeat with the same key or read the row; never retry under a new key. Moving an org unit into another company also moves its seated agents’ agent_worker role: each agent seated in the moved unit or a unit under it gets the role at the new company root, and loses a role a seat gave at the old one that no other seat or its home company needs. A move inside one company changes no role.

Pods

Pod reads require workforce:read at the platform scope, as in the Console: a key or app whose grant covers only some org units receives 403. Pods managed by a customer organization or by an org unit under one are never returned; single reads answer 404, exactly as for a missing pod. Pod IDs are the IDs the Console uses; managingOrgUnitId and membership workerId are legacy IDs. Optional at (epoch milliseconds, default the request time) chooses which memberships count as effective. Roster workers carry worker and person IDs, name and type only. Outputs never include who created, updated, archived or verified a pod or membership, the archive reason, or manager resolution. listPods defaults limit to 25, its maximum (a larger one is 400 too_big), filters by status (active by default) and optional managingOrgUnitId, and continues by an opaque cursor that never names a pod the caller cannot see. listPodMembershipHistory defaults to 50 rows, clamps at 100, and continues by the decimal sequence in meta.nextCursor; any other cursor is 400. POST previewPodMembership previews one membership change as the Console does and changes nothing. It requires workforce:manage at the platform scope (mutating, never given to the built-in Apps), and the credential’s scopes must reach it. Validation refusals are 200 results with status: "blocked"; unknown pods and pods managed by or under a customer organization are 404. The result carries the worker’s ID, name and type but no person ID, and its overlapping memberships never name a pod you cannot see.

Assignment history

Assignment history requires workforce:read at the platform scope, as in the Console; a key or app whose grant covers only some org units receives 403. Pass workerId, positionId or both. Rows are the Console’s rows in the Console’s order, newest start first: assignment, worker and position IDs (legacy space), assignmentKind, startDate, optional endDate and supersededByAssignmentId, and the worker name, position title and org unit name. Who made an assignment, and why, is never returned. The whole history (at most 500 rows) arrives in one response without limit, or in pages of limit with cursor. Rows in a customer organization’s org unit or an org unit under one, or in no org unit, are omitted; a positionId the caller cannot see returns 404, and an unknown workerId returns an empty list. The position assignment commands create, change, end and reassign these rows. Seating an agent also gives it the agent_worker role (workflows:use, tools:read) at the company root of the position’s org unit, or at the platform scope for a system agent; ending the seat removes a role the seat gave, unless another of the agent’s seats or its home company still needs it. A seat whose end is dated in the future keeps the role until that end.

Position assignment commands

Four commands change position assignments as the Console’s people page does, and require org:manage, which the credential’s scopes must reach. Each needs org:manage and workforce:read at the platform scope (the Console’s home for these commands); a grant below it is 403. Because each answers assignment rows, the credential’s scopes must also reach workforce:read. Each takes a non-blank reason, recorded in the audit log with the calling key or app, and dates in epoch milliseconds. A success is the assignment history row (create and update), {assignment, outcome} (end; ALREADY_ENDED changes nothing) or {assignment, endedAssignment} (reassign; endedAssignment is null when no primary ended). Rows never name who made an assignment. A worker with any assignment that has not ended in a position in or under a customer organization, or without an org unit, a position homed in or under a customer organization or without an org unit, an assignment naming either, and a missing ID are 404 (Worker not found, Position not found, Assignment not found). Refusals end with the Console’s code in parentheses and write nothing: 400 (ASSIGNMENT_REASON_REQUIRED, INVALID_ASSIGNMENT_INTERVAL), 404 (MISSING_ASSIGNMENT_TARGET), 409 invalid_state (INACTIVE_ASSIGNMENT_TARGET), 409 conflict (AGENT_ASSIGNMENT_INCOMPATIBLE, PRIMARY_ASSIGNMENT_OVERLAP, PRIMARY_ASSIGNMENT_AMBIGUOUS, INVALID_ASSIGNMENT_SUPERSESSION) and 413 (INTEGRITY_ASSIGNMENT_LIMIT, past 500 assignments). The Console’s rule that an agent cannot manage a human worker is refused as 500, with nothing written. Seating and unseating agents moves their agent_worker role exactly as described under Assignment history. With an Idempotency-Key, a same-key retry within 24 hours returns the recorded result only while the caller still holds the same authority and can see every assignment the result names; otherwise 409 idempotency_result_unavailable, and the write never runs twice. Without one, a repeated create records a second assignment (or is refused as an overlapping primary), an update writes and audits again, an end answers ALREADY_ENDED, and a reassignment reassigns again.

Worker roles

The worker roles (Jobs) a position can carry, oldest first, in one response without limit, or in pages of limit with cursor, as the Console’s Jobs picker lists them: ID, roleId, name, description and the system and template flags. A role’s agent configuration and its author are never returned. Requires workforce:read at the platform scope; more than 500 roles is 413.

Pod membership writes

Membership writes require workforce:manage, reached by the credential’s scopes and held at the platform scope as in the Console; a key or app whose grant covers only some org units receives 403. Because every success returns the membership, the credential’s scopes must also include workforce:read; otherwise 403 naming workforce:read, and nothing is written. Built-in apps never receive workforce:manage. Each write runs the Console’s own command, so its UTC-day dates, person-capacity check, verification window and audit record are unchanged. Every body is exactly the command’s arguments; unknown fields return 400. expectedMembershipRevision is the pod’s current membershipRevision. A pod whose managing org unit is a customer organization or sits under one returns 404, exactly as a missing pod (the same rule as the org-unit and position commands). A refusal returns 400 (invalid allocation or dates, a missing correction reason), 404 (membership or worker seat not found) or 409 (overlap, capacity, stale revision, archived pod, ineligible seat, future-only or ended membership); its message ends with the Console’s code in parentheses, such as (POD_MEMBERSHIP_CAPACITY_EXCEEDED). Results never name who created, updated or verified a membership. With an Idempotency-Key, a same-key retry within 24 hours returns the recorded result while the caller’s scopes still include workforce:read, it still holds workforce:manage and the pod’s managing org unit is still outside every customer organization; otherwise 409 idempotency_result_unavailable. Pod-to-Customer assignments are below.

Pod lifecycle, ownership and internal profiles

Pod create, update and archive, and pod owner and internal delivery profile writes, use the same key workforce:manage (held at the platform scope) and the same rules as the membership writes: the credential’s scopes must also include workforce:read, each write runs the Console’s own command, and a refusal ends with the Console’s code in parentheses. A pod whose managing org unit is a customer organization or sits under one returns 404 exactly as a missing pod, and so does an owner assignment or internal profile of such a pod, or an ID that does not resolve. Creating a pod, or moving one, under a managing org unit that does not exist, is a customer organization or sits under one returns 404 ending (MANAGING_ORG_UNIT_NOT_FOUND). updatePod and archivePod take the pod’s updatedAt from Get pod as expectedUpdatedAt; a stale value returns 409 ending (POD_ROSTER_CHANGED). A move to another managing org unit needs a reason, and reason without a move returns 400 (POD_REASON_REQUIRED). Archiving ends the pod’s open memberships and records the reason in the audit; results never carry it. Owner and profile rows carry a revision; send it as expectedRevision. A pod’s owner intervals never overlap, and an internal profile cannot overlap another profile or any Customer assignment of the pod. Dates are UTC day boundaries; a change dated before today needs correctionReason. Results never name who created or updated a row. listPodOwners and listPodInternalProfiles require workforce:read at the platform scope and take podId, startsAt and endsAt (UTC day boundaries, at most 366 days apart) They return every row that overlaps the window, oldest first, paged with limit and cursor; more than 100 overlapping rows return 413 with error.code: "payload_too_large", never a truncated list. Owner rows carry the owner’s display name and whether the person is current, inactive or unresolved. With an Idempotency-Key, a same-key retry of any of these writes within 24 hours returns the recorded result under the same rule as the membership writes. Without a key, a repeat is refused by the command’s own name, revision or overlap check.

Pod Customer assignments

Pod-to-Customer assignment writes use the same key workforce:manage (held at the platform scope) and the same rules as the other pod writes: the credential’s scopes must also include workforce:read, each write runs the Console’s own command, and a refusal ends with the Console’s code in parentheses. The reads require workforce:read at the platform scope. No route needs customers:read: as in the Console, each Customer’s name, type and status are part of the Workforce answer. A pod whose managing org unit is a customer organization or sits under one returns 404 exactly as a missing pod, and so does any assignment of such a pod, or an assignment ID that does not resolve. An assignment gives an active Organization Customer allocationPercent (1–100) of a pod’s capacity from a UTC day, optionally split into delivery slices by delivery type, reporting category and stage. A Customer has at most one assignment to a pod at a time, a pod’s assignments never exceed 100% at any moment, and an assignment cannot overlap the pod’s internal profile. Rows carry a revision; send it as expectedRevision. A change dated before today needs correctionReason; only an assignment that has not started can be edited with updateFuturePodCustomerAssignment or deleted. Confirming accuracy moves the verification due date forward; reads report each row’s verification as current or stale. Results never name who created, updated or verified a row. POST previewPodCustomerAssignment previews one assign, change-effective, update-future or end operation as the Console does and changes nothing; refusals are 200 results with status: "blocked". It takes no Idempotency-Key. listPodCustomerAssignments (by podId) and listCustomerPodAssignments (by customerId) take startsAt and endsAt (UTC day boundaries, endsAt exclusive) and return the rows that overlap the window a page at a time, oldest effective end first: limit is 1–100 (default 100; a larger value is 400 too_big), and while meta.hasMore is true, meta.nextCursor passed as cursor with the same other parameters reads the next page. A Customer’s list omits assignments of pods managed by or under a customer organization without naming them. A row that starts after the window ends, or of such a pod, is left out after the read, so a page may hold fewer rows than limit, or none, while more remain. Neither answers 413 for a large window. listPodCustomerAssignmentHistory pages a pod’s assignments, latest effective end first: limit defaults to 20 and clamps at 50, and meta.nextCursor continues it; an unreadable cursor returns 400. With an Idempotency-Key, a same-key retry of any of these writes within 24 hours returns the recorded result under the same rule as the membership writes. Without a key, a repeat is refused by the command’s own revision or overlap check.

Worker detail

Get worker reads one worker seat by id: name, type, status, person ID, current position and its team and department. It requires workforce:read at the platform scope. It never returns the owner’s email, metadata, agent configuration, budget or spend. A worker with any current or upcoming assignment in a customer organization or an org unit under one returns 404, exactly as a missing worker.

People

People are not homed in an org unit, so every people operation is decided at the platform scope (Console parity): a grant that covers only some org units receives 403. A person reaches a machine caller only when none of their seats sits in a customer organization or an org unit under one; any other person, an unknown ID, or an ID merged into such a person returns 404 with the same message. Results never carry a person’s avatar URL, and audit rows name the calling credential. The person changes use the key workforce:manage (held at the platform scope) and, because each returns the person or its counts, the credential’s scopes must include workforce:read as well (otherwise 403 naming workforce:read, and nothing changes). Each runs the Console’s own command and ends a refusal with the Console’s code in parentheses, e.g. (PERSON_SEAT_TYPE_CONFLICT). A duplicate or email conflict names the other person (conflicting person <id>) only when that person is in reach. reason is required; for merge, offboard and reactivate it is 1–500 characters. Merge and offboard change people for good. A merge cannot be undone: there is no unmerge, the loser becomes an inactive redirect, and a role grant both people hold is kept once (the loser’s copy is deleted). Call Preview person merge first; it writes nothing and shows exactly what would move. An offboard is only partly reversible: reactivating restores the person and one seat, never claims, role grants, Personal keys or personal agents. Send an Idempotency-Key with both. Get person and List workers require workforce:read at the platform scope. A person includes every human seat with its monthly budget and spend; the worker list never returns email, metadata, agent configuration, budget or spend, and leaves out workers seated in a customer organization and every seat of a person with any such seat. Update worker seat sets a human seat’s monthly budget under org:manage (with workforce:read, both at the platform scope) and records it on the person’s history. With an Idempotency-Key, a same-key retry within 24 hours returns the recorded result only while your scopes still include workforce:read, you still hold the route’s authority at the platform scope, and every person the result names is still in reach; otherwise 409 idempotency_result_unavailable (see Idempotency). Without a key, a create with no email makes a second person, an update writes again, a merge or reactivate returns 409, and an offboard returns alreadyInactive: true.

Identities, email claims and profiles

A person’s identity links, email claims and communication profile follow the People rules: each operation is decided at the platform scope, needs workforce:manage, and answers 404 Person not found for a person out of reach. Each change runs the Console’s own command and, because it returns the person’s record, the credential’s scopes must include workforce:read as well. WorkOS sign-in bindings are managed in the Console: linking or unlinking provider workos decides who signs in as the person, so these routes refuse it with 400. A Freshservice link names the synchronized Freshservice Knowledge source, the org unit it is homed at and the technician, and needs knowledge:read at that org unit as well, as in the Console. An identity never carries its email, a profile revision never names its editor, and an email claim’s origin shows as providerName (api or console). An email claim is sign-in relevant: the first verified sign-in with a claimed address binds an unbound person. Adding and revoking claims is recorded on the person’s history (the claim ID and the reason, never the address), and revoking a claim that is already revoked keeps its original revocation. With an Idempotency-Key, the five changes replay under the people rule.

Person history

List person audit events pages the audit events on a person’s history, newest first. A person’s record is a read about the person, so it requires audit:read and workforce:read at the platform scope, and the credential’s scopes must include both. It returns the event, its category, whether a person or a credential acted and when, and only the detail the Console’s person history shows (counts and the reason); never who acted, run or resource IDs, or before and after values. Every other single-resource audit read in Forge also requires audit:read.

Resourcing settings

The settings behind the resourcing views are platform rows with no per-record home, so each operation is decided at the platform scope (Console parity): a grant that covers only some org units receives 403. Reads need workforce:read; changes need workforce:manage, which built-in apps never receive. Because each change returns the written row, its credential’s scopes must include workforce:read as well (otherwise 403 naming workforce:read, and nothing changes). Dates are UTC midnight epoch milliseconds. The changes run the Console’s own commands and end every refusal with the Console’s code in parentheses. Results never name who created or updated a row, or who answered a bandwidth report. A same-key retry within 24 hours returns the recorded result only while your scopes still include workforce:read and you still hold workforce:manage at the platform scope; otherwise 409 idempotency_result_unavailable (see Idempotency).

Engineering resourcing snapshots

Three GET operations provide the Engineers, Pods and Customers planning perspectives and require workforce:read. The credential’s scopes must reach it, and its grants must hold it at platform scope; an org-unit-only grant receives 403. Each request requires startsAt, exclusive endsAt, and at, all UTC midnight epoch milliseconds. at must lie inside a window of at most 366 days. numItems defaults to 20 and must be an integer from 1 through 20. Continue with the opaque cursor from meta.nextCursor; it belongs to that exact window, evaluation date, filters and page size. Invalid or stale cursors, duplicate or unknown keys, empty values and invalid filters return 400. Bounded-source limits return 413 with error.code: "payload_too_large" and message ENGINEERING_PLANNING_LIMIT_EXCEEDED, never partial totals. The success envelope is {data, meta: {requestId, hasMore, nextCursor}}. data retains the planning page and its scope, isDone and continueCursor; Engineers also include summary, boundaries and matchingRows. Those values come from one authorized query snapshot. Engineer row query, mode and pagination do not change the pool summary. engineeringGroupId refines the pool; mode is all, available (default), opening, full, over or review, and minAvailable is 0–100 (default 0, positive capacity in available mode). Search matches names, never email. Pod and Customer requests accept query, podId, customerId, staffingOrgUnitId, deliveryType, categoryKey, and stage. Delivery types are msp, project, platform, and forward_deployed; stages are pre_deal and engaged. Filters multiply matching classification percentage points by membership percentages; they never convert a matching slice into the whole parent allocation. Partners remain distinct from the Gloo employee denominator. Available Engineer capacity is 100% minus all Pod commitments; Customer-unattributed capacity can include internal work. Over-allocation stays negative, and missing legacy percentages remain conservative 100% commitments. Customer-housed org units, their subtrees and their Pods are hidden before results, totals and cursors. An Engineer with any hidden Pod commitment anywhere in the reporting window is omitted rather than displayed as falsely available. Engineer scope.visibility is visible_employee_pool_all_commitments_visible; delivery scope is visible_pods. No global omitted or hidden count is returned. Customer pages cover Customers related to visible workforce assignments, not an unrestricted CRM directory. A restricted or unresolved owner display is null; ownership never increases Pod staffing. Historical source gaps remain coverage gaps, not verified bench. Outputs omit primary email, audit identities, unrestricted CRM fields, SOW, signatures, contracts and revenue evidence. Editing remains in Forge Console. Engineer rows emit optional capacityTimeline segments covering the selected window contiguously: {startsAt, endsAt, eligible, allocatedPercent, availablePercent}. Ends are exclusive. These values use authoritative eligibility and Pod commitments; negative availability indicates overallocation. Proven outside-scope time has eligible: false and zero availability. Historical time without employment evidence has null eligibility and availability. Current group labels describe at, while future transfers still affect the timeline. engineeringGroupId must select an effective configured Engineering unit or its known active descendant; invalid selections return 400 with ENGINEERING_PLANNING_INPUT_INVALID. Pod and Customer resourcing context emits optional staffingAffiliationCoverage with status (proven, incomplete, or historical_unproven) and unprovenFte. The latter is the portion of counted, filtered staffing whose worker identity or employer is unproven, bounded by the existing total staffing FTE. The existing Gloo/partner-and-other split keeps its arithmetic; unknown employer evidence never proves partner affiliation. Historical reports carry the qualifier even at zero FTE. Older responses may omit the field; clients should treat omission as unavailable evidence. Staffing-organization filters follow dated Position changes at each timeline boundary. Historical windows whose employment/organization context cannot be proven are refused with 400 bad_request and message ENGINEERING_STAFFING_HISTORY_UNPROVEN; they never return an attributed zero as proven coverage. Hidden or unknown staffing-organization selectors yield no matches, and hidden organization names/IDs are omitted from member affiliation.