Find posting IDs, assessment IDs, and bookable rounds in a hiring pipeline.

Roles and rounds

A posting is a role or cohort. A role's pipeline contains tracks and rounds. Use posting and round IDs to target the correct interview in your integration.

List roles

GET /api/v1/roles · Required scope: roles:read.

bash

curl --fail-with-body https://litmushiring.com/api/v1/roles \
  -H "Authorization: Bearer $LITMUS_API_KEY"

Returns:

json

{
  "roles": [
    {
      "id": "posting_abc123",
      "title": "Backend Engineer",
      "status": "open",
      "team": "Platform",
      "location": "Remote",
      "type": "full_time",
      "assessment_count": 2,
      "created_at": "2026-05-22T12:00:00.000Z"
    }
  ]
}

Returns 200 with all postings in the organization, including roles, cohorts, and closed postings, ordered newest first. Pass id as posting_id in subsequent requests. type is the employment type, such as full_time.

Read a role's pipeline

GET /api/v1/postings/{id}/pipeline · Required scope: roles:read or interviews:read.

bash

curl --fail-with-body https://litmushiring.com/api/v1/postings/posting_abc123/pipeline \
  -H "Authorization: Bearer $LITMUS_API_KEY"

Returns the role's stages in order, one list per track:

json

{
  "posting_id": "posting_abc123",
  "tracks": [
    {
      "id": "track_abc123",
      "name": "Engineering",
      "is_default": true,
      "steps": [
        {
          "round_id": "step_abc123",
          "type": "assessment",
          "title": "System design",
          "assessment_id": "asmt_ghi789",
          "delivery_mode": "sync",
          "duration_minutes": 60,
          "bookable": true
        },
        { "round_id": "step_def456", "type": "step", "title": "Debrief" }
      ]
    }
  ],
  "unstaged_assessments": []
}

round_id identifies a pipeline step within one track. Use the round in the candidate's track: the same assessment can have different round IDs in different tracks.

Field	Meaning
`type`	`assessment`, `group`, or `step`. Only assessment steps support booking.
`assessment_id`	The exercise used by the round. Pass this to `POST /invites`.
`delivery_mode`	`async` for a take-home, `sync` for a live interview, or `trial` for a work trial. Only `sync` supports interview booking.
`bookable`	Whether the assessment step has a stored round ID that the booking endpoint can resolve. Check this together with `delivery_mode: "sync"`.
`duration_minutes`	The configured calendar duration, defaulting to 60 minutes. This is separate from the assessment's working time limit.

Group steps include group_id, assignment_mode (random or self_select), and assessment_ids. They provide pipeline context and cannot be booked as interview rounds.

unstaged_assessments lists assessments attached to the posting without a pipeline round. They have no round_id. Configure and save a live round in the dashboard before booking it through the API. The same applies to steps with bookable: false.

A posting outside the key's organization returns 404.