Positions

Authentication: All endpoints require an Authorization: Bearer <access token> header.

Most endpoints require an X-Company-ID: <company_id> header to scope requests to a specific company. This is the recommended header for most API operations.

Some endpoints require an X-Location-ID: <location_id> header when the query doesn't accept a locationId parameter.

See Authentication for details on how to obtain and use these headers.

Query Positions

Retrieve all positions configured for the company. Positions represent job roles or titles that employees can be assigned to within the organization.

Query Parameters:

This query takes no parameters and returns all positions configured for the company.

Response Fields:

Field	Description
`id`	Unique identifier for the position
`name`	Name of the position (e.g., "Full Stack Developer")
`description`	Description of the position
`alias`	Alternative name or abbreviation for the position
`location.id`	ID of the location this position belongs to (if location-specific)
`location.name`	Name of the location

For the complete Position type reference and all available fields, see the GraphQL Schema Reference.

Implementation Notes:

Positions can be company-wide or specific to a location
When location is null, the position is available across all locations
Positions are used in rostering, shift scheduling, and employee assignments
Position names are typically unique within a company for clarity

GraphQL Query

query Positions {
  positions {
    id
    name
    description
    alias
    location {
      id
      name
    }
  }
}

Example Variables

{}

Example Response

{
  "data": {
    "positions": [
      {
        "id": "18107",
        "name": "Administrator",
        "description": "Company Administrator",
        "alias": null,
        "location": null
      },
      {
        "id": "18099",
        "name": "CTO",
        "description": "CTO",
        "alias": null,
        "location": null
      },
      {
        "id": "18100",
        "name": "Full Stack Developer",
        "description": "Full Stack Developer",
        "alias": null,
        "location": null
      },
      {
        "id": "18101",
        "name": "General Manager",
        "description": "General Manager",
        "alias": null,
        "location": null
      },
      {
        "id": "18103",
        "name": "SQA",
        "description": "SQA",
        "alias": null,
        "location": null
      }
    ]
  }
}