REST API Reference
All endpoints are under https://worksignal.com/api/v1. All responses are JSON. Authentication required on every request.
Quick Post
Create, publish, and list a job in a single API call.
/quick_post
Creates a role, generates a career page job posting, and publishes everything live in one request. The fastest path from "we need to hire" to "job is live."
Request body
| Parameter | Type | Required | Description |
|---|---|---|---|
| role.title | string | required | Job title |
| role.department | string | optional | Department or team name |
| role.description | string | optional | Job description (used for posting if no job_posting.public_description) |
| role.location | string | optional | City, state, or "Remote" |
| role.remote_policy | string | optional | onsite, hybrid, or remote |
| role.salary_min | integer | optional | Annual salary minimum (USD) |
| role.salary_max | integer | optional | Annual salary maximum (USD) |
| job_posting | object | optional | Override public title, description, or requirements shown on the career page |
| publish | boolean | optional | Default: true. Set to false to create as draft. |
Response (201)
{
"role": {
"id": 42,
"title": "Senior Backend Engineer",
"status": "open",
"department": "Engineering"
},
"job_posting": {
"id": 15,
"title": "Senior Backend Engineer",
"slug": "senior-backend-engineer",
"published": true,
"public_url": "https://worksignal.com/careers/acme/jobs/senior-backend-engineer"
},
"career_portal_url": "https://worksignal.com/careers/acme"
}Roles
Roles represent open positions. Each role can have one job posting on your career page.
/roles
List all roles - Filter with ?status=open|draft|paused|closed
/roles
Create a draft role
/roles/:id
Role detail - Includes description, salary range, and job posting URL
/roles/:id
Update a role
/roles/:id/publish
Publish a draft role - Status: draft -> open
/roles/:id/pause
Pause an open role - Stops accepting new applications
/roles/:id
Close a role
/roles/:id/stats
Hiring stats - Applicant count, screens, pass rate, and average score
Job Postings
Job postings control what appears on your public career page. Each role has one job posting.
/job_postings
List all postings - Filter with ?published=true
/job_postings
Create a posting for a role - Body: { role_id, job_posting: { ... } }
/job_postings/:id
Update posting content - Title, description, requirements
/job_postings/:id/publish
Publish a draft posting
/job_postings/:id/unpublish
Take a posting offline
Candidates
Create, read, and advance candidates through your hiring pipeline.
/candidates
List candidates - Filter with ?role_id=42&stage=screening
/candidates/:id
Candidate detail - All applications, voice screens, and touchpoints
/candidates
Add a candidate manually - Body: { name, email, role_id? }. Include role_id to apply immediately
/candidates/:id
Update candidate info - name, email, phone, resume_url
/candidates/:id/advance
Advance to next stage - Body: { stage: "interview" }
/candidates/:id/reject
Reject candidate - Body: { reason, notes? }
/candidates/:id/hire
Mark as hired - Body: { start_date? }
/candidates/:id/invite_screen
Trigger a voice screen - Body: { role_id, scheduled_at? }
Voice Screens
Read-only access to AI voice screening results, transcripts, and scores.
/voice_screens
List screens - Filter with ?role_id=42&status=completed
/voice_screens/:id
Screen detail - Full transcript, AI-generated highlights, red flags, and scores
Channels
Post jobs to X (Twitter) and check WhatsApp connection status.
/channels
Channel status - X and WhatsApp connection status and current usage
/channels/x/post
Post a job to X - Body: { job_posting_id, style? } - style: professional, casual, or bold
/channels/x/posts
X post history - Engagement metrics: likes, retweets, replies, link clicks
Organization
Read your organization's plan info, usage, and career portal URL.
/organization
Plan info, limits, current usage, and career portal URL
Error responses
All errors return JSON with an error field:
{ "error": "Validation failed", "messages": ["Title can't be blank"] }| Status | Meaning |
|---|---|
| 401 | Invalid or missing API key |
| 403 | Not authorized for this resource |
| 404 | Resource not found |
| 422 | Validation failed - check the messages array |
| 429 | Rate limit exceeded (free tier: 100 requests/day) |