Shortlist API - WallJobs AI Documentation

Manage shortlists and pipeline stages programmatically. Add candidates, update status, and track progress.

Overview

The Shortlist API allows you to manage your candidate pipelines programmatically. Create shortlists, add candidates, and move them through pipeline stages.

List Shortlists

Retrieve all shortlists in the workspace.

GET/v1/shortlists

Query Parameters

Name	Type	Required	Description
`page`	integer	Optional	Default: `1`
`per_page`	integer	Optional	Default: `20`
`status`	string	Optional

Request Example

curl "https://api.walljobs.com.br/v1/shortlists" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123"

Response Example

{
  "data": [
    {
      "id": "shortlist_abc123",
      "name": "Senior Frontend Developer",
      "description": "Q1 2024 hiring for frontend team",
      "status": "active",
      "stages": [
        { "id": "stage_1", "name": "New", "order": 1, "count": 15 },
        { "id": "stage_2", "name": "Screening", "order": 2, "count": 8 },
        { "id": "stage_3", "name": "Interview", "order": 3, "count": 3 },
        { "id": "stage_4", "name": "Offer", "order": 4, "count": 1 },
        { "id": "stage_5", "name": "Hired", "order": 5, "count": 0 }
      ],
      "total_candidates": 27,
      "created_at": "2024-01-10T09:00:00Z",
      "updated_at": "2024-01-22T11:30:00Z"
    }
  ],
  "pagination": {
    "total": 3,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}

Get Shortlist

Retrieve a shortlist with all candidates organized by stage.

GET/v1/shortlists/:id

Query Parameters

Name	Type	Required	Description
`include_candidates`	boolean	Optional	Default: `true`

Request Example

curl "https://api.walljobs.com.br/v1/shortlists/shortlist_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123"

Response Example

{
  "data": {
    "id": "shortlist_abc123",
    "name": "Senior Frontend Developer",
    "description": "Q1 2024 hiring for frontend team",
    "status": "active",
    "stages": [
      {
        "id": "stage_1",
        "name": "New",
        "order": 1,
        "candidates": [
          {
            "id": "candidate_xyz789",
            "contact_id": "contact_abc123",
            "first_name": "Maria",
            "last_name": "Silva",
            "email": "maria@example.com",
            "headline": "Senior Software Engineer",
            "added_at": "2024-01-15T10:30:00Z",
            "stage_changed_at": "2024-01-15T10:30:00Z"
          }
        ]
      }
    ],
    "created_at": "2024-01-10T09:00:00Z"
  }
}

Create Shortlist

Create a new shortlist with custom pipeline stages.

POST/v1/shortlists

Body Parameters

Name	Type	Required
`name`	string	Required
`description`	string	Optional
`stages`	array	Optional

Request Example

curl -X POST "https://api.walljobs.com.br/v1/shortlists" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Engineer Q1",
    "description": "Backend team expansion",
    "stages": [
      { "name": "Applied", "order": 1 },
      { "name": "Phone Screen", "order": 2 },
      { "name": "Technical Interview", "order": 3 },
      { "name": "Onsite", "order": 4 },
      { "name": "Offer", "order": 5 },
      { "name": "Hired", "order": 6 }
    ]
  }'

Response Example

{
  "data": {
    "id": "shortlist_def456",
    "name": "Backend Engineer Q1",
    "description": "Backend team expansion",
    "status": "active",
    "stages": [
      { "id": "stage_1", "name": "Applied", "order": 1, "count": 0 },
      { "id": "stage_2", "name": "Phone Screen", "order": 2, "count": 0 },
      { "id": "stage_3", "name": "Technical Interview", "order": 3, "count": 0 },
      { "id": "stage_4", "name": "Onsite", "order": 4, "count": 0 },
      { "id": "stage_5", "name": "Offer", "order": 5, "count": 0 },
      { "id": "stage_6", "name": "Hired", "order": 6, "count": 0 }
    ],
    "created_at": "2024-01-22T12:00:00Z"
  }
}

Note

If you don't provide custom stages, the default stages (New, Screening, Interview, Offer, Hired, Rejected) will be used.

Add Candidate

Add a contact to a shortlist as a candidate.

POST/v1/shortlists/:id/candidates

Body Parameters

Name	Type	Required
`contact_id`	string	Required
`stage_id`	string	Optional
`note`	string	Optional

Request Example

curl -X POST "https://api.walljobs.com.br/v1/shortlists/shortlist_abc123/candidates" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": "contact_abc123",
    "stage_id": "stage_1",
    "note": "Strong React experience, referred by current employee"
  }'

Response Example

{
  "data": {
    "id": "candidate_xyz789",
    "contact_id": "contact_abc123",
    "shortlist_id": "shortlist_abc123",
    "stage_id": "stage_1",
    "note": "Strong React experience, referred by current employee",
    "added_at": "2024-01-22T12:30:00Z"
  }
}

Move Candidate

Move a candidate to a different pipeline stage.

PATCH/v1/shortlists/:id/candidates/:candidate_id

Body Parameters

Name	Type	Required	Description
`stage_id`	string	Optional
`note`	string	Optional

Request Example

curl -X PATCH "https://api.walljobs.com.br/v1/shortlists/shortlist_abc123/candidates/candidate_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "stage_id": "stage_3",
    "note": "Passed phone screen, scheduling technical interview"
  }'

Response Example

{
  "data": {
    "id": "candidate_xyz789",
    "contact_id": "contact_abc123",
    "shortlist_id": "shortlist_abc123",
    "stage_id": "stage_3",
    "previous_stage_id": "stage_1",
    "stage_changed_at": "2024-01-22T14:00:00Z",
    "note": "Passed phone screen, scheduling technical interview"
  }
}

Remove Candidate

Remove a candidate from a shortlist.

DELETE/v1/shortlists/:id/candidates/:candidate_id

Request Example

curl -X DELETE "https://api.walljobs.com.br/v1/shortlists/shortlist_abc123/candidates/candidate_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123"

Response Example

{
  "data": {
    "id": "candidate_xyz789",
    "removed": true
  }
}

Note

Removing a candidate from a shortlist doesn't delete the underlying contact. The contact remains in your database and can be added to other shortlists.