Searches API - WallJobs AI Documentation

Execute AI-powered candidate searches via the API. Create saved searches and retrieve results.

Overview

The Searches API allows you to execute AI-powered candidate searches programmatically. Use natural language queries just like in the web interface to find matching candidates.

Credit Usage

Each search execution consumes 1 credit. Plan your API usage accordingly.

Execute Search

Execute an AI-powered search with a natural language query.

POST/v1/searches

Body Parameters

Name	Type	Required	Description
`query`	string	Required
`filters`	object	Optional
`limit`	integer	Optional	Default: `50`
`include_external`	boolean	Optional	Default: `false`

Request Example

curl -X POST "https://api.walljobs.com.br/v1/searches" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Senior React developer with 5+ years experience in São Paulo",
    "filters": {
      "remote": true,
      "experience_min": 5
    },
    "limit": 25
  }'

Response Example

{
  "data": {
    "search_id": "search_xyz789",
    "query": "Senior React developer with 5+ years experience in São Paulo",
    "results": [
      {
        "contact_id": "contact_abc123",
        "match_score": 95,
        "first_name": "Maria",
        "last_name": "Silva",
        "headline": "Senior Software Engineer",
        "company": "Tech Corp",
        "location": "São Paulo, Brazil",
        "skills": ["React", "TypeScript", "Node.js"],
        "match_reasons": [
          "5+ years React experience",
          "Located in São Paulo",
          "Senior-level position"
        ]
      },
      {
        "contact_id": "contact_def456",
        "match_score": 87,
        "first_name": "João",
        "last_name": "Santos",
        "headline": "Frontend Tech Lead",
        "company": "Startup Inc",
        "location": "São Paulo, Brazil",
        "skills": ["React", "Vue.js", "JavaScript"],
        "match_reasons": [
          "7 years frontend experience",
          "Located in São Paulo",
          "Tech lead experience"
        ]
      }
    ],
    "total_results": 2,
    "credits_consumed": 1,
    "executed_at": "2024-01-22T10:15:00Z"
  }
}

Filter Options

The filters object supports the following fields:

Field	Type	Description
`location`	string
`remote`	boolean
`experience_min`	integer
`experience_max`	integer
`skills`	array
`companies`	array

List Saved Searches

Retrieve all saved searches in the workspace.

GET/v1/searches/saved

Request Example

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

Response Example

{
  "data": [
    {
      "id": "saved_search_abc123",
      "name": "Senior React Developers",
      "query": "Senior React developer with 5+ years experience",
      "filters": {
        "remote": true
      },
      "created_at": "2024-01-15T10:00:00Z",
      "last_run_at": "2024-01-22T09:30:00Z"
    }
  ],
  "pagination": {
    "total": 5,
    "page": 1,
    "per_page": 20,
    "total_pages": 1
  }
}

Get Saved Search

Retrieve a specific saved search by ID.

GET/v1/searches/saved/:id

Request Example

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

Response Example

{
  "data": {
    "id": "saved_search_abc123",
    "name": "Senior React Developers",
    "query": "Senior React developer with 5+ years experience",
    "filters": {
      "remote": true,
      "experience_min": 5
    },
    "created_by": "user_xyz789",
    "created_at": "2024-01-15T10:00:00Z",
    "last_run_at": "2024-01-22T09:30:00Z",
    "run_count": 12
  }
}

Create Saved Search

Save a search for later reuse.

POST/v1/searches/saved

Body Parameters

Name	Type	Required
`name`	string	Required
`query`	string	Required
`filters`	object	Optional

Request Example

curl -X POST "https://api.walljobs.com.br/v1/searches/saved" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Engineers - Q1",
    "query": "Backend engineer with Python and AWS experience",
    "filters": {
      "experience_min": 3,
      "location": "Brazil"
    }
  }'

Response Example

{
  "data": {
    "id": "saved_search_def456",
    "name": "Backend Engineers - Q1",
    "query": "Backend engineer with Python and AWS experience",
    "filters": {
      "experience_min": 3,
      "location": "Brazil"
    },
    "created_at": "2024-01-22T11:00:00Z"
  }
}

Run Saved Search

To run a saved search, use the POST /v1/searches endpoint with the same query and filters. Saved searches don't consume credits when created, only when executed.

Delete Saved Search

Delete a saved search.

DELETE/v1/searches/saved/:id

Request Example

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

Response Example

{
  "data": {
    "id": "saved_search_abc123",
    "deleted": true
  }
}