Projects and lists

How the three fit together

A project is a piece of hiring work. It contains lists, and each list holds memberships pointing at sourced profiles, each with a stage.

This is parallel to, and separate from, the applications pipeline. An applicant moves through a job’s pipeline_stages; a sourced candidate moves through a list’s stage. Do not try to reconcile the two into one funnel — they are different populations at different points in the process.

GET/projectslists:read

{
  "object": "list",
  "data": [
    {
      "object": "project",
      "id": "prj_7Kd2mXq4Rp8v",
      "workspace_id": "wsp_4Kd8sPm2Qx7L",
      "name": "Platform hiring — H2 2026",
      "description": "Backend and infra roles for the payments team.",
      "created_at": "2026-07-01T09:00:00.000Z",
      "updated_at": "2026-09-06T12:08:55.400Z",
      "links": {
        "self": "/api/partner/v1/projects/prj_7Kd2mXq4Rp8v",
        "lists": "/api/partner/v1/projects/prj_7Kd2mXq4Rp8v/lists"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

GET/projects/{project_handle}/listslists:read

The lists inside one project.

GET/listslists:read

Every candidate list in the workspace, including any not attached to a project — those carry project_id: null.

{
  "object": "list",
  "data": [
    {
      "object": "list",
      "id": "lst_3Rp8vKd2mXq4",
      "workspace_id": "wsp_4Kd8sPm2Qx7L",
      "project_id": "prj_7Kd2mXq4Rp8v",
      "name": "Staff engineers — Seoul",
      "description": null,
      "created_at": "2026-07-02T11:20:00.000Z",
      "updated_at": "2026-09-06T12:08:55.400Z",
      "links": {
        "self": "/api/partner/v1/lists/lst_3Rp8vKd2mXq4",
        "members": "/api/partner/v1/lists/lst_3Rp8vKd2mXq4/members"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Note the object on a row is "list", which is also the envelope’s object. The envelope is the outer one; the rows are candidate lists.

GET/lists/{list_handle}lists:read

One list, same shape as a row above.

GET/lists/{list_handle}/memberslists:read

Who is in the list and where they sit. A membership points at a sourced profile rather than embedding it — read the profile itself for the person’s data.

{
  "object": "list",
  "data": [
    {
      "object": "list_membership",
      "id": "mem_9Xj4kQd7Rm2s",
      "list_id": "lst_3Rp8vKd2mXq4",
      "sourced_profile_id": "cnd_8Fj3kLm2Qd7s",
      "stage": "contacted",
      "stage_updated_at": "2026-09-04T08:12:44.201Z",
      "added_at": "2026-08-19T07:41:02.115Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

stage_updated_at lets you compute time-in-stage without keeping your own history, and added_at is when the candidate entered the list. Both are RFC 3339 UTC.

Related events

list.created, list.updated, list.deleted, list_membership.added, list_membership.removed and list_membership.stage_changed, all under lists:read.

list_membership.removed counts as a deletion event: if you mirror memberships, it is the instruction to remove your copy of that row.