> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bindbee.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Candidate

> Creates a Candidate object with the given values.

To create an candidate in ATS, you first need to fetch the request body structure that ATS expects. This structure varies based on the ATS provider (e.g., Greenhouse, Teamtailor, BambooHR). The request body consists of three parts:

* **Model Keys**: Standard attributes required for all candidate.
* **Additional Attributes**: Specific fields required by the chosen ATS.
* **Custom Fields**: Extra metadata for specific implementations.

**Note:** Some attributes may have `allowed_values`, meaning only specific values are permitted based on the customer's ATS configuration. Ensure you check for these constraints before submitting the request.

## Step 1: Fetch the Required Request Body

Before calling the **Create Candidate** API, you need to get the request structure using the  [Meta Create Candidate](/ats/candidate/meta-create-candidate) API.

## Step 2: Create an Candidate

Once you have the request body structure, use the **Create Candidate** API to send the request.


## OpenAPI

````yaml post /api/ats/v1/candidates
openapi: 3.1.0
info:
  title: Bindbee APIs
  version: 0.1.0
servers:
  - url: https://api.bindbee.dev
  - url: https://api-eu.bindbee.dev
security: []
paths:
  /api/ats/v1/candidates:
    post:
      tags:
        - Candidate
      summary: Create Candidate
      description: Creates a Candidate object with the given values.
      operationId: create_candidate_api_ats_v1_candidates_post
      parameters:
        - name: x-connector-token
          in: header
          required: true
          schema:
            type: string
            title: X-Connector-Token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              anyOf:
                - $ref: '#/components/schemas/CreateCandidate'
                - $ref: '#/components/schemas/AtsCandidateWrite'
              title: Candidate
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - HTTPBearer: []
components:
  schemas:
    CreateCandidate:
      properties:
        data:
          $ref: '#/components/schemas/PostCandidate'
        remote_user_id:
          type: string
          title: Remote User Id
          description: The remote user's id
          examples:
            - 018b4bfb-5ece-70b1-ad5e-862a9433aa65
        job_requisition_id:
          type: string
          title: Job Requisition Id
          description: The job requisition id in external ATS
          examples:
            - R-00007
      type: object
      required:
        - data
      title: CreateCandidate
    AtsCandidateWrite:
      properties:
        additional_attributes:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Additional Attributes
          description: Specific fields required by the chosen HRIS
          examples:
            - contract_end_date: '2025-12-31T00:00:00'
              previous_employer: TechCorp
        custom_fields:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Custom Fields
          description: The custom fields related to the model
          examples:
            - customTshirtSize: XXL
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
          description: The candidate's first name.
          examples:
            - John
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
          description: The candidate's last name.
          examples:
            - Doe
        company:
          anyOf:
            - type: string
            - type: 'null'
          title: Company
          description: The name of the company where candidate has applied.
          examples:
            - Google
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: The position for which the candidate has applied
          examples:
            - SOFTWARE ENGINEER
        last_interaction_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Interaction At
          description: The date of the last interaction with the candidate.
          examples:
            - '2021-07-01T00:00:00Z'
        is_private:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Private
          description: Whether the candidate's information is private.
          examples:
            - true
        can_email:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Can Email
          description: Whether the candidate can be emailed.
          examples:
            - true
        locations:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Locations
          description: The location of the candidate.
          examples:
            - San Francisco
            - New York
        phone_numbers:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Phone Numbers
          description: The candidate's phone numbers.
          examples:
            - 123-456-7890
        email_addresses:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Email Addresses
          description: The candidate's email addresses.
          examples:
            - john@doe.com
        urls:
          anyOf:
            - items:
                $ref: '#/components/schemas/AtsUrl'
              type: array
            - type: 'null'
          title: Urls
          description: >-
            The candidate's URLs. This can include a personal website, LinkedIn
            profile, or other relevant URLs.
          examples:
            - type: LINKEDIN
              value: https://www.linkedin.com/in/johndoe
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tags
          description: >-
            The candidate's tags. Tags are used to categorize candidates and can
            be used to filter candidates in the UI.
          examples:
            - JUNIOR
            - INTERMEDIATE
        applications:
          anyOf:
            - items: {}
              type: array
            - type: 'null'
          title: Applications
          description: The candidate's applications.
          examples:
            - 018b4bfb-5ece-70b1-ad5e-862a9433aa65
        attachments:
          anyOf:
            - items:
                $ref: '#/components/schemas/AtsAttachmentWrite'
              type: array
            - type: 'null'
          title: Attachments
          description: >-
            Please share the details like this, AtsAttachmentWrite model fields
            are shared in model_fields key
          examples:
            - attachment_type: RESUME
              file_name: resume.pdf
              file_url: https://example.com/resume.pdf
        remote_created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Remote Created At
          description: When the third party's candidate was created.
          examples:
            - '2021-07-01T00:00:00Z'
        remote_updated_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Remote Updated At
          description: When the third party's candidate was last updated.
          examples:
            - '2021-07-01T00:00:00Z'
        avatar:
          anyOf:
            - type: string
            - type: 'null'
          title: Avatar
          description: The candidate's avatar.
          examples:
            - https://www.example.com/avatar.jpg
        job:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Job
          description: The job id for the candidate
          examples:
            - 018b4bfb-5ece-70b1-ad5e-862a9433aa65
      type: object
      title: AtsCandidateWrite
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PostCandidate:
      properties:
        first_name:
          anyOf:
            - type: string
            - type: 'null'
          title: First Name
          description: The candidate's first name.
          examples:
            - John
        last_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Name
          description: The candidate's last name.
          examples:
            - Doe
        company:
          anyOf:
            - type: string
            - type: 'null'
          title: Company
          description: The name of the company where candidate has applied.
          examples:
            - Google
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: The position for which the candidate has applied
          examples:
            - SOFTWARE ENGINEER
        is_private:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Private
          description: Whether the candidate's information is private.
          examples:
            - true
        can_email:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Can Email
          description: Whether the candidate can be emailed.
          examples:
            - true
        locations:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Locations
          description: The location of the candidate.
          default: []
          examples:
            - San Francisco
            - New York
        phone_numbers:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Phone Numbers
          description: The candidate's phone numbers.
          default: []
          examples:
            - 123-456-7890
        email_addresses:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Email Addresses
          description: The candidate's email addresses.
          default: []
          examples:
            - john@doe.com
        urls:
          anyOf:
            - items:
                $ref: '#/components/schemas/AtsUrl'
              type: array
            - type: 'null'
          title: Urls
          description: >-
            The candidate's URLs. This can include a personal website, LinkedIn
            profile, or other relevant URLs.
          default: []
          examples:
            - type: LINKEDIN
              value: https://www.linkedin.com/in/johndoe
        tags:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Tags
          description: >-
            The candidate's tags. Tags are used to categorize candidates and can
            be used to filter candidates in the UI.
          default: []
          examples:
            - JUNIOR
            - INTERMEDIATE
        applications:
          anyOf:
            - items:
                type: string
                format: uuid
              type: array
            - type: 'null'
          title: Applications
          description: The candidate's applications.
          default: []
          examples:
            - 018b4bfb-5ece-70b1-ad5e-862a9433aa65
        attachments:
          anyOf:
            - items:
                type: string
                format: uuid
              type: array
            - type: 'null'
          title: Attachments
          description: The candidate's attachments.
          default: []
          examples:
            - 018b4bfb-5ece-70b1-ad5e-862a9433aa65
        avatar:
          anyOf:
            - type: string
            - type: 'null'
          title: Avatar
          description: The candidate's avatar.
          examples:
            - https://www.example.com/avatar.jpg
        job_interview_stage_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Job Interview Stage Id
          description: The job stage id for the candidate
          examples:
            - 018b4bfb-5ece-70b1-ad5e-862a9433aa65
        job_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Job Id
          description: The job id for the candidate
          examples:
            - 018b4bfb-5ece-70b1-ad5e-862a9433aa65
      type: object
      title: PostCandidate
    AtsUrl:
      properties:
        value:
          anyOf:
            - type: string
            - type: 'null'
          title: Value
          description: The site's url.
        url_type:
          anyOf:
            - type: string
            - type: 'null'
          enum:
            - PERSONAL
            - COMPANY
            - PORTFOLIO
            - BLOG
            - SOCIAL_MEDIA
            - OTHER
            - JOB_POSTING
            - '-'
          title: Url Type
          description: >-
            The type of site. If the value is not one of the defined enum
            values, the original value passed through will be returned.
      type: object
      required:
        - value
        - url_type
      title: AtsUrl
    AtsAttachmentWrite:
      properties:
        file_name:
          anyOf:
            - type: string
            - type: 'null'
          title: File Name
          description: The name of the file attached.
          examples:
            - resume.pdf
        file_url:
          anyOf:
            - type: string
              maxLength: 2083
              minLength: 1
              format: uri
            - type: 'null'
          title: File Url
          description: The URL where the file is stored and can be retrieved.
          examples:
            - https://example.com/path/to/resume.pdf
        attachment_type:
          anyOf:
            - type: string
            - type: 'null'
          enum:
            - RESUME
            - COVER_LETTER
            - OFFER_LETTER
            - OTHER
            - '-'
          title: Attachment Type
          description: >-
            The type of attachment. If the value is not one of the defined enum
            values, the original value passed through will be returned.
          examples:
            - RESUME
        file_content:
          anyOf:
            - type: string
            - type: 'null'
          title: File Content
          description: File in base64 format
          examples:
            - SGVsbG8sIFdvcmxkIQ==
        content_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Content Type
          description: The MIME type of the file (e.g., 'application/pdf', 'image/png').
          examples:
            - application/pdf
        candidate:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Candidate
          description: The candidate to whom the attachment belongs.
          examples:
            - 018b4bfb-5ece-70b1-ad5e-862a9433aa65
        remote_user_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Remote User Id
          description: The id of user using the integration
          examples:
            - 018b4bfb-5ece-70b1-ad5e-862a9433aa65
      type: object
      title: AtsAttachmentWrite
      description: >-
        The AtsAttachmentWriteForCandidate object is used to represent a file
        attachment linked to a candidate's application within the ATS.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer

````