Gloat Candidacy API

openapi: 3.2.0
info:
  title: Gloat Customer Candidacy API
  description: This document covers the data models and the APIs exposed by Gloat.
  contact:
    email: naama.b@gloat.com
  version: 1.0.0
servers:
- url: https://api.gloat.com/api/v2
security:
- ApiKeyAuth: []
tags:
- name: Candidacy
  description: Candidacies operations
paths:
  /candidacies:
    post:
      tags:
      - Candidacy
      summary: Upsert candidacy
      description: Update or insert a candidacy in Gloat
      operationId: candidacyUpsert
      requestBody:
        description: Gloat candidacy object
        content:
          application/json:
            schema:
              type: object
              properties:
                allowInsert:
                  type: boolean
                  default: true
                  description: If true, candidacy will be created if missing. If false, will be ignored and treated as success.
                suppressRejectionEmail:
                  type: boolean
                  default: true
                  description: If false and the update triggers the creation of a rejection action, then Gloat will send a rejection notice to the candidate. If true, a rejection notice will not be sent.
              allOf:
              - type: object
                required:
                - vendor
                properties:
                  vendor:
                    type: string
                    example: vendor
                  new_external_id:
                    type: string
                    description: updates external id only for existing candidate
                  allowExternalCandidacies:
                    type: boolean
                    default: false
                    description: If true, candidacies will be created and/or updated, even if they were not initiated in the Gloat platform. Otherwise, the default, candidacies are not created or updated, unless an action (apply/approach) was taken in Gloat initially.
              - $ref: '#/components/schemas/candidacy_data_object'
        required: true
      responses:
        '200':
          description: successful operation - candidacy updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/candidacy_response'
        '201':
          description: successful operation - candidacy created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/candidacy_response'
        '400':
          description: Bad request - invalid parameters | invalid candidacy structure data | invalid status
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Unable to parse candidacy
        '404':
          description: user or job of candidacy does not exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: User does not exist
        '500':
          description: internal server problem
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Internal server error
      x-codegen-request-body-name: body
      x-operation-id-source: normalized
      x-operation-id-original: candidacy upsert
    patch:
      tags:
      - Candidacy
      summary: Update candidacy data
      description: Update candidacy data by ids
      operationId: candidacyPatch
      requestBody:
        description: List of Gloat candidacy objects
        content:
          application/json:
            schema:
              type: object
              properties:
                vendor:
                  type: string
                  example: vendor
                candidacies:
                  type: array
                  items:
                    allOf:
                    - type: object
                      properties:
                        candidacy_status:
                          $ref: '#/components/schemas/candidacy_status_object'
                    - $ref: '#/components/schemas/candidacy_id_data'
                suppressRejectionEmail:
                  description: If false and the update triggers the creation of a rejection action, then Gloat will send a rejection notice to the candidate. If true, a rejection notice will not be sent.
                  type: string
                  default: 'true'
                allowExternalCandidacies:
                  type: boolean
                  default: false
                  description: If true, candidacies will be created and/or updated, even if they were not initiated in the Gloat platform. Otherwise, the default, candidacies are not created or updated, unless an action (apply/approach) was taken in Gloat initially.
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                type: object
        '400':
          description: Bad request - invalid payload | invalid candidacy structure data | invalid status | candidacy not found
          content:
            application/json:
              schema:
                oneOf:
                - type: object
                  properties:
                    results:
                      type: object
                      properties:
                        Success:
                          type: array
                          items:
                            type: string
                            example:
                            - id1
                            - id2
                        Invalid input:
                          type: array
                          items:
                            type: string
                            example: id3
                        Not found:
                          type: array
                          items:
                            type: string
                            example: id4
                        Unknown error:
                          type: array
                          items:
                            type: string
                            example: id5
                - type: object
                  properties:
                    success:
                      type: boolean
                      example: false
                    error:
                      type: string
                      example: Unable to parse payload
      x-codegen-request-body-name: body
      x-operation-id-source: normalized
      x-operation-id-original: candidacy patch
    get:
      tags:
      - Candidacy
      summary: Get candidacy data
      description: get candidacy data by id
      operationId: candidacyGet
      parameters:
      - name: vendor
        in: query
        required: true
        schema:
          type: string
      - name: candidacy_id
        description: required 1 of - candidacy_id | job_id & user_id | external_id
        in: query
        required: false
        schema:
          type: string
      - name: job_id
        description: required 1 of - candidacy_id | job_id & user_id | external_id
        in: query
        required: false
        schema:
          type: string
      - name: user_id
        description: required 1 of - candidacy_id | job_id & user_id | external_id
        in: query
        required: false
        schema:
          type: string
      - name: external_id
        description: required 1 of - candidacy_id | job_id & user_id | external_id
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/candidacy_outbound_object_get'
        '400':
          description: Bad request - invalid payload | invalid candidacy structure data | invalid status | candidacy not found
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Not found
      x-codegen-request-body-name: body
      x-operation-id-source: normalized
      x-operation-id-original: candidacy get
  /candidacies/status:
    get:
      tags:
      - Candidacy
      summary: Candidacy IDs by status
      description: Retrieve list of candidacies by given status
      operationId: getCandidacyIDsByStatus
      parameters:
      - name: vendor
        in: query
        required: true
        schema:
          type: string
      - name: status
        in: query
        required: true
        schema:
          type: string
          enum:
          - apply
          - match
          - reject
          - invited-to-interview
          - interview
          - on-hold
          - advanced
          - phone-approach
          - email-approach
          - offer
          - hired
          - withdrew
      - name: offset
        in: query
        schema:
          default: 0
        description: how many candidacies to skip from beginning
      - name: limit
        in: query
        description: how many candidacies to return (max 1000)
        schema:
          default: 200
      - name: start_date
        in: query
        description: Retrieve candidacies whose status last changed date equal or greater than received date
        schema:
          type: string
          format: date
          pattern: YYYY-MM-DD
          example: '2022-05-01'
      - name: end_date
        in: query
        description: Retrieve candidacies whose status last changed date equal or less than received date. Must be provided with start_date (max days range is 62)
        schema:
          type: string
          format: date
          pattern: YYYY-MM-DD
          default: <current_date>
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/candidacy_status_response'
        '400':
          description: Bad request - invalid payload | missing required params | invalid status | invalid vendor | non positive numbers (offset, limit) | limit exceeded max | invalid date format or input
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: 'received invalid status, status: <invalid_status>'
        '500':
          description: internal server problem
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: false
                  error:
                    type: string
                    example: Internal Server Error
      x-operation-id-source: normalized
      x-operation-id-original: get candidacy IDs by status
components:
  schemas:
    basic_user_object:
      type: object
      title: Basic User Data
      required:
      - first_name
      - last_name
      - email
      properties:
        first_name:
          type: string
          example: John
        last_name:
          type: string
          example: Doe
        email:
          type: string
          example: john.doe@gloat.com
    candidacy_data_object:
      title: Candidacy
      type: object
      allOf:
      - $ref: '#/components/schemas/candidacy_id_data'
      - type: object
        properties:
          candidacy_status:
            $ref: '#/components/schemas/candidacy_status_object'
          user_data:
            $ref: '#/components/schemas/basic_user_object'
          actions:
            type: array
            items:
              $ref: '#/components/schemas/candidacy_action'
    candidacy_status_object_get:
      type: object
      title: Candidacy Status Object
      properties:
        status:
          $ref: '#/components/schemas/candidacy_status'
    candidacy_status_response:
      type: object
      properties:
        count:
          type: number
          example: 1
        hasMore:
          type: boolean
          example: false
        candidacies:
          type: array
          items:
            allOf:
            - $ref: '#/components/schemas/candidacy_outbound_object_get'
            - type: object
              properties:
                status:
                  type: string
                  description: received status in parameters
                  example: apply
    candidacy_action:
      type: object
      title: Candidacy Action
      properties:
        action:
          type: string
          example: CL
          description: candidacy action (2 letter code)
        timestamp:
          type: string
          format: date-time
    candidacy_response:
      type: object
      properties:
        success:
          type: boolean
    candidacy_status_object:
      type: object
      title: Candidacy Status Object
      properties:
        status:
          $ref: '#/components/schemas/candidacy_status'
        changed_by:
          type: string
          example: 123456
          description: external user id of actor
        changed_by_user_data:
          $ref: '#/components/schemas/basic_user_object'
        description:
          type: string
        free_text:
          type: string
        timestamp:
          type: string
          format: date-time
    candidacy_status:
      type: string
      title: Candidacy Status
      enum:
      - apply
      - match
      - reject
      - invited-to-interview
      - interview
      - on-hold
      - advanced
      - phone-approach
      - email-approach
      - offer
      - hired
      - withdrew
    candidacy_outbound_object_get:
      type: object
      title: Candidacy
      properties:
        candidacy_id:
          type: string
        external_id:
          type: string
        job_id:
          type: string
        user_id:
          type: string
        candidacy_status:
          $ref: '#/components/schemas/candidacy_status_object_get'
        user_data:
          $ref: '#/components/schemas/basic_user_object'
    candidacy_id_data:
      type: object
      oneOf:
      - type: object
        properties:
          candidacy_id:
            type: string
        required:
        - candidacy_id
        additionalProperties: false
      - type: object
        properties:
          job_id:
            type: string
          user_id:
            type: string
        required:
        - job_id
        - user_id
        additionalProperties: false
      - type: object
        properties:
          external_id:
            type: string
        required:
        - external_id
        additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-Gloat-API-Key
      in: header
x-provenance:
  method: searched
  source: https://developer.gloat.com/reference
  harvested: '2026-10-14'
  tool: harvest-readme-openapi.py
  note: Assembled verbatim from the OpenAPI definition ReadMe embeds in each operation page of the provider's developer portal; paths and components merged by API title, nothing authored.
  assembled_from:
  - https://developer.gloat.com/reference/candidacy-get-1.md
  - https://developer.gloat.com/reference/candidacy-patch-1.md
  - https://developer.gloat.com/reference/candidacy-upsert-1.md
  - https://developer.gloat.com/reference/department-bulk-delete-1.md
  - https://developer.gloat.com/reference/function-bulk-insert-1.md
  - https://developer.gloat.com/reference/get-candidacy-ids-by-status-1.md
  - https://developer.gloat.com/reference/get-gloat-cv-by-user-and-job-1.md
  - https://developer.gloat.com/reference/get-job-by-status-1.md
  - https://developer.gloat.com/reference/get_jobs-desired-1.md
  - https://developer.gloat.com/reference/get_ping-1.md
  - https://developer.gloat.com/reference/get_projects-1.md
  - https://developer.gloat.com/reference/get_projects-roles-1.md
  - https://developer.gloat.com/reference/getuserskills-1.md
  - https://developer.gloat.com/reference/getuserskillsoutbound-1.md
  - https://developer.gloat.com/reference/grantrolestousers-1.md
  - https://developer.gloat.com/reference/job-patch-1.md
  - https://developer.gloat.com/reference/job-upsert-1.md
  - https://developer.gloat.com/reference/learning-get-1.md
  - https://developer.gloat.com/reference/learning-patch-1.md
  - https://developer.gloat.com/reference/listallcompanygroups-1.md
  - https://developer.gloat.com/reference/listallcompanyroles-1.md
  - https://developer.gloat.com/reference/listcompanyroles-1.md
  - https://developer.gloat.com/reference/listrolesassignments-1.md
  - https://developer.gloat.com/reference/listusers-1.md
  - https://developer.gloat.com/reference/listusersgroups-1.md
  - https://developer.gloat.com/reference/location-bulk-insert-1.md
  - https://developer.gloat.com/reference/opportunities-personalized-1.md
  - https://developer.gloat.com/reference/opportunities-post-1.md
  - https://developer.gloat.com/reference/patchusers-1.md
  - https://developer.gloat.com/reference/post_outbound-post-candidate-1.md
  - https://developer.gloat.com/reference/post_user-profile-training-1.md
  - https://developer.gloat.com/reference/postskills-1.md
  - https://developer.gloat.com/reference/postuserskills-1.md
  - https://developer.gloat.com/reference/postuserskillsoutbound-1.md
  - https://developer.gloat.com/reference/project-role-update-or-create-1.md
  - https://developer.gloat.com/reference/project-role-update-status-1.md
  - https://developer.gloat.com/reference/project-update-or-create-1.md
  - https://developer.gloat.com/reference/project-update-status-1.md
  - https://developer.gloat.com/reference/revokerolesfromusers-1.md
  - https://developer.gloat.com/reference/search-by-keyword-1.md
  - https://developer.gloat.com/reference/user-activate-1.md
  - https://developer.gloat.com/reference/user-upsert-1.md
  merge:
    pages: 42
    deduped: 79
    conflicts_kept_first: 0