{ "openapi": "3.0.3", "info": { "title": "Bons Empregos Company API", "version": "1.0.0", "description": "Company-scoped integration. Bearer credentials issued at /developers/tokens. HTTPS only. Read scope includes jobs:read and reference:read; write adds jobs:write. Creation counts toward the existing plan quota. DELETE withdraws and preserves applications. 60 requests/minute/company; retry 429 after Retry-After seconds. Sandbox is available to verified main company accounts without a paid plan. It stores only isolated test jobs, has a capacity of 100 jobs until reset, simulates pending moderation, and does not send notifications or consume production quotas. Create a sandbox job before requesting production access from /developers/tokens. Admin approval is per company; test and live credentials are not interchangeable. Reset clears sandbox jobs and idempotency keys only. No automatic promotion to production. Administrators may grant complimentary production API and MCP access independently of a subscription, with a monthly posting limit (-1 unlimited) and optional expiry. Website plan benefits remain unchanged." }, "servers": [ { "url": "https://www.bonsempregos.com/api/sandbox/v1", "description": "Sandbox — be_test_ credentials, isolated test jobs" }, { "url": "https://www.bonsempregos.com/api/v1", "description": "Production — be_live_ credentials, administrator approval and eligible plan or complimentary access required" } ], "security": [ { "companyToken": [] } ], "paths": { "/account": { "get": { "summary": "Current plan and shared posting quota", "operationId": "get_account", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Account" } } } } } }, "default": { "description": "Error envelope. 400, 401, 403, 404, 409, 410, 413, 415, 422, 429 or 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "jobs:read" } }, "/categories": { "get": { "summary": "Active categories including parent_id", "operationId": "get_categories", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Category" } } } } } } }, "default": { "description": "Error envelope. 400, 401, 403, 404, 409, 410, 413, 415, 422, 429 or 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "reference:read" } }, "/regions": { "get": { "summary": "District and region IDs", "operationId": "get_regions", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } } } } } } }, "default": { "description": "Error envelope. 400, 401, 403, 404, 409, 410, 413, 415, 422, 429 or 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "reference:read" } }, "/districts": { "get": { "summary": "Alias of regions", "operationId": "get_districts", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Region" } } } } } } }, "default": { "description": "Error envelope. 400, 401, 403, 404, 409, 410, 413, 415, 422, 429 or 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "reference:read" } }, "/options": { "get": { "summary": "Accepted enum values", "operationId": "get_options", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } } } } }, "default": { "description": "Error envelope. 400, 401, 403, 404, 409, 410, 413, 415, 422, 429 or 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-required-scope": "reference:read" } }, "/jobs": { "get": { "summary": "Paginated company jobs", "operationId": "get_jobs", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Job" } }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer" }, "per_page": { "type": "integer" }, "total": { "type": "integer" }, "last_page": { "type": "integer" } } } } } } } }, "default": { "description": "Error envelope. 400, 401, 403, 404, 409, 410, 413, 415, 422, 429 or 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "page", "in": "query", "schema": { "type": "integer", "minimum": 1 } }, { "name": "per_page", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "pending", "inactive", "expired" ] } } ], "x-required-scope": "jobs:read" }, "post": { "summary": "Create job; pending unless company can auto-publish", "operationId": "post_jobs", "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" } } } } }, "headers": { "Location": { "schema": { "type": "string" } } } }, "default": { "description": "Error envelope. 400, 401, 403, 404, 409, 410, 413, 415, 422, 429 or 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Idempotency replay; Idempotent-Replayed: true", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" } } } } }, "headers": { "Idempotent-Replayed": { "schema": { "type": "string" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobInput" } } } }, "parameters": [ { "in": "header", "name": "Idempotency-Key", "required": true, "description": "Unique per company. Reuse with identical JSON to retry; returns 200 and current job state. Different JSON returns 409; removed original returns 410.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" } } ], "x-required-scope": "jobs:write" } }, "/jobs/{id}": { "get": { "summary": "Get owned job by numeric ID", "operationId": "get_jobs_id", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" } } } } } }, "default": { "description": "Error envelope. 400, 401, 403, 404, 409, 410, 413, 415, 422, 429 or 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "x-required-scope": "jobs:read" }, "patch": { "summary": "Update supplied fields; inactive jobs stay inactive", "operationId": "patch_jobs_id", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Job" } } } } } }, "default": { "description": "Error envelope. 400, 401, 403, 404, 409, 410, 413, 415, 422, 429 or 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobPatch" } } } }, "x-required-scope": "jobs:write" }, "delete": { "summary": "Withdraw job and preserve applications; repeat returns 204", "operationId": "delete_jobs_id", "responses": { "204": { "description": "Success" }, "default": { "description": "Error envelope. 400, 401, 403, 404, 409, 410, 413, 415, 422, 429 or 503.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" } } ], "x-required-scope": "jobs:write" } } }, "components": { "securitySchemes": { "companyToken": { "type": "http", "scheme": "bearer" } }, "schemas": { "JobInput": { "type": "object", "additionalProperties": false, "properties": { "requirements": { "type": "string", "nullable": true, "maxLength": 10000 }, "salary_benefits": { "type": "string", "nullable": true, "maxLength": 5000 }, "remote_policy": { "type": "string", "nullable": true, "maxLength": 5000 }, "contact_email": { "type": "string", "nullable": true, "maxLength": 255, "format": "email", "description": "Required when application_method is email." }, "contact_phone": { "type": "string", "nullable": true, "maxLength": 20, "description": "Required when application_method is phone." }, "external_application_url": { "type": "string", "nullable": true, "maxLength": 2048, "format": "uri", "description": "Required when application_method is external." }, "title": { "type": "string", "maxLength": 255 }, "body": { "type": "string", "maxLength": 30000, "description": "Up to 30000 characters and 65535 UTF-8 bytes." }, "contact_instructions": { "type": "string", "maxLength": 10000 }, "category_id": { "type": "integer", "minimum": 1, "description": "Active child category with an active parent; GET /categories supplies IDs." }, "district_id": { "type": "integer", "minimum": 1 }, "valid_until": { "type": "string", "format": "date", "nullable": true, "description": "Future date, YYYY-MM-DD; null means open-ended." }, "salary_min": { "type": "number", "minimum": 0, "maximum": 99999999.99, "nullable": true }, "salary_max": { "type": "number", "minimum": 0, "maximum": 99999999.99, "nullable": true, "description": "Must be greater than or equal to salary_min. Values in EUR." }, "salary_negotiable": { "type": "boolean" }, "experience_years": { "type": "integer", "minimum": 0, "maximum": 50, "nullable": true }, "education_details": { "type": "array", "nullable": true, "maxItems": 50, "items": { "type": "string", "maxLength": 500 } }, "professional_requirements": { "type": "array", "nullable": true, "maxItems": 50, "items": { "type": "string", "maxLength": 500 } }, "language_requirements": { "type": "array", "nullable": true, "maxItems": 50, "items": { "type": "string", "maxLength": 500 } }, "contract_type": { "type": "string", "enum": [ "full_time", "part_time", "contract", "temporary", "internship", "freelance" ], "nullable": true }, "work_modality": { "type": "string", "enum": [ "presencial", "remoto", "hibrido" ], "nullable": true }, "application_method": { "type": "string", "enum": [ "system", "email", "phone", "external" ], "nullable": false }, "salary_type": { "type": "string", "enum": [ "hourly", "monthly", "yearly", "negotiable", "not_specified" ], "nullable": true }, "education_level": { "type": "string", "enum": [ "sem_requisitos", "ensino_basico", "ensino_secundario", "ensino_profissional", "curso_tecnologico", "licenciatura", "pos_graduacao", "mestrado", "doutoramento", "outro" ], "nullable": true } }, "required": [ "title", "body", "contact_instructions", "category_id", "district_id", "application_method" ] }, "JobPatch": { "type": "object", "additionalProperties": false, "minProperties": 1, "properties": { "requirements": { "type": "string", "nullable": true, "maxLength": 10000 }, "salary_benefits": { "type": "string", "nullable": true, "maxLength": 5000 }, "remote_policy": { "type": "string", "nullable": true, "maxLength": 5000 }, "contact_email": { "type": "string", "nullable": true, "maxLength": 255, "format": "email" }, "contact_phone": { "type": "string", "nullable": true, "maxLength": 20 }, "external_application_url": { "type": "string", "nullable": true, "maxLength": 2048, "format": "uri" }, "title": { "type": "string", "maxLength": 255 }, "body": { "type": "string", "maxLength": 30000, "description": "Up to 30000 characters and 65535 UTF-8 bytes." }, "contact_instructions": { "type": "string", "maxLength": 10000 }, "category_id": { "type": "integer", "minimum": 1 }, "district_id": { "type": "integer", "minimum": 1 }, "valid_until": { "type": "string", "format": "date", "nullable": true, "description": "Future date, YYYY-MM-DD; null means open-ended." }, "salary_min": { "type": "number", "minimum": 0, "maximum": 99999999.99, "nullable": true }, "salary_max": { "type": "number", "minimum": 0, "maximum": 99999999.99, "nullable": true }, "salary_negotiable": { "type": "boolean" }, "experience_years": { "type": "integer", "minimum": 0, "maximum": 50, "nullable": true }, "education_details": { "type": "array", "nullable": true, "maxItems": 50, "items": { "type": "string", "maxLength": 500 } }, "professional_requirements": { "type": "array", "nullable": true, "maxItems": 50, "items": { "type": "string", "maxLength": 500 } }, "language_requirements": { "type": "array", "nullable": true, "maxItems": 50, "items": { "type": "string", "maxLength": 500 } }, "contract_type": { "type": "string", "enum": [ "full_time", "part_time", "contract", "temporary", "internship", "freelance" ], "nullable": true }, "work_modality": { "type": "string", "enum": [ "presencial", "remoto", "hibrido" ], "nullable": true }, "application_method": { "type": "string", "enum": [ "system", "email", "phone", "external" ], "nullable": false }, "salary_type": { "type": "string", "enum": [ "hourly", "monthly", "yearly", "negotiable", "not_specified" ], "nullable": true }, "education_level": { "type": "string", "enum": [ "sem_requisitos", "ensino_basico", "ensino_secundario", "ensino_profissional", "curso_tecnologico", "licenciatura", "pos_graduacao", "mestrado", "doutoramento", "outro" ], "nullable": true } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "status": { "type": "integer" }, "message": { "type": "string" }, "details": { "type": "object" } } } } }, "Job": { "type": "object", "properties": { "requirements": { "type": "string", "nullable": true, "maxLength": 10000 }, "salary_benefits": { "type": "string", "nullable": true, "maxLength": 5000 }, "remote_policy": { "type": "string", "nullable": true, "maxLength": 5000 }, "contact_email": { "type": "string", "nullable": true, "maxLength": 255, "format": "email", "description": "Required when application_method is email." }, "contact_phone": { "type": "string", "nullable": true, "maxLength": 20, "description": "Required when application_method is phone." }, "external_application_url": { "type": "string", "nullable": true, "maxLength": 2048, "format": "uri", "description": "Required when application_method is external." }, "title": { "type": "string", "maxLength": 255 }, "body": { "type": "string", "maxLength": 30000 }, "contact_instructions": { "type": "string", "maxLength": 10000 }, "category_id": { "type": "integer", "minimum": 1, "nullable": true }, "district_id": { "type": "integer", "minimum": 1, "nullable": true }, "valid_until": { "type": "string", "format": "date", "nullable": true, "description": "Future date, YYYY-MM-DD; null means open-ended." }, "salary_min": { "type": "string", "nullable": true, "description": "Decimal EUR amount serialized as a string to preserve precision.", "example": "1500.00" }, "salary_max": { "type": "string", "nullable": true, "description": "Decimal EUR amount serialized as a string to preserve precision.", "example": "1500.00" }, "salary_negotiable": { "type": "boolean" }, "experience_years": { "type": "integer", "minimum": 0, "maximum": 50, "nullable": true }, "education_details": { "type": "array", "nullable": true, "maxItems": 50, "items": { "type": "string", "maxLength": 500 } }, "professional_requirements": { "type": "array", "nullable": true, "maxItems": 50, "items": { "type": "string", "maxLength": 500 } }, "language_requirements": { "type": "array", "nullable": true, "maxItems": 50, "items": { "type": "string", "maxLength": 500 } }, "contract_type": { "type": "string", "enum": [ "full_time", "part_time", "contract", "temporary", "internship", "freelance" ], "nullable": true }, "work_modality": { "type": "string", "enum": [ "presencial", "remoto", "hibrido" ], "nullable": true }, "application_method": { "type": "string", "enum": [ "system", "email", "phone", "external" ], "nullable": false }, "salary_type": { "type": "string", "enum": [ "hourly", "monthly", "yearly", "negotiable", "not_specified" ], "nullable": true }, "education_level": { "type": "string", "enum": [ "sem_requisitos", "ensino_basico", "ensino_secundario", "ensino_profissional", "curso_tecnologico", "licenciatura", "pos_graduacao", "mestrado", "doutoramento", "outro" ], "nullable": true }, "id": { "type": "integer" }, "company_name": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "pending", "active", "inactive", "expired", "denied" ] }, "is_active": { "type": "boolean" }, "is_anonymous": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "Category": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "parent_id": { "type": "integer", "nullable": true } } }, "Region": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" } } }, "Account": { "type": "object", "properties": { "company_id": { "type": "integer" }, "plan": { "type": "string", "nullable": true }, "requests_per_minute": { "type": "integer" }, "jobs": { "type": "object", "properties": { "limit": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" }, "period_start": { "type": "string", "format": "date", "nullable": true }, "period_end": { "type": "string", "format": "date", "nullable": true } } }, "access_type": { "type": "string", "enum": [ "subscription", "complimentary" ], "description": "Production access entitlement. Complimentary access is administrator-granted and may have its own posting quota and expiry." } } } } } }