API Overview

Introduction

The WallJobs AI REST API allows you to programmatically access and manage your recruiting data. Use the API to build custom integrations, automate workflows, or connect WallJobs AI with your existing tools.

The API follows RESTful conventions and uses standard HTTP methods:

• GET - Retrieve resources
• POST - Create new resources
• PUT - Update existing resources
• PATCH - Partially update resources
• DELETE - Remove resources

Base URL

All API requests should be made to:

https://api.walljobs.com.br/v1

The API is versioned in the URL. The current version is v1. We'll maintain backwards compatibility within a version and announce any breaking changes in advance.

Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header:

curl https://api.walljobs.com.br/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY"

Get your API key from Settings → API in the WallJobs AI dashboard. See the Authentication page for more details. Authentication

Rate Limits

API requests are rate limited to ensure fair usage and system stability:

Rate limit information is included in response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1699500000

If you exceed the rate limit, you'll receive a 429 Too Many Requests response. Wait for the reset time before retrying.

Request Format

Send request bodies as JSON with the appropriate content type header:

curl https://api.walljobs.com.br/v1/contacts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Maria",
    "last_name": "Silva",
    "email": "maria@example.com"
  }'

Response Format

All responses are returned as JSON. Successful responses include the requested data:

{
  "data": {
    "id": "contact_abc123",
    "first_name": "Maria",
    "last_name": "Silva",
    "email": "maria@example.com",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

List endpoints return an array with pagination metadata:

{
  "data": [
    { "id": "contact_abc123", ... },
    { "id": "contact_def456", ... }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

Error Handling

Errors are returned with appropriate HTTP status codes and a consistent JSON format:

{
  "error": {
    "code": "invalid_request",
    "message": "The email field is required",
    "details": {
      "field": "email",
      "reason": "required"
    }
  }
}

Common Status Codes

Pagination

List endpoints support pagination with the following query parameters:

• page - Page number (default: 1)
• per_page - Items per page (default: 20, max: 100)

curl "https://api.walljobs.com.br/v1/contacts?page=2&per_page=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use the pagination object in the response to navigate through pages and determine total results.