Sense Talent Labs Candidate API

openapi: 3.2.0
info:
  description: '# Overview

    ### Introduction

    Use the Sense API to synchronize your ATS data into the Sense Platform.'
  title: Sense Candidate API
  version: ''
servers:
- url: https://partner-api.us-stage.sensehq.co
security:
- sense_bearer_auth: []
tags:
- description: A person seeking a job.
  name: Candidate
paths:
  /candidates:
    post:
      description: Batch upsert Candidate entities.
      operationId: post_candidates
      requestBody:
        content:
          application/json:
            schema:
              items:
                $ref: '#/components/schemas/Candidate'
              maxItems: 500
              minItems: 1
              type: array
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/201_response_schema'
          description: Request accepted for async processing.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_response_schema'
          description: Invalid request. Message will indicate which field failed validation.
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_response_schema'
          description: Payload too large
      summary: Upsert Candidate
      tags:
      - Candidate
  /candidates/{id}:
    get:
      description: Fetch details of a single Candidate entity by its unique ID.
      operationId: get_candidates
      parameters:
      - description: The unique ID of the Candidate whose details need to be retrieved.
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/200_response_schema'
          description: Successful response containing Candidate details.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/200_response_schema'
          description: Invalid request. Message will indicate which field failed validation.
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/200_response_schema'
          description: Candidate not found.
      summary: Retrieve Candidate details
      tags:
      - Candidate
    patch:
      description: Update single Candidate entity.
      operationId: patch_candidates
      parameters:
      - description: The unique id of the Candidatewhose details need to be updated.
        in: path
        name: id
        required: true
        schema:
          type: integer
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Candidate'
              type: object
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/201_response_schema'
          description: Request accepted for async processing.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_response_schema'
          description: Invalid request. Message will indicate which field failed validation.
        '413':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_response_schema'
          description: Payload too large
      summary: Update Candidate
      tags:
      - Candidate
  /candidates/possible-values/{fieldName}:
    get:
      description: Fetch the list of possible values configured for a field on the Candidate entity. These values define dropdown options used in various Sense workflows.
      operationId: get_candidates_possible_values
      parameters:
      - description: The field name for which possible values should be retrieved.
        in: path
        name: fieldName
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PossibleValuesGetResponse'
          description: Successful response containing possible values.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_response_schema'
          description: Invalid request.
      summary: Get possible values for a Candidate field
      tags:
      - Candidate
    put:
      description: A self-serve endpoint to synchronize dropdown options with your ATS configuration, ensuring data integrity during field writebacks.
      operationId: put_candidates_possible_values
      parameters:
      - description: The field name whose possible values should be updated.
        in: path
        name: fieldName
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            example:
            - label: Hourly
              value: hourly
            - label: Daily
              value: daily
            schema:
              items:
                properties:
                  label:
                    type: string
                  value:
                    oneOf:
                    - type: string
                    - type: number
                    - type: boolean
                required:
                - label
                - value
                type: object
              type: array
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PossibleValuesPutResponse'
          description: Updated possible values returned in the response.
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/400_response_schema'
          description: Invalid request payload.
      summary: Update possible values for a Candidate field
      tags:
      - Candidate
  /candidates/{id}/resume:
    post:
      description: 'Upload a resume file for a specific candidate. The file must be sent as multipart/form-data. Supported formats include pdf, doc, docx, txt, rtf, odt, html, htm.


        Maximum supported file upload size is 4MB.'
      operationId: post_candidates_resume
      parameters:
      - description: The unique ID of the candidate.
        in: path
        name: id
        required: true
        schema:
          type: string
      requestBody:
        content:
          multipart/form-data:
            example:
              date_created: '2026-01-20T08:00:00Z'
              date_updated: '2026-03-15T10:30:00Z'
              file: <binary file content>
              file_extension: pdf
              file_name: john_doe_resume.pdf
              resume_id: RES-78901
            schema:
              properties:
                date_created:
                  description: Date when the resume was created in the ATS.
                  format: date-time
                  type: string
                date_updated:
                  description: Date when the resume was last updated in the ATS.
                  format: date-time
                  type: string
                file:
                  description: 'The resume file to upload. (Maximum file size: 4 MB)'
                  format: binary
                  type: string
                file_extension:
                  description: 'The format of the file (Supported values : pdf, doc, docx, txt, rtf, odt, html, htm)'
                  type: string
                file_name:
                  description: The resume file name.
                  type:
                  - string
                  - 'null'
                resume_id:
                  description: The unique identifier for this resume file.
                  type: string
              required:
              - file
              - resume_id
              - file_extension
              - date_updated
              - date_created
              type: object
        required: true
      responses:
        '201':
          content:
            application/json:
              example:
                message: request 86887e46-5b72-450a-b6c4-2017a9faa566 is received
                request_id: 86887e46-5b72-450a-b6c4-2017a9faa566
              schema:
                $ref: '#/components/schemas/ResumeUploadResponse'
          description: Resume uploaded successfully.
        '400':
          content:
            application/json:
              examples:
                invalid_content_type:
                  summary: Invalid Content-Type
                  value:
                    errors:
                    - message: Content-Type must be multipart/form-data
                invalid_extension:
                  summary: Unsupported file extension
                  value:
                    errors:
                    - message: 'Invalid file_extension. Allowed: doc, docx, htm, html, odt, pdf, rtf, txt'
                missing_file:
                  summary: Missing file
                  value:
                    errors:
                    - message: 'Missing required form field: file'
                missing_file_extension:
                  summary: Missing file_extension
                  value:
                    errors:
                    - message: 'Missing required form field: file_extension'
              schema:
                $ref: '#/components/schemas/400_response_schema'
          description: Invalid request. The file may be missing, unsupported, or exceed the size limit.
      summary: Upload Candidate Resume
      tags:
      - Candidate
components:
  schemas:
    PossibleValuesPutResponse:
      properties:
        data:
          properties:
            field_name:
              type: string
            object_name:
              type: string
            possibleValues:
              items:
                properties:
                  label:
                    type: string
                  value:
                    oneOf:
                    - type: string
                    - type: number
                    - type: boolean
                required:
                - label
                - value
                type: object
              type: array
            updated:
              type: boolean
          type: object
        resource_id:
          type: string
      type: object
    Candidate:
      properties:
        active:
          type:
          - boolean
          - 'null'
        address1:
          type:
          - string
          - 'null'
        address2:
          type:
          - string
          - 'null'
        categories:
          items:
            type: string
          type:
          - array
          - 'null'
        city:
          type:
          - string
          - 'null'
        country:
          type:
          - string
          - 'null'
        custom_array1:
          items:
            type: string
          type:
          - array
          - 'null'
        custom_array2:
          items:
            type: string
          type:
          - array
          - 'null'
        custom_array3:
          items:
            type: string
          type:
          - array
          - 'null'
        custom_array4:
          items:
            type: string
          type:
          - array
          - 'null'
        custom_array5:
          items:
            type: string
          type:
          - array
          - 'null'
        custom_boolean1:
          type:
          - boolean
          - 'null'
        custom_boolean10:
          type:
          - boolean
          - 'null'
        custom_boolean11:
          type:
          - boolean
          - 'null'
        custom_boolean12:
          type:
          - boolean
          - 'null'
        custom_boolean13:
          type:
          - boolean
          - 'null'
        custom_boolean14:
          type:
          - boolean
          - 'null'
        custom_boolean15:
          type:
          - boolean
          - 'null'
        custom_boolean2:
          type:
          - boolean
          - 'null'
        custom_boolean3:
          type:
          - boolean
          - 'null'
        custom_boolean4:
          type:
          - boolean
          - 'null'
        custom_boolean5:
          type:
          - boolean
          - 'null'
        custom_boolean6:
          type:
          - boolean
          - 'null'
        custom_boolean7:
          type:
          - boolean
          - 'null'
        custom_boolean8:
          type:
          - boolean
          - 'null'
        custom_boolean9:
          type:
          - boolean
          - 'null'
        custom_date1:
          format: date
          type:
          - string
          - 'null'
        custom_date10:
          format: date
          type:
          - string
          - 'null'
        custom_date11:
          format: date
          type:
          - string
          - 'null'
        custom_date12:
          format: date
          type:
          - string
          - 'null'
        custom_date13:
          format: date
          type:
          - string
          - 'null'
        custom_date14:
          format: date
          type:
          - string
          - 'null'
        custom_date15:
          format: date
          type:
          - string
          - 'null'
        custom_date16:
          format: date
          type:
          - string
          - 'null'
        custom_date17:
          format: date
          type:
          - string
          - 'null'
        custom_date18:
          format: date
          type:
          - string
          - 'null'
        custom_date19:
          format: date
          type:
          - string
          - 'null'
        custom_date2:
          format: date
          type:
          - string
          - 'null'
        custom_date20:
          format: date
          type:
          - string
          - 'null'
        custom_date21:
          format: date
          type:
          - string
          - 'null'
        custom_date22:
          format: date
          type:
          - string
          - 'null'
        custom_date23:
          format: date
          type:
          - string
          - 'null'
        custom_date24:
          format: date
          type:
          - string
          - 'null'
        custom_date25:
          format: date
          type:
          - string
          - 'null'
        custom_date26:
          format: date
          type:
          - string
          - 'null'
        custom_date27:
          format: date
          type:
          - string
          - 'null'
        custom_date28:
          format: date
          type:
          - string
          - 'null'
        custom_date29:
          format: date
          type:
          - string
          - 'null'
        custom_date3:
          format: date
          type:
          - string
          - 'null'
        custom_date30:
          format: date
          type:
          - string
          - 'null'
        custom_date31:
          format: date
          type:
          - string
          - 'null'
        custom_date32:
          format: date
          type:
          - string
          - 'null'
        custom_date33:
          format: date
          type:
          - string
          - 'null'
        custom_date34:
          format: date
          type:
          - string
          - 'null'
        custom_date35:
          format: date
          type:
          - string
          - 'null'
        custom_date36:
          format: date
          type:
          - string
          - 'null'
        custom_date37:
          format: date
          type:
          - string
          - 'null'
        custom_date38:
          format: date
          type:
          - string
          - 'null'
        custom_date39:
          format: date
          type:
          - string
          - 'null'
        custom_date4:
          format: date
          type:
          - string
          - 'null'
        custom_date40:
          format: date
          type:
          - string
          - 'null'
        custom_date41:
          format: date
          type:
          - string
          - 'null'
        custom_date42:
          format: date
          type:
          - string
          - 'null'
        custom_date43:
          format: date
          type:
          - string
          - 'null'
        custom_date44:
          format: date
          type:
          - string
          - 'null'
        custom_date45:
          format: date
          type:
          - string
          - 'null'
        custom_date46:
          format: date
          type:
          - string
          - 'null'
        custom_date47:
          format: date
          type:
          - string
          - 'null'
        custom_date48:
          format: date
          type:
          - string
          - 'null'
        custom_date49:
          format: date
          type:
          - string
          - 'null'
        custom_date5:
          format: date
          type:
          - string
          - 'null'
        custom_date50:
          format: date
          type:
          - string
          - 'null'
        custom_date6:
          format: date
          type:
          - string
          - 'null'
        custom_date7:
          format: date
          type:
          - string
          - 'null'
        custom_date8:
          format: date
          type:
          - string
          - 'null'
        custom_date9:
          format: date
          type:
          - string
          - 'null'
        custom_datetime1:
          format: date-time
          type:
          - string
          - 'null'
        custom_datetime2:
          format: date-time
          type:
          - string
          - 'null'
        custom_datetime3:
          format: date-time
          type:
          - string
          - 'null'
        custom_datetime4:
          format: date-time
          type:
          - string
          - 'null'
        custom_datetime5:
          format: date-time
          type:
          - string
          - 'null'
        custom_datetime6:
          format: date-time
          type:
          - string
          - 'null'
        custom_float1:
          type:
          - number
          - 'null'
        custom_float2:
          type:
          - number
          - 'null'
        custom_float3:
          type:
          - number
          - 'null'
        custom_float4:
          type:
          - number
          - 'null'
        custom_float5:
          type:
          - number
          - 'null'
        custom_float6:
          type:
          - number
          - 'null'
        custom_integer1:
          type:
          - integer
          - 'null'
        custom_integer2:
          type:
          - integer
          - 'null'
        custom_integer3:
          type:
          - integer
          - 'null'
        custom_integer4:
          type:
          - integer
          - 'null'
        custom_integer5:
          type:
          - integer
          - 'null'
        custom_integer6:
          type:
          - integer
          - 'null'
        custom_text1:
          type:
          - string
          - 'null'
        custom_text10:
          type:
          - string
          - 'null'
        custom_text11:
          type:
          - string
          - 'null'
        custom_text12:
          type:
          - string
          - 'null'
        custom_text13:
          type:
          - string
          - 'null'
        custom_text14:
          type:
          - string
          - 'null'
        custom_text15:
          type:
          - string
          - 'null'
        custom_text16:
          type:
          - string
          - 'null'
        custom_text17:
          type:
          - string
          - 'null'
        custom_text18:
          type:
          - string
          - 'null'
        custom_text19:
          type:
          - string
          - 'null'
        custom_text2:
          type:
          - string
          - 'null'
        custom_text20:
          type:
          - string
          - 'null'
        custom_text21:
          type:
          - string
          - 'null'
        custom_text22:
          type:
          - string
          - 'null'
        custom_text23:
          type:
          - string
          - 'null'
        custom_text24:
          type:
          - string
          - 'null'
        custom_text25:
          type:
          - string
          - 'null'
        custom_text26:
          type:
          - string
          - 'null'
        custom_text27:
          type:
          - string
          - 'null'
        custom_text28:
          type:
          - string
          - 'null'
        custom_text29:
          type:
          - string
          - 'null'
        custom_text3:
          type:
          - string
          - 'null'
        custom_text30:
          type:
          - string
          - 'null'
        custom_text31:
          type:
          - string
          - 'null'
        custom_text32:
          type:
          - string
          - 'null'
        custom_text33:
          type:
          - string
          - 'null'
        custom_text34:
          type:
          - string
          - 'null'
        custom_text35:
          type:
          - string
          - 'null'
        custom_text36:
          type:
          - string
          - 'null'
        custom_text37:
          type:
          - string
          - 'null'
        custom_text38:
          type:
          - string
          - 'null'
        custom_text39:
          type:
          - string
          - 'null'
        custom_text4:
          type:
          - string
          - 'null'
        custom_text40:
          type:
          - string
          - 'null'
        custom_text41:
          type:
          - string
          - 'null'
        custom_text42:
          type:
          - string
          - 'null'
        custom_text43:
          type:
          - string
          - 'null'
        custom_text44:
          type:
          - string
          - 'null'
        custom_text45:
          type:
          - string
          - 'null'
        custom_text46:
          type:
          - string
          - 'null'
        custom_text47:
          type:
          - string
          - 'null'
        custom_text48:
          type:
          - string
          - 'null'
        custom_text49:
          type:
          - string
          - 'null'
        custom_text5:
          type:
          - string
          - 'null'
        custom_text50:
          type:
          - string
          - 'null'
        custom_text6:
          type:
          - string
          - 'null'
        custom_text7:
          type:
          - string
          - 'null'
        custom_text8:
          type:
          - string
          - 'null'
        custom_text9:
          type:
          - string
          - 'null'
        custom_text_block1:
          type:
          - string
          - 'null'
        custom_text_block2:
          type:
          - string
          - 'null'
        custom_text_block3:
          type:
          - string
          - 'null'
        custom_text_block4:
          type:
          - string
          - 'null'
        custom_text_block5:
          type:
          - string
          - 'null'
        custom_text_block6:
          type:
          - string
          - 'null'
        date_added:
          format: date-time
          type:
          - string
          - 'null'
        date_last_activity:
          format: date-time
          type:
          - string
          - 'null'
        date_last_modified:
          format: date-time
          type:
          - string
          - 'null'
        date_of_birth:
          format: date
          type:
          - string
          - 'null'
        email:
          type:
          - string
          - 'null'
        email2:
          type:
          - string
          - 'null'
        email3:
          type:
          - string
          - 'null'
        ethnicity:
          description: 'The gender and ethnicity standard fields will be used to facilitate audits and will not be available in the front end of Sense. For more details, please review how Sense complies with the NYC Basis Audit Law: <a href=https://support.sensehq.co/hc/en-us/articles/24991816106509-Sense-compliance-with-NYC-Bias-Audit-Law>here</a>'
          type:
          - string
          - 'null'
        first_name:
          type:
          - string
          - 'null'
        gender:
          description: 'The gender and ethnicity standard fields will be used to facilitate audits and will not be available in the front end of Sense. For more details, please review how Sense complies with the NYC Basis Audit Law: <a href=https://support.sensehq.co/hc/en-us/articles/24991816106509-Sense-compliance-with-NYC-Bias-Audit-Law>here</a>'
          type:
          - string
          - 'null'
        home_phone:
          type:
          - string
          - 'null'
        id:
          minLength: 1
          type: string
        industries:
          items:
            type: string
          type:
          - array
          - 'null'
        internal_user_id:
          type:
          - string
          - 'null'
        internal_user_id2:
          type:
          - string
          - 'null'
        internal_user_id3:
          type:
          - string
          - 'null'
        is_archived:
          type:
          - boolean
          - 'null'
        is_deleted:
          description: A soft DELETE Operation is supported if the field `is_deleted = true`
          type:
          - boolean
          - 'null'
        last_name:
          type:
          - string
          - 'null'
        mobile_phone:
          type:
          - string
          - 'null'
        nick_name:
          type:
          - string
          - 'null'
        office:
          type:
          - string
          - 'null'
        opt_out_email:
          type:
          - boolean
          - 'null'
        opt_out_sms:
          type:
          - boolean
          - 'null'
        phone4:
          type:
          - string
          - 'null'
        phone5:
          type:
          - string
          - 'null'
        preferred_contact_method:
          type:
          - string
          - 'null'
        skills:
          items:
            type: string
          type:
          - array
          - 'null'
        source:
          type:
          - string
          - 'null'
        specialties:
          items:
            type: string
          type:
          - array
          - 'null'
        state:
          type:
          - string
          - 'null'
        status:
          type:
          - string
          - 'null'
        title:
          type:
          - string
          - 'null'
        work_phone:
          type:
          - string
          - 'null'
        zipcode:
          type:
          - string
          - 'null'
      required:
      - id
    400_response_schema:
      properties:
        errors:
          items:
            properties:
              entity_id:
                description: entity id which has validation errors if available
                type:
                - string
                - 'null'
              message:
                description: description of validation error
                type:
                - string
                - 'null'
              path:
                description: path to the entity which has validation errors
                items:
                  type: string
                type:
                - array
                - 'null'
          type:
          - array
          - 'null'
        warnings:
          items:
            properties:
              entity_id:
                description: entity id which has validation warnings if available
                type:
                - string
                - 'null'
              message:
                description: description of validation warning
                type:
                - string
                - 'null'
              path:
                description: path to the entity which has validation warnings
                items:
                  type: string
                type:
                - array
                - 'null'
          type:
          - array
          - 'null'
    200_response_schema:
      properties:
        data:
          description: Contains the response entity data
          type:
          - object
          - 'null'
        errors:
          items:
            properties:
              entity_id:
                description: entity id which has validation errors if available
                type:
                - string
                - 'null'
              message:
                description: description of validation error
                type:
                - string
                - 'null'
              path:
                description: path to the entity which has validation errors
                items:
                  type: string
                type:
                - array
                - 'null'
          type: array
        resource_id:
          description: the resource id for which data is requested
          type: string
    201_response_schema:
      properties:
        message:
          type:
          - string
          - 'null'
        request_id:
          description: UUID reference for the submitted request
          type: string
    ResumeUploadResponse:
      properties:
        message:
          description: Status message indicating the request was received.
          type: string
        request_id:
          description: Status message indicating the request was received.
          type: string
      type: object
    PossibleValuesGetResponse:
      properties:
        data:
          properties:
            field_name:
              description: The field name whose possible values are being returned
              type: string
            object_name:
              description: The object name for which possible values are configured
              type: string
            values:
              description: List of configured possible values, or null if none are set
              items:
                properties:
                  associationValue:
                    description: Optional association value if configured
                    type:
                    - string
                    - 'null'
                  label:
                    type: string
                  value:
                    oneOf:
                    - type: string
                    - type: number
                    - type: boolean
                required:
                - label
                - value
                type: object
              type:
              - array
              - 'null'
          type: object
        resource_id:
          description: The field name used in the request path
          type: string
      type: object
  securitySchemes:
    sense_authentication:
      flows:
        clientCredentials:
          scopes:
            N/A: The Sense API does not require a scope to be provided.
          tokenUrl: https://partner-auth.us-stage.sensehq.co/oauth2/token
      type: oauth2
    sense_bearer_auth:
      bearerFormat: JWT
      scheme: bearer
      type: http