Welcome to the Brainner API documentation. This API is primarily focused on managing candidates and jobs within the Brainner platform, providing tools for streamlined operations and efficient management.
As we continuously work on improving and expanding our API's capabilities, this documentation remains a work in progress. It will be regularly updated to reflect the latest changes and enhancements.
To explore our API's functionalities, feel free to use the Swagger Editor at https://editor.swagger.io/. This user-friendly interface allows you to interact with our API, testing its features and capabilities in real-time.
Creating an API Key:
- Navigate to the Settings in your Brainner account.
- Access the 'API & Webhooks' section.
- Select 'Create a new API user' to generate your unique API key.
We value your feedback and experiences with our API. If you encounter any issues, have queries, or wish to provide suggestions, do not hesitate to reach out to us. Your input is crucial in helping us enhance the Brainner API experience.
openapi: 3.0.0
info:
title: Brainner API
version: 1.0.0
description: API for managing jobs and candidates in the Brainner system.
servers:
- url: https://admin.brainner.ai/
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: $token
schemas:
Job:
type: object
properties:
Role:
type: string
description: The role to hire.
Metadata:
type: object
description: Custom structured data. You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. All values will be converted to string.
example: { "foo": "bar" }
RoleType:
type: string
enum: [full_time, part_time, temporary, contractor, intern, volunteer]
description: The type of employment for the role.
Description:
type: string
description: Description of the job in markdown formatting.
Criteria:
type: array
items:
$ref: '#/components/schemas/Criteria'
description: List of requirements for the job.
CandidateProfile:
type: array
items:
type: object
properties:
Attribute:
type: string
description: Attributes to extract from candidate resumes.
LocationType:
type: string
enum: [office, hybrid, remote]
description: Indicates where the job will be performed.
Locations:
type: array
items:
type: object
properties:
Address:
type: string
State:
type: string
City:
type: string
Country:
type: string
description: Details of the job's possible locations.
Language:
type: string
description: The language to use for criteria and reports.
Criteria:
type: object
properties:
Text:
type: string
description: The requirement text.
Category:
type: string
enum: [Work, Skills, Education, Additional]
description: Category of the requirement.
Required:
type: boolean
description: Indicates if the requirement is strongly needed.
Candidate:
type: object
properties:
Name:
type: string
description: Name of the candidate.
Email:
type: string
description: Email of the candidate.
Metadata:
type: object
description: Custom structured data. You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long. All values will be converted to string.
Language:
type: string
description: The language to use for the candidate's report.
paths:
/api/jobs:
post:
summary: Create a job
tags:
- Job
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/Job'
options:
type: object
properties:
parseCriteria:
type: boolean
description: Parse the job description to extract the criteria. The event "job.created" will be deferred until the criteria is updated.
responses:
'201':
description: Job created successfully.
security:
- bearerAuth: []
/api/jobs/{id}:
get:
summary: Get a specific job
tags:
- Job
description: Retrieve detailed information about a specific job by its ID.
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The unique identifier of the job.
responses:
'200':
description: Job details retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
'404':
description: Job not found.
put:
summary: Update a specific job
tags:
- Job
description: Update details of a specific job by its ID.
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The unique identifier of the job to update.
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
responses:
'200':
description: Job updated successfully.
'400':
description: Invalid input provided.
'404':
description: Job not found.
/api/jobs/{id}/archive:
post:
summary: Archive a job
tags:
- Job
description: Archive a specific job by its ID.
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The unique identifier of the job to archive.
responses:
'200':
description: Job archived successfully.
security:
- bearerAuth: []
/api/candidates:
post:
summary: Create a candidate
tags:
- Candidate
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
data:
type: string
format: json
description: JSON string containing the details of the candidate.
options:
type: string
format: json
description: >
JSON string containing options while creating the candidate. {evaluate: true} will add the candidate to the evaluation queue.
files.Resume:
type: string
format: binary
description: The candidate's resume file.
responses:
'201':
description: Candidate created successfully.
security:
- bearerAuth: []
/api/candidates/{id}:
get:
summary: Get a specific candidate
tags:
- Candidate
description: Retrieve detailed information about a specific candidate by their ID.
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The unique identifier of the candidate.
responses:
'200':
description: Candidate details retrieved successfully.
content:
application/json:
schema:
$ref: '#/components/schemas/Candidate'
'404':
description: Candidate not found.
put:
summary: Update a specific candidate
tags:
- Candidate
description: Update details of a specific candidate by their ID.
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The unique identifier of the candidate to update.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
data:
type: string
format: json
description: JSON string containing the details of the candidate. See Schemas/Candidate
files.Resume:
type: string
format: binary
description: The candidate's resume file.
options:
type: string
format: json
description: >
JSON string containing options while creating the candidate. {evaluate: true} will add the candidate to the evaluation queue.
application/json:
schema:
$ref: '#/components/schemas/Candidate'
responses:
'200':
description: Candidate updated successfully.
'400':
description: Invalid input provided.
'404':
description: Candidate not found.
/api/candidates/{id}/evaluate:
post:
summary: Evaluate a candidate
tags:
- Candidate
parameters:
- in: path
name: id
required: true
schema:
type: string
description: The ID of the candidate to evaluate.
responses:
'200':
description: Candidate evaluated successfully.
security:
- bearerAuth: []