Candidates API - WallJobs AI Documentation

Create, read, update, and delete candidates. Search and filter your candidate database programmatically.

Overview

The Candidates API (also referred to as Contacts API) allows you to manage your candidate database programmatically. Create, read, update, and delete contacts, as well as trigger enrichment for additional data.

Note

All contacts endpoints require the X-Workspace-ID header to specify which workspace to operate on.

List Contacts

Retrieve a paginated list of contacts in the workspace.

GET/v1/contacts

Query Parameters

Name	Type	Required	Description
`page`	integer	Optional	Default: `1`
`per_page`	integer	Optional	Default: `20`
`search`	string	Optional
`tags`	string	Optional
`created_after`	string	Optional
`updated_after`	string	Optional

Request Example

curl "https://api.walljobs.com.br/v1/contacts?page=1&per_page=20" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123"

Response Example

{
  "data": [
    {
      "id": "contact_abc123",
      "first_name": "Maria",
      "last_name": "Silva",
      "email": "maria@example.com",
      "headline": "Senior Software Engineer",
      "company": "Tech Corp",
      "location": "São Paulo, Brazil",
      "tags": ["frontend", "senior"],
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-20T14:22:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

Get Contact

Retrieve a single contact by ID with full profile information.

GET/v1/contacts/:id

Request Example

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

Response Example

{
  "data": {
    "id": "contact_abc123",
    "first_name": "Maria",
    "last_name": "Silva",
    "email": "maria@example.com",
    "phone": "+5511999999999",
    "headline": "Senior Software Engineer",
    "company": "Tech Corp",
    "location": "São Paulo, Brazil",
    "linkedin_url": "https://linkedin.com/in/mariasilva",
    "github_url": "https://github.com/mariasilva",
    "skills": ["React", "TypeScript", "Node.js", "AWS"],
    "experience": [
      {
        "title": "Senior Software Engineer",
        "company": "Tech Corp",
        "start_date": "2022-01",
        "end_date": null,
        "current": true
      }
    ],
    "education": [
      {
        "degree": "Bachelor's in Computer Science",
        "institution": "USP",
        "graduation_year": 2018
      }
    ],
    "tags": ["frontend", "senior"],
    "notes": "Great candidate, strong React experience",
    "enriched_at": "2024-01-18T09:15:00Z",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-20T14:22:00Z"
  }
}

Create Contact

Create a new contact in the workspace.

POST/v1/contacts

Body Parameters

Name	Type	Required	Description
`first_name`	string	Required
`last_name`	string	Required
`email`	string	Optional
`phone`	string	Optional
`headline`	string	Optional
`company`	string	Optional
`location`	string	Optional
`linkedin_url`	string	Optional
`skills`	array	Optional
`tags`	array	Optional
`notes`	string	Optional
`auto_enrich`	boolean	Optional	Default: `false`

Request Example

curl -X POST "https://api.walljobs.com.br/v1/contacts" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "João",
    "last_name": "Santos",
    "email": "joao@example.com",
    "company": "Startup Inc",
    "skills": ["Python", "Django", "PostgreSQL"],
    "tags": ["backend"],
    "auto_enrich": true
  }'

Response Example

{
  "data": {
    "id": "contact_def456",
    "first_name": "João",
    "last_name": "Santos",
    "email": "joao@example.com",
    "company": "Startup Inc",
    "skills": ["Python", "Django", "PostgreSQL"],
    "tags": ["backend"],
    "created_at": "2024-01-21T16:45:00Z",
    "updated_at": "2024-01-21T16:45:00Z"
  }
}

Update Contact

Update an existing contact. Only include fields you want to change.

PATCH/v1/contacts/:id

Body Parameters

Name	Type	Required
`first_name`	string	Optional
`last_name`	string	Optional
`email`	string	Optional
`phone`	string	Optional
`headline`	string	Optional
`company`	string	Optional
`location`	string	Optional
`skills`	array	Optional
`tags`	array	Optional
`notes`	string	Optional

Request Example

curl -X PATCH "https://api.walljobs.com.br/v1/contacts/contact_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "headline": "Staff Software Engineer",
    "tags": ["frontend", "senior", "lead"]
  }'

Response Example

{
  "data": {
    "id": "contact_abc123",
    "first_name": "Maria",
    "last_name": "Silva",
    "headline": "Staff Software Engineer",
    "tags": ["frontend", "senior", "lead"],
    "updated_at": "2024-01-22T09:30:00Z"
  }
}

Delete Contact

Permanently delete a contact from the workspace.

DELETE/v1/contacts/:id

Request Example

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

Response Example

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

Permanent Deletion

Deleting a contact is permanent and cannot be undone. The contact will also be removed from all shortlists and sequences.

Enrich Contact

Trigger data enrichment for a contact to gather additional information.

POST/v1/contacts/:id/enrich

Request Example

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

Response Example

{
  "data": {
    "id": "contact_abc123",
    "enrichment_status": "processing",
    "credits_consumed": 2,
    "estimated_completion": "2024-01-22T09:35:00Z"
  }
}

Note

Enrichment is an asynchronous process. Use the GET /contacts/:id endpoint to check when enrichment is complete (look for the enriched_at field).