{ "components": { "securitySchemes": { "BearerAuth": { "bearerFormat": "dj_\u003capikey\u003e", "description": "API key issued from Dashboard → Settings → API Access", "scheme": "bearer", "type": "http" } } }, "info": { "contact": { "email": "developers@dynamitejobs.com", "name": "DJ Developer Support", "url": "https://dynamitejobs.com/developers/" }, "description": "Programmatic API for **Dynamite Jobs** customer companies — manage your jobs, triage applications, score candidates, pull analytics, and check billing without leaving your tools.\n\nThis API powers the [official Python client](https://pypi.org/project/dynamitejobs/) (`pip install dynamitejobs`) which exposes the same surface as an Agent Skill, CLI, library, and MCP server.\n\n---\n\n## Connect to Claude \u0026 other AI apps (hosted MCP)\n\nThis API is also a hosted [MCP](https://modelcontextprotocol.io) server — add it as a connector in Claude, ChatGPT, Cursor, or any MCP-compatible app and your assistant can read and act on your Dynamite Jobs company data directly: jobs, applications, candidates, analytics, and billing. **No install.** When prompted, **sign in with your DJ account** (one-click OAuth) — or paste a `dj_` API key. Every endpoint below is exposed as a tool.\n\n**Connector URL** (Streamable HTTP): `https://api.dynamitejobs.com/mcp`\n\n- **Claude Code:** `claude mcp add --transport http dj https://api.dynamitejobs.com/mcp`\n- **Cursor, ChatGPT \u0026 other MCP apps:** add a custom / remote MCP connector pointing at the URL above (Streamable HTTP). Discovery is published at `/.well-known/mcp.json`.\n- **Local process:** run the official client as an MCP server — `pipx run dj --mcp` (`pip install dynamitejobs`).\n\n---\n\n## What this is for\n\n- **Build your own ATS workflow.** Pull today's new applicants into your tracker, push status changes back, sync notes.\n- **Score \u0026 rank candidates.** Fetch full candidate profiles for applications on your jobs, score them in your model, write the status back.\n- **Pull dashboards \u0026 funnel reports.** Aggregate views, applications-per-job, source breakdowns — same numbers the dashboard shows.\n- **Automate job posting.** Draft a job, push it as a free trial, then upgrade to a paid posting when billing-from-API ships.\n- **Stay in tools you already use.** Wire into Claude, Codex, Cursor, ChatGPT (via MCP), Zapier, your internal scripts.\n\n## Not for\n\n- **Scraping the public board.** All endpoints are scoped to *your* company. Public job listings live at [dynamitejobs.com/remote-jobs](https://dynamitejobs.com/remote-jobs/) and have no API surface — use that site directly.\n- **Cold-emailing candidates.** Candidate endpoints only return profiles attached to applications on *your* jobs. The DJ talent pool is not browsable via this API.\n- **Cross-company access.** Each API key is bound to one company; the server rejects any request that would read or write another company's data.\n\n## Rate limits\n\nLimits are tier-based, per API key. New companies start on the **trial** tier; posting paid jobs and DJ plans lift you to higher tiers automatically:\n\n| Tier | Per minute | Per day |\n|---|---|---|\n| trial (default) | 5 | 100 |\n| standard | 30 | 1,500 |\n| business-pro | 120 | 10,000 |\n| partner | 300 | 30,000 |\n\nEvery endpoint is billed at 1 request each; the SDK respects `Retry-After` on 429 automatically.\n\nNeed a higher cap? Email developers@dynamitejobs.com — most ATS-integration workloads fit inside a standard tier, but we'll raise limits for legitimate use cases.\n\nCheck your remaining budget with `GET /limits` — returns `per_minute_limit`/`per_minute_used` and `per_day_limit`/`per_day_used`.\n\n---\n\n## DJ workflow recipes\n\nEight common end-to-end flows. Each is one to three calls.\n\n### 1. List your jobs, ranked by applications\n\n```\nGET /jobs?status=published\u0026limit=100\nGET /analytics/jobs\n```\nMerge on `jobID` and sort by `applicationsCount`. Use this as the homepage of your custom dashboard.\n\n### 2. Triage a job's new applicants\n\n```\nGET /jobs/{jobID}/applications?status=not-reviewed\u0026limit=100\n```\nReturns the `not-reviewed` applications for one job (applications are scoped per job — there is no cross-job applicant feed). Pipe each `applicationID` into your scoring model, then `PATCH /applications/{id}?jobId={jobID}` with the new `status`.\n\n### 3. Page through applications for one job\n\n```\nGET /jobs/{jobID}/applications?limit=100\nGET /jobs/{jobID}/applications?limit=100\u0026cursor={cursor-from-previous-response}\n...\n```\nWalk pages using the `cursor` returned by each response; stop when `cursor` is empty. Each item includes the `candidateID` — pull the full candidate via `GET /candidate/{candidateID}` if you need resume / skills.\n\n### 4. Update status + notes after an interview\n\n```\nPATCH /applications/{applicationID}\n{\n \"status\": \"interested\",\n \"candidateNotesText\": \"Strong on backend Go. Offered next round on Thursday.\"\n}\n```\nNotes accept either `candidateNotesText` (plain) or `candidateNotesHTML` (rich, server-sanitised) — whichever your tool produces. Status enum: `not-reviewed`, `good-fit`, `interested`, `declined`, `filtered`.\n\n### 5. Check funnel + per-job analytics\n\n```\nGET /analytics/funnel?from=2026-05-01\u0026to=2026-05-31\nGET /analytics/jobs?from=2026-05-01\u0026to=2026-05-31\n```\nFunnel = impressions → views → applications → hires across all jobs. Jobs = same metrics broken down by `jobID`.\n\n### 6. Trial-post a job\n\n```\nPOST /jobs/trial\n{ \"title\": \"Senior Backend Engineer (Go)\", \"description\": \"...\", \"category\": \"development\" }\n```\nCreates a free 7-day trial post. Use this to sanity-check the surface before wiring up paid posting (gated behind a feature flag until billing-from-API ships).\n\n### 7. Check your tier and what's left this minute\n\n```\nGET /limits\nGET /billing/status\n```\n`/limits` returns `per_minute_used` / `per_day_used` against your tier caps. `/billing/status` returns whether a payment method is on file and your recent API charge activity.\n\n### 8. Sync the canonical company profile\n\n```\nGET /company\nPATCH /company\n{ \"description\": \"We build async-first product teams.\", \"links\": [{ \"kind\": \"cw\", \"name\": \"Website\", \"url\": \"https://acme.com\" }] }\n```\nEditable fields: `name`, `description`, `industryName`, `industrySlug`, `links`, `icon`, `photo`. The fields here flow through to every job posting's company embed.\n\n---\n\n## Discoverability tip for LLM agents\n\n- **Pagination** — list endpoints accept `limit` (default 25, max 100) and return an opaque `cursor`; pass it back as `?cursor=` for the next page. Stop when the returned `cursor` is empty.\n- **Idempotency** — `PATCH` calls are idempotent. Re-sending the same body is safe; status will end up the same regardless of how many times you fire it.\n- **Timestamps** — every `*At` field is ISO 8601 UTC (`2026-06-01T14:32:00Z`). Query params accept either ISO 8601 or unix seconds; the server normalises.\n- **Status ordering** — application statuses are ranked in the dashboard via `statusOrder` (see the response schema). Use that field instead of hardcoding an enum order in your client — the canonical order can shift.\n- **IDs** — every resource ID is URL-safe and case-sensitive. Don't trim or URL-decode them.\n- **Auth** — bearer token in the `Authorization` header. Issue keys from your dashboard at *Settings → API Access*; rotate any leaked key from the same screen.\n\n---\n\n## Conventions\n\n- **URL paths**: kebab-case (`/analytics/funnel`).\n- **JSON fields**: camelCase (`createdAt`, `candidateNotesText`).\n- **All times in UTC**, ISO 8601 with `Z` suffix.\n- **All currency in USD**, integer cents where applicable.\n- **Errors**: structured JSON `{ \"error\": { \"code\": \"...\", \"message\": \"...\" } }` with appropriate HTTP status.\n", "title": "Dynamite Jobs — Company API", "version": "1.2.8" }, "openapi": "3.0.3", "paths": { "/analytics/funnel": { "get": { "description": "Aggregates the same dashboard analytics rows returned by /analytics/jobs into a company-level current funnel. Use ?status=published to include only currently published jobs, or ?status=all/default to include every company job. Date filters are not supported — this endpoint reads precomputed current-total aggregates, not a windowed event scan.", "responses": { "200": { "content": { "application/json": { "example": { "funnel": [ { "count": 1234, "stage": "views" }, { "count": 210, "stage": "clicks" }, { "count": 42, "stage": "applies" }, { "count": 34, "stage": "reviewed" }, { "count": 6, "stage": "good_fit" }, { "count": 5, "stage": "interested" }, { "count": 12, "stage": "declined" }, { "count": 4, "stage": "filtered" } ], "scope": "published", "source": "precomputed aggregates (same source as the dashboard)" } } }, "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Company-wide funnel — views → clicks → applies → reviewed → goodFit/interested/declined", "tags": [ "analytics" ] } }, "/analytics/jobs": { "get": { "description": "Returns one row per job in your company with the same current aggregate numbers shown in the dashboard: lifetime views, clicks (apply-button clicks before the form), applications, and per-status application counts. The `prevViews`, `prevClicks`, and `applications.prev` fields are the dashboard's previous-24-hour comparison fields. **Date filters are not supported** — the source is a precomputed current-total aggregate, not a windowed event query.\n\n**Rate limits:** Counts as 1 request. Cheap read — backed by precomputed aggregates.", "parameters": [ { "description": "Limit the result set to a job-status group.", "example": "published", "in": "query", "name": "status", "required": false, "schema": { "default": "all", "enum": [ "all", "published" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "currently-live-job-performance": { "description": "Pull dashboards for only-published jobs.", "summary": "Currently-live job performance", "value": { "jobs": [ { "applications": { "declined": 12, "filtered": 4, "goodFit": 6, "interested": 5, "notReviewed": 8, "prev": 3, "total": 42 }, "clicks": 210, "jobId": "job_abc123", "prevClicks": 14, "prevViews": 87, "status": "published", "title": "Customer Success Manager", "views": 1234 } ], "scope": "published", "source": "precomputed aggregates (same source as the dashboard)", "totals": { "applications": { "declined": 12, "filtered": 4, "goodFit": 6, "interested": 5, "notReviewed": 8, "prev": 3, "total": 42 }, "clicks": 210, "prevClicks": 14, "prevViews": 87, "views": 1234 } } } }, "schema": { "properties": { "jobs": { "description": "One row per matching job.", "items": { "properties": { "applications": { "description": "Application counters keyed by ATS status.", "properties": { "declined": { "type": "number" }, "filtered": { "type": "number" }, "goodFit": { "type": "number" }, "interested": { "type": "number" }, "notReviewed": { "type": "number" }, "prev": { "description": "Applications in the previous 24h window.", "type": "number" }, "total": { "type": "number" } }, "type": "object" }, "clicks": { "description": "Apply-button clicks before the form.", "type": "number" }, "jobId": { "description": "Job ID.", "type": "string" }, "prevClicks": { "description": "Clicks in the previous 24h window.", "type": "number" }, "prevViews": { "description": "Views in the previous 24h window (dashboard comparison).", "type": "number" }, "status": { "description": "Job status.", "type": "string" }, "title": { "description": "Job title.", "type": "string" }, "views": { "description": "Lifetime page views.", "type": "number" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Per-job metrics — views, clicks, applies, per-status application counts", "tags": [ "analytics" ] } }, "/applications/{applicationID}": { "get": { "description": "Returns one application document plus the company-side meta row. Provide ?jobId=... because application IDs are candidate UIDs scoped under a job. Only completed applications are accessible. The application object contains the submitted form, answers, and PDF resume link at applyForm.resume.pubUrl when present. The meta object contains dashboard state such as status, statusOrder, candidateNotesText, and candidateNotesHTML. Companion to GET /candidate/{uid}, which returns the candidate's profile details after the same applicant ownership check.", "parameters": [ { "description": "The application ID (== candidate UID scoped under the job).", "example": "user_alice", "in": "path", "name": "applicationID", "required": true, "schema": { "type": "string" } }, { "description": "The job the application belongs to (application IDs are scoped per job).", "example": "job_abc123", "in": "query", "name": "jobId", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "example": { "application": { "applyForm": { "answers": { "custom-question-1": "I have five years of remote customer success experience.", "default-question-linkedin": "https://linkedin.com/in/jane-candidate", "default-question-salary": "$5,000 - $7,000 / month", "email": "jane@example.com" }, "resume": { "name": "jane-candidate-resume.pdf", "pubUrl": "https://firebasestorage.googleapis.com/.../resume.pdf" } }, "id": "candidate_uid_123", "jobId": "job_abc123", "profileId": "candidate_uid_123" }, "meta": { "candidateNotesHTML": "\u003cp\u003eStrong SaaS background; schedule interview.\u003c/p\u003e", "candidateNotesText": "Strong SaaS background; schedule interview.", "id": "candidate_uid_123", "jobId": "job_abc123", "status": "good-fit", "statusOrder": 4 } } } }, "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Read a single application + answers", "tags": [ "applications" ] }, "patch": { "description": "Partial-update on the dashboard application meta row. Editable fields: `status`, `candidateNotesText`, `candidateNotesHTML`. Setting `status=filtered` is equivalent to the dashboard's internal 'Not Matching' / 'refined' state. Status transitions are not restricted — you can move an applicant back to `not-reviewed` after the fact. Audit-logged. **There is no 1-5 candidate rating feature** in the DJ dashboard or this API; previous client versions that sent `rating` will be rejected with `field_not_editable`.\n\n**Rate limits:** Idempotent — re-sending the same body is safe.", "parameters": [ { "description": "The application ID (== candidate UID scoped under the job).", "example": "user_alice", "in": "path", "name": "applicationID", "required": true, "schema": { "type": "string" } }, { "description": "The job the application belongs to (application IDs are scoped per job).", "example": "job_abc123", "in": "query", "name": "jobId", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "examples": { "mark-applicant-as-interested-after-interview": { "description": "Standard ATS write after a screening call.", "summary": "Mark applicant as interested after interview", "value": { "candidateNotesText": "Strong on backend Go. Offered next round on Thursday.", "status": "interested" } }, "move-applicant-back-to-not-reviewed": { "description": "Status transitions are not restricted — re-triage is allowed.", "summary": "Move applicant back to not-reviewed", "value": { "status": "not-reviewed" } } }, "schema": { "properties": { "candidateNotesHTML": { "description": "Rich-text internal notes. Sent by editors that produce sanitised HTML.", "type": "string" }, "candidateNotesText": { "description": "Plain-text internal notes. Sent by tools that don't produce HTML.", "type": "string" }, "status": { "description": "New ATS status.", "enum": [ "not-reviewed", "good-fit", "interested", "declined", "filtered" ], "example": "interested", "type": "string" } }, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "examples": { "mark-applicant-as-interested-after-interview": { "description": "Standard ATS write after a screening call.", "summary": "Mark applicant as interested after interview", "value": { "updated": { "candidateNotesHTML": "\u003cp\u003eStrong SaaS background; schedule interview.\u003c/p\u003e", "candidateNotesText": "Strong SaaS background; schedule interview.", "status": "good-fit", "statusOrder": 4, "update": true, "updatedAt": "2026-05-27T05:20:00Z", "updatedByKey": "key_abc123", "updatedVia": "company-api" } } }, "move-applicant-back-to-not-reviewed": { "description": "Status transitions are not restricted — re-triage is allowed.", "summary": "Move applicant back to not-reviewed", "value": { "updated": { "candidateNotesHTML": "\u003cp\u003eStrong SaaS background; schedule interview.\u003c/p\u003e", "candidateNotesText": "Strong SaaS background; schedule interview.", "status": "good-fit", "statusOrder": 4, "update": true, "updatedAt": "2026-05-27T05:20:00Z", "updatedByKey": "key_abc123", "updatedVia": "company-api" } } } }, "schema": { "properties": { "id": { "description": "The applicationID that was updated.", "type": "string" }, "status": { "description": "The status that's now persisted.", "type": "string" }, "updated": { "description": "Always true on success.", "type": "boolean" }, "updatedByKey": { "description": "Fingerprint (`key_\u003c12-hex\u003e`) of the API key that wrote the change. Never the raw token.", "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Update status or internal candidate notes", "tags": [ "applications" ] } }, "/billing/status": { "get": { "description": "Returns whether your company has a Stripe customer/card on file, your resolved API tier (trial / standard / business-pro / partner), and recent API-initiated billing audit rows if any exist. Paid publish/repromote endpoints are not public in this release, so this endpoint is informational and useful for dashboard parity rather than a prerequisite for any active Company API write.", "responses": { "200": { "content": { "application/json": { "example": { "company_id": "company_123", "has_card_on_file": true, "plan_tier": "standard", "recent_api_charges": [], "recent_api_charges_note": "Last 30d, surfaced from apiAudit. Full charge details available via Stripe customer dashboard." } } }, "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Card-on-file status, plan tier, recent API charges", "tags": [ "billing" ] } }, "/candidate/{uid}": { "get": { "description": "Returns hiring-relevant DJ candidate profile details for a user who applied to one of your company's jobs. Access is scoped: the candidate must have an application under one of your jobs, otherwise the API returns 403. There is no general 'browse all candidates' endpoint. The response is an explicit public allowlist: name, location, work and education history, languages, skills, salary preference, links, profile image, categories, and resume.pubUrl when the candidate has a PDF resume on their profile. Use GET /applications/{applicationID}?jobId=... for the submitted form answers and application-specific resume.", "responses": { "200": { "content": { "application/json": { "example": { "candidate": { "edus": [ { "degree": "BA Communications", "school": "State University" } ], "id": "candidate_uid_123", "links": [ { "kind": "linkedin", "name": "LinkedIn", "url": "https://linkedin.com/in/jane-candidate" }, { "kind": "portfolio", "name": "Portfolio", "url": "https://jane.example.com" } ], "loc": { "countryCode": "US", "display": "Austin, United States", "utcOffset": -300 }, "name": { "display": "Jane Candidate", "slug": "jane-candidate" }, "photo": "https://cdn.dynamitejobs.com/profiles/candidate_uid_123/photo.jpg", "resume": { "name": "jane-candidate-resume.pdf", "pubUrl": "https://firebasestorage.googleapis.com/.../resume.pdf" }, "salary": { "currency": "USD", "from": 5000, "period": "month", "to": 7000 }, "skills": [ { "name": "Customer Success", "slug": "customer-success" } ], "xps": [ { "companyName": "Example SaaS", "description": "Led onboarding and retention for remote B2B customers.", "title": "Customer Success Manager" } ] } } } }, "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Read candidate profile (only if they applied to one of your jobs)", "tags": [ "candidates" ] } }, "/company": { "get": { "description": "Returns a curated public view of your company profile (explicit allowlist — internal/billing fields are never included): name, username/usernameLow, description, industryName/industrySlug, links, icon/photo, jobsMap, and owner/team metadata. The key is scoped to a single company; there is no companyID parameter.", "responses": { "200": { "content": { "application/json": { "example": { "company": { "description": "Example Co builds tools for remote teams.", "icon": { "sm": "https://cdn.dynamitejobs.com/companies/example/icon_128.png" }, "id": "company_123", "industryName": "Software", "links": [ { "kind": "cw", "name": "Website", "url": "https://example.com" } ], "name": { "display": "Example Co" }, "username": "example-co", "usernameLow": "example-co" } } } }, "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Read own company profile", "tags": [ "company" ] }, "patch": { "description": "Partial-update on the company profile using dashboard field names. Editable fields: name, description, industryName, industrySlug, links, icon, and photo. The API sets update=true so the company update task refreshes embedded company metadata on jobs and profile surfaces. Fields you cannot change via API include username/slug, owner/team, billing, jobsMap, brandMeta, disabled flags, redirectTo, and other internal/system fields.", "requestBody": { "content": { "application/json": { "example": { "description": "Example Co builds tools for remote teams.", "links": [ { "kind": "cw", "name": "Website", "url": "https://example.com" } ], "name": { "display": "Example Co" } } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "updated": { "description": "Example Co builds tools for remote teams.", "name": { "display": "Example Co" }, "update": true, "updatedByKey": "key_abc123", "updatedVia": "company-api" } } } }, "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Update permitted company fields", "tags": [ "company" ] } }, "/jobs": { "get": { "description": "Returns jobs owned by your company, scoped by the embedded company.id field used by the dashboard. Results are paginated and ordered by createdAt desc. There is no package/source filter and no global 'all jobs on DJ' endpoint — this endpoint is scoped to *your* company only.\n\n**Rate limits:** Counts as 1 request against the per-minute budget regardless of page size.", "parameters": [ { "description": "Filter by job status. Defaults to all statuses.", "example": "published", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "unpublished", "pending", "published", "expired", "finished", "fulfilled", "deleted", "rejected" ], "type": "string" } }, { "description": "Page size (max 100).", "example": "100", "in": "query", "name": "limit", "required": false, "schema": { "default": "25", "type": "number" } }, { "description": "Opaque cursor from the previous response. Walk pages until the returned cursor is empty.", "example": "job_abc123", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "currently-published-jobs": { "description": "Filter to live postings only.", "summary": "Currently published jobs", "value": { "count": 1, "cursor": "", "jobs": [ { "applicationsCount": 12, "applyType": "platform-form", "company": { "id": "company_123", "name": "Example Co", "username": "example-co" }, "featured": false, "id": "job_abc123", "isFeatured": false, "isPromoted": false, "slug": "senior-product-engineer", "status": "published", "title": "Senior Product Engineer" } ] } } }, "schema": { "properties": { "count": { "description": "Number of jobs in this page.", "type": "number" }, "cursor": { "description": "Pass as ?cursor= for the next page. Empty when the last page is reached.", "type": "string" }, "jobs": { "description": "Jobs owned by your company, newest first.", "items": { "properties": { "applicationsCount": { "description": "Total applications received.", "type": "number" }, "createdAt": { "description": "ISO 8601 creation timestamp.", "type": "string" }, "id": { "description": "Job ID.", "type": "string" }, "publishedAt": { "description": "ISO 8601 publish timestamp (null until published).", "type": "string" }, "status": { "description": "Current status.", "enum": [ "unpublished", "pending", "published", "expired", "finished", "fulfilled", "deleted", "rejected" ], "type": "string" }, "title": { "description": "Job title.", "type": "string" } }, "type": "object" }, "type": "array" } }, "type": "object" } } }, "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "List your company's jobs", "tags": [ "jobs" ] }, "post": { "description": "Creates a new job with status='unpublished', matching the dashboard's real draft state. There is no 'draft' status in DJ. The body uses dashboard field names such as title, description, descriptionHTML, locationSlugs, salary, skills, categories, type, applyType, applyLink, and form. The Company API sets the canonical embedded company map, source='user' for job processor compatibility, createdVia='company-api', update=true, and timestamps. package and addons cannot be set via the API. Paid publish/repromote endpoints are not public in this release; use the dashboard checkout flow or POST /jobs/trial for the one-time free trial post.", "requestBody": { "content": { "application/json": { "example": { "applyType": "platform-form", "categories": [ { "category": { "name": "Software Development", "slug": "software-development" }, "subcategory": { "name": "Full Stack", "slug": "full-stack" } } ], "description": "Build and improve our remote-first product with a small engineering team.", "descriptionHTML": "\u003cp\u003eBuild and improve our remote-first product with a small engineering team.\u003c/p\u003e", "form": { "questions": { "default-question-name": { "fieldType": "text", "id": "default-question-name", "label": "Name", "order": 1, "questionType": "platform", "required": true } }, "resumeUpload": true }, "locationSlugs": [ "worldwide" ], "primaryCategory": { "name": "Software Development", "slug": "software-development" }, "primarySubcategory": { "name": "Full Stack", "slug": "full-stack" }, "salary": { "currency": "USD", "from": 90000, "public": true, "to": 120000, "type": "yearly" }, "skillSlugs": [ "go", "vue", "firebase" ], "skills": [ { "name": "Go", "slug": "go" }, { "name": "Vue", "slug": "vue" }, { "name": "Firebase", "slug": "firebase" } ], "title": "Senior Product Engineer", "type": { "name": { "display": "Full Time" }, "slug": "full-time" } } } }, "required": true }, "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Create an unpublished job", "tags": [ "jobs" ] } }, "/jobs/trial": { "post": { "description": "One-shot free job post. Each company is allowed one trial post in its lifetime: a company that already has a trial post or any paid job history returns 409 with reason 'trial_not_eligible'. The post is scam-scanned and, if flagged, returns 403 'scam_scanner'. Otherwise it goes to status='pending' for DJ admin review. Same body field names as POST /jobs, with package forced to 'job-trial', source='user', createdVia='company-api-trial', and update=true.", "requestBody": { "content": { "application/json": { "example": { "applyType": "platform-form", "categories": [ { "category": { "name": "Software Development", "slug": "software-development" }, "subcategory": { "name": "Full Stack", "slug": "full-stack" } } ], "description": "Build and improve our remote-first product with a small engineering team.", "descriptionHTML": "\u003cp\u003eBuild and improve our remote-first product with a small engineering team.\u003c/p\u003e", "form": { "questions": { "default-question-name": { "fieldType": "text", "id": "default-question-name", "label": "Name", "order": 1, "questionType": "platform", "required": true } }, "resumeUpload": true }, "locationSlugs": [ "worldwide" ], "primaryCategory": { "name": "Software Development", "slug": "software-development" }, "primarySubcategory": { "name": "Full Stack", "slug": "full-stack" }, "salary": { "currency": "USD", "from": 90000, "public": true, "to": 120000, "type": "yearly" }, "skillSlugs": [ "go", "vue", "firebase" ], "skills": [ { "name": "Go", "slug": "go" }, { "name": "Vue", "slug": "vue" }, { "name": "Firebase", "slug": "firebase" } ], "title": "Senior Product Engineer", "type": { "name": { "display": "Full Time" }, "slug": "full-time" } } } }, "required": true }, "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Create + submit a trial post (free, 1 per company)", "tags": [ "jobs" ] } }, "/jobs/{jobID}": { "delete": { "description": "Drafts and pending submissions (status unpublished/pending) are soft-deleted (status='deleted'). A PUBLISHED job cannot be deleted via the API and returns 409 (cannot_delete_published) — publishing is a live posting and must be CLOSED in the dashboard (finished/fulfilled), never resurrected as a draft. Jobs in terminal states (expired, finished, fulfilled, rejected) also return 409. No hard delete is performed; the document and audit trail are preserved.", "responses": { "200": { "content": { "application/json": { "example": { "deleted": true, "id": "job_abc123", "status": "deleted" } } }, "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Delete a draft job", "tags": [ "jobs" ] }, "get": { "description": "Returns a curated public view of a job you own: title, slug, description/descriptionHTML, shortDescription, locationSlugs, salary, skills/skillSlugs, categories, primaryCategory/primarySubcategory, type, package, status, applyType/applyLink/form, faqs, video, labels, addons, dates (created/updated/published/expires/repromoted), derived isFeatured and isPromoted booleans, embedded company metadata, and applicationsCount. Internal/billing fields (charges, jobAmount, paid, raw flags, audit fields) are never returned. Returns 403 if the job belongs to another company and 404 if not found. Pair with GET /jobs/{jobID}/applications to enumerate applicants.", "responses": { "200": { "content": { "application/json": { "example": { "job": { "applicationsCount": 12, "applyType": "platform-form", "categories": [ { "category": { "name": "Software Development", "slug": "software-development" }, "subcategory": { "name": "Full Stack", "slug": "full-stack" } } ], "company": { "id": "company_123", "name": "Example Co", "username": "example-co" }, "description": "Build and improve our remote-first product with a small engineering team.", "descriptionHTML": "\u003cp\u003eBuild and improve our remote-first product with a small engineering team.\u003c/p\u003e", "featured": false, "form": { "questions": { "default-question-name": { "fieldType": "text", "id": "default-question-name", "label": "Name", "order": 1, "questionType": "platform", "required": true } }, "resumeUpload": true }, "id": "job_abc123", "isFeatured": false, "isPromoted": false, "locationSlugs": [ "worldwide" ], "primaryCategory": { "name": "Software Development", "slug": "software-development" }, "primarySubcategory": { "name": "Full Stack", "slug": "full-stack" }, "salary": { "currency": "USD", "from": 90000, "public": true, "to": 120000, "type": "yearly" }, "skillSlugs": [ "go", "vue", "firebase" ], "skills": [ { "name": "Go", "slug": "go" }, { "name": "Vue", "slug": "vue" }, { "name": "Firebase", "slug": "firebase" } ], "slug": "senior-product-engineer", "status": "published", "title": "Senior Product Engineer", "type": { "name": { "display": "Full Time" }, "slug": "full-time" } } } } }, "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Read a single job", "tags": [ "jobs" ] }, "patch": { "description": "Partial-update on a job. Unpublished jobs accept the same job-editor field names used by the dashboard. Published jobs are restricted to the dashboard's live-edit surface: title, description/descriptionHTML, shortDescription, salary, skills, categories, type, locations, apply process (applyType/applyLink/form), faqs, video, and labels (the company logo is not editable via the API). The API sets update=true so the same job processing, indexing, and ATS sync tasks run as dashboard edits. Locked/internal fields such as company, source, status, slug, package, addons, paid, charges, flags, analytics, and billing fields are not editable through PATCH.", "requestBody": { "content": { "application/json": { "example": { "description": "Updated role description...", "descriptionHTML": "\u003cp\u003eUpdated role description...\u003c/p\u003e", "salary": { "currency": "USD", "from": 90000, "public": true, "to": 120000, "type": "yearly" } } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "example": { "updated": { "description": "Updated role description...", "descriptionHTML": "\u003cp\u003eUpdated role description...\u003c/p\u003e", "salary": { "currency": "USD", "from": 90000, "public": true, "to": 120000, "type": "yearly" }, "update": true, "updatedVia": "company-api" } } } }, "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Edit a draft or restricted published-job fields", "tags": [ "jobs" ] } }, "/jobs/{jobID}/applications": { "get": { "description": "Returns application summaries for one job, using the same job-scoped dashboard collection the employer UI reads. There is no company-wide applicant browsing endpoint. Default results exclude `filtered` applications, matching the dashboard. The API status `filtered` maps to the dashboard's internal `refined` state. Application rows include denormalized candidate basics plus `applyForm.resume.pubUrl` when the candidate uploaded a PDF resume.\n\n**Rate limits:** 1 request per page. For large job pipelines, consider POST /jobs/{jobID}/applications/export instead.", "parameters": [ { "description": "The job's ID. Must belong to your company.", "example": "job_abc123", "in": "path", "name": "jobID", "required": true, "schema": { "type": "string" } }, { "description": "Comma-separated statuses to include.", "example": "not-reviewed,good-fit", "in": "query", "name": "status", "required": false, "schema": { "enum": [ "not-reviewed", "good-fit", "interested", "declined", "filtered" ], "type": "string" } }, { "description": "Show only this status (overrides default exclusion of `filtered`).", "example": "filtered", "in": "query", "name": "only", "required": false, "schema": { "enum": [ "not-reviewed", "good-fit", "interested", "declined", "filtered" ], "type": "string" } }, { "description": "Add `filtered` back into the default result set.", "example": "filtered", "in": "query", "name": "include", "required": false, "schema": { "type": "string" } }, { "description": "Comma-separated ISO country codes (lowercase).", "example": "us,gb", "in": "query", "name": "location", "required": false, "schema": { "type": "string" } }, { "description": "Salary band slug.", "example": "5k-10k", "in": "query", "name": "salary_range", "required": false, "schema": { "type": "string" } }, { "description": "Fuzzy text search across candidate name/email.", "example": "alice", "in": "query", "name": "text", "required": false, "schema": { "type": "string" } }, { "description": "Sort order. Defaults to dashboard order.", "example": "applied_desc", "in": "query", "name": "sort", "required": false, "schema": { "default": "status", "enum": [ "status", "applied_desc", "applied_asc", "salary_desc", "salary_asc" ], "type": "string" } }, { "description": "Page size (max 100).", "example": "100", "in": "query", "name": "limit", "required": false, "schema": { "default": "25", "type": "number" } }, { "description": "Opaque cursor returned by the previous page.", "example": "eyJsYXN0SUQiOiJhcHBfMTAwIn0=", "in": "query", "name": "cursor", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "examples": { "today-s-unreviewed-applicants": { "description": "Default dashboard view, scoped to one job.", "summary": "Today's unreviewed applicants", "value": { "applications": [ { "appliedAt": "2026-05-27T05:12:00Z", "applyForm": { "resume": { "name": "jane-candidate-resume.pdf", "pubUrl": "https://firebasestorage.googleapis.com/.../resume.pdf" } }, "id": "candidate_uid_123", "jobId": "job_abc123", "profile": { "id": "candidate_uid_123", "links": [ { "kind": "linkedin", "name": "LinkedIn", "url": "https://linkedin.com/in/jane-candidate" } ], "loc": { "countryCode": "US", "display": "Austin, United States", "utcOffset": -300 }, "name": { "display": "Jane Candidate", "slug": "jane-candidate" } }, "profileId": "candidate_uid_123", "status": "not-reviewed" } ], "count": 1, "cursor": "candidate_uid_123", "sort": "status" } } }, "schema": { "properties": { "applications": { "description": "Application summaries for this job.", "items": { "properties": { "appliedAt": { "description": "ISO 8601 timestamp the application was submitted.", "type": "string" }, "applyForm": { "description": "Submitted form data + resume URL.", "properties": { "resume": { "properties": { "pubUrl": { "description": "Public download URL for the candidate's PDF resume (empty when absent).", "type": "string" } }, "type": "object" } }, "type": "object" }, "candidate": { "description": "Denormalized candidate basics.", "properties": { "displayName": { "type": "string" }, "email": { "type": "string" }, "locationLabel": { "type": "string" } }, "type": "object" }, "candidateID": { "description": "Candidate UID. Pair with GET /candidate/{uid}.", "type": "string" }, "id": { "description": "Application ID (== candidate UID scoped under the job).", "type": "string" }, "status": { "description": "Current ATS status.", "enum": [ "not-reviewed", "good-fit", "interested", "declined", "filtered" ], "type": "string" }, "statusOrder": { "description": "Canonical dashboard sort weight — prefer over hardcoding a status order.", "type": "number" } }, "type": "object" }, "type": "array" }, "cursor": { "description": "Pass to the next request as `?cursor=`. Empty when the last page is reached.", "type": "string" } }, "type": "object" } } }, "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "List applications for one job", "tags": [ "applications" ] } }, "/jobs/{jobID}/applications/export": { "post": { "description": "Queues the same CSV export used by the DJ dashboard for one job's ATS applications. Body: { email: 'recipient@example.com' }. The CSV is generated asynchronously and emailed to the requested recipient; it includes status, candidate name, email, notes, applied date, location, salary expectations, resume URL, DJ profile URL, LinkedIn URL, and custom form answers. Returns 202 after the task is queued. The job must belong to the API key's company.", "requestBody": { "content": { "application/json": { "example": { "email": "hiring@example.com" } } }, "required": true }, "responses": { "202": { "content": { "application/json": { "example": { "email": "hiring@example.com", "jobId": "job_abc123", "queued": true } } }, "description": "CSV export task queued" }, "400": { "description": "Invalid request body or email" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "404": { "description": "Job not found" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Email a CSV export of job applications", "tags": [ "applications" ] } }, "/limits": { "get": { "description": "Returns your API key's currently-effective rate limits plus current usage. Limits are tier-based (trial / standard / business-pro / partner / admin-bypass) and surface in three windows: per-minute, per-hour, per-day. Every API response also carries this info inline via X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-RateLimit-Daily-Limit, X-RateLimit-Daily-Remaining headers — call this endpoint when you want a snapshot without making a real request, or to plan rate-aware retry/backoff strategies in your SDK.", "responses": { "200": { "description": "OK" }, "401": { "description": "Missing or invalid API key" }, "403": { "description": "Forbidden (key disabled or company disabled)" }, "429": { "description": "Rate limit exceeded" } }, "security": [ { "BearerAuth": null } ], "summary": "Effective rate limits + current usage", "tags": [ "limits" ] } } }, "security": [ { "BearerAuth": [] } ], "servers": [ { "description": "Production", "url": "https://api.dynamitejobs.com" } ], "tags": [ { "name": "analytics" }, { "name": "applications" }, { "name": "billing" }, { "name": "candidates" }, { "name": "company" }, { "name": "jobs" }, { "name": "limits" } ] }