Brainner API

api.md

API Documentation

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:

1. Navigate to the Settings in your Brainner account.
2. Access the 'API & Webhooks' section.
3. 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.
        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.
    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.
        Profile:
          type: object
          description: Object representing the profile information extracted from the resume based on the job.CandidateProfile.

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/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. {applying: 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.
          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: []

webhooks.md

Webhooks Documentation

Webhooks in Brainner are designed to send notifications about critical events occurring within the system. Currently, we support two events: candidate.created and candidate.evaluated. Below, you'll find sample payloads for each of these events.

Creating a Webhook

1. Navigate to Settings in your Brainner account.
2. Click on 'API & Webhooks'.
3. Enter the URL where you want to receive webhook notifications.
4. Select at least one of the events you wish to subscribe to.

candidate.created

This webhook is triggered when a new candidate is created. The payload example:

{
  "event": "candidate.created",
  "data": {
    "type": "candidate",
    "id": 2003,
    "attributes": {
      "Name": null,
      "Email": null,
      "ResumeParsed": "...",
      "Profile": null,
      "Criteria": null,
      "createdAt": "2024-03-21T10:00:50.606Z",
      "updatedAt": "2024-03-21T10:00:50.606Z",
      "Status": "created"
    }
  }
}

candidate.evaluated

This webhook is triggered when a candidate's evaluation is completed. Note:

• Profile refers to the CandidateProfile defined in the job.
• Criteria refers to the requirements set in the job criteria.

The payload example:

{
  "event": "candidate.evaluated",
  "data": {
    "type": "candidate",
    "id": 2003,
    "attributes": {
      "Name": "Guillermo Gette",
      "Email": "guillermogette@gmail.com",
      "ResumeParsed": "...",
      "Profile": {
        "Name": "...",
        "Email": "guillermogette@gmail.com",
        "Location": "Sydney, New South Wales, Australia",
        "Current role": "Co-Founder",
        "Current company": "Workast"
      },
      "Criteria": {
        "453": {
          "outcome": "yes",
          "analysis": "The candidate has experience managing several projects and founding companies, indicating capability in managing production crises."
        },
        "454": {
          "outcome": "no",
          "analysis": "The resume does not mention experience with large-scale, distributed backend systems in compiled languages like Java, C#, or Go."
        },
        // Additional criteria outcomes and analyses...
      },
      "createdAt": "2024-03-21T10:00:50.606Z",
      "updatedAt": "2024-03-21T10:01:29.171Z",
      "Status": "evaluated",
      "Job": {...}
    }
  }
}

job.created

This webhook is triggered when a job is created. If while creating the job, we passs the option { parseCriteria: true } the event will be executed once the criteria has been collected.

The payload example:

{
  "event": "job.created",
  "data": {
    "type": "job",
    "id": 207,
    "attributes": {
      "Role": "Manager",
      "Description": "...",
      "createdAt": "2024-04-08T02:50:28.900Z",
      "updatedAt": "2024-04-08T02:50:28.900Z",
      "publishedAt": null,
      "EvaluatedCandidates": null,
      "Status": "draft",
      "LocationType": "office",
      "RoleType": "full_time",
      "CandidateProfile": [
        {
          "id": 942,
          "Attribute": "Name"
        },
        {
          "id": 941,
          "Attribute": "Email"
        },
        {
          "id": 940,
          "Attribute": "Current company"
        },
        {
          "id": 943,
          "Attribute": "Current role"
        },
        {
          "id": 944,
          "Attribute": "Location"
        }
      ],
      "Criteria": [
        {
          "id": 1652,
          "Text": "Experience in complex digital advertising or ad technology projects",
          "Category": "Work",
          "Required": true
        },
        {
          "id": 1653,
          "Text": "Understanding of broadcaster's or publisher's strategic goals",
          "Category": "Work",
          "Required": true
        },
        {
          "id": 1651,
          "Text": "Knowledge of campaign booking processes and sales mechanisms in the digital and/or TV advertising market",
          "Category": "Work",
          "Required": true
        },
        {
          "id": 1655,
          "Text": "Excellent communication skills in English",
          "Category": "Skills",
          "Required": true
        },
        {
          "id": 1654,
          "Text": "German speaking",
          "Category": "Skills",
          "Required": false
        },
        {
          "id": 1656,
          "Text": "Experience in product management or requirements engineering",
          "Category": "Work",
          "Required": false
        }
      ]
      "Suggestions": [],
      "Locations": []
    }
  }
}