openapi: 3.0.3
info:
  title: Merge ATS API
  description: >-
    Unified API for integrating with 50+ applicant tracking systems including
    Greenhouse, Lever, Workday, iCIMS, and Jobvite. Provides standardized
    access to candidates, applications, interviews, job postings, offers,
    scorecards, and recruiting pipeline data.
  version: "1.0.0"
  contact:
    name: Merge Support
    url: https://help.merge.dev/
    email: support@merge.dev
  x-generated-from: documentation
  x-last-validated: "2026-04-18"
servers:
  - url: https://api.merge.dev/api/ats/v1
    description: Merge ATS API production server
security:
  - bearerAuth: []
    accountToken: []
paths:
  /candidates:
    get:
      operationId: listCandidates
      summary: Merge List Candidates
      description: Returns a list of Candidate objects from the connected ATS.
      tags:
        - Candidates
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/includeRemoteData'
        - name: created_after
          in: query
          schema:
            type: string
            format: date-time
          description: Filter by creation date.
        - name: modified_after
          in: query
          schema:
            type: string
            format: date-time
          description: Filter by modification date.
      responses:
        '200':
          description: A paginated list of Candidate objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedCandidateList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createCandidate
      summary: Merge Create Candidate
      description: Creates a Candidate object in the connected ATS.
      tags:
        - Candidates
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CandidateRequest'
      responses:
        '201':
          description: The created Candidate object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Candidate'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /candidates/{id}:
    get:
      operationId: getCandidate
      summary: Merge Get Candidate
      description: Returns a Candidate object with the given ID.
      tags:
        - Candidates
      parameters:
        - $ref: '#/components/parameters/resourceId'
        - $ref: '#/components/parameters/includeRemoteData'
      responses:
        '200':
          description: The Candidate object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Candidate'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications:
    get:
      operationId: listApplications
      summary: Merge List Applications
      description: Returns a list of Application objects.
      tags:
        - Applications
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/includeRemoteData'
        - name: candidate_id
          in: query
          schema:
            type: string
          description: Filter by candidate ID.
        - name: current_stage_id
          in: query
          schema:
            type: string
          description: Filter by current interview stage ID.
      responses:
        '200':
          description: A paginated list of Application objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedApplicationList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createApplication
      summary: Merge Create Application
      description: Creates an Application object in the connected ATS.
      tags:
        - Applications
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ApplicationRequest'
      responses:
        '201':
          description: The created Application object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Application'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /applications/{id}/change-stage:
    post:
      operationId: changeApplicationStage
      summary: Merge Change Application Stage
      description: Changes the interview stage for the given application.
      tags:
        - Applications
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                job_interview_stage:
                  type: string
                  format: uuid
              required:
                - job_interview_stage
      responses:
        '200':
          description: Stage changed successfully.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /jobs:
    get:
      operationId: listJobs
      summary: Merge List Jobs
      description: Returns a list of Job objects.
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/includeRemoteData'
        - name: status
          in: query
          schema:
            type: string
            enum:
              - OPEN
              - CLOSED
              - DRAFT
              - ARCHIVED
              - PENDING
          description: Filter by job status.
      responses:
        '200':
          description: A paginated list of Job objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedJobList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /jobs/{id}:
    get:
      operationId: getJob
      summary: Merge Get Job
      description: Returns a Job object with the given ID.
      tags:
        - Jobs
      parameters:
        - $ref: '#/components/parameters/resourceId'
        - $ref: '#/components/parameters/includeRemoteData'
      responses:
        '200':
          description: The Job object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /offers:
    get:
      operationId: listOffers
      summary: Merge List Offers
      description: Returns a list of Offer objects.
      tags:
        - Offers
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/includeRemoteData'
      responses:
        '200':
          description: A paginated list of Offer objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedOfferList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /interviews:
    get:
      operationId: listInterviews
      summary: Merge List Interviews
      description: Returns a list of ScheduledInterview objects.
      tags:
        - Interviews
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/includeRemoteData'
        - name: application_id
          in: query
          schema:
            type: string
          description: Filter by application ID.
      responses:
        '200':
          description: A paginated list of ScheduledInterview objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedScheduledInterviewList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /job-interview-stages:
    get:
      operationId: listJobInterviewStages
      summary: Merge List Job Interview Stages
      description: Returns a list of JobInterviewStage objects.
      tags:
        - Interviews
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/includeRemoteData'
        - name: job_id
          in: query
          schema:
            type: string
          description: Filter by job ID.
      responses:
        '200':
          description: A paginated list of JobInterviewStage objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedJobInterviewStageList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /scorecards:
    get:
      operationId: listScorecards
      summary: Merge List Scorecards
      description: Returns a list of Scorecard objects.
      tags:
        - Scorecards
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/includeRemoteData'
        - name: application_id
          in: query
          schema:
            type: string
          description: Filter by application ID.
        - name: interview_id
          in: query
          schema:
            type: string
          description: Filter by interview ID.
      responses:
        '200':
          description: A paginated list of Scorecard objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedScorecardList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /departments:
    get:
      operationId: listDepartments
      summary: Merge List Departments
      description: Returns a list of Department objects.
      tags:
        - Departments
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/includeRemoteData'
      responses:
        '200':
          description: A paginated list of Department objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDepartmentList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /offices:
    get:
      operationId: listOffices
      summary: Merge List Offices
      description: Returns a list of Office objects.
      tags:
        - Offices
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/includeRemoteData'
      responses:
        '200':
          description: A paginated list of Office objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedOfficeList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /eeocs:
    get:
      operationId: listEEOCs
      summary: Merge List EEOCs
      description: Returns a list of EEOC objects containing diversity data.
      tags:
        - EEOCs
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/includeRemoteData'
      responses:
        '200':
          description: A paginated list of EEOC objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedEEOCList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /activities:
    get:
      operationId: listActivities
      summary: Merge List Activities
      description: Returns a list of Activity objects (notes, emails, etc.).
      tags:
        - Activities
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/includeRemoteData'
      responses:
        '200':
          description: A paginated list of Activity objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedActivityList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createActivity
      summary: Merge Create Activity
      description: Creates an Activity object in the connected ATS.
      tags:
        - Activities
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ActivityRequest'
      responses:
        '201':
          description: The created Activity object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Activity'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /tags:
    get:
      operationId: listTags
      summary: Merge List Tags
      description: Returns a list of Tag objects used to categorize candidates.
      tags:
        - Tags
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/includeRemoteData'
      responses:
        '200':
          description: A paginated list of Tag objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedTagList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /users:
    get:
      operationId: listUsers
      summary: Merge List Users
      description: Returns a list of RemoteUser objects (recruiters, hiring managers).
      tags:
        - Users
      parameters:
        - $ref: '#/components/parameters/cursor'
        - $ref: '#/components/parameters/pageSize'
        - $ref: '#/components/parameters/includeRemoteData'
      responses:
        '200':
          description: A paginated list of RemoteUser objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedRemoteUserList'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    accountToken:
      type: apiKey
      in: header
      name: X-Account-Token
  parameters:
    cursor:
      name: cursor
      in: query
      schema:
        type: string
      description: Pagination cursor for the next page.
    pageSize:
      name: page_size
      in: query
      schema:
        type: integer
        default: 100
      description: Number of results per page.
    includeRemoteData:
      name: include_remote_data
      in: query
      schema:
        type: boolean
      description: Whether to include raw third-party data.
    resourceId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: The unique identifier of the resource.
  responses:
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      properties:
        detail:
          type: string
          example: "Not found."
    Candidate:
      type: object
      description: A candidate in the recruiting pipeline.
      properties:
        id:
          type: string
          format: uuid
          example: "521b18c2-4d01-4297-b451-19858d07c133"
        remote_id:
          type: string
          example: "21198"
        first_name:
          type: string
          example: "Gil"
        last_name:
          type: string
          example: "Feig"
        company:
          type: string
          example: "Columbia Dining App"
        title:
          type: string
          example: "Software Engineer"
        is_private:
          type: boolean
        can_email:
          type: boolean
        email_addresses:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
                format: email
              email_address_type:
                type: string
                enum:
                  - PERSONAL
                  - WORK
                  - OTHER
        phone_numbers:
          type: array
          items:
            type: object
            properties:
              value:
                type: string
              phone_number_type:
                type: string
                enum:
                  - HOME
                  - WORK
                  - MOBILE
                  - SKYPE
                  - OTHER
        tags:
          type: array
          items:
            type: string
        applications:
          type: array
          items:
            type: string
            format: uuid
        attachments:
          type: array
          items:
            type: string
            format: uuid
        remote_was_deleted:
          type: boolean
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
    CandidateRequest:
      type: object
      properties:
        model:
          type: object
          properties:
            first_name:
              type: string
            last_name:
              type: string
            company:
              type: string
            title:
              type: string
            is_private:
              type: boolean
            email_addresses:
              type: array
              items:
                type: object
                properties:
                  value:
                    type: string
                  email_address_type:
                    type: string
            phone_numbers:
              type: array
              items:
                type: object
                properties:
                  value:
                    type: string
                  phone_number_type:
                    type: string
    Application:
      type: object
      description: An application linking a candidate to a job.
      properties:
        id:
          type: string
          format: uuid
          example: "92e8a369-fbe6-489b-b0b6-222b8b31a4d0"
        remote_id:
          type: string
        candidate:
          type: string
          format: uuid
        job:
          type: string
          format: uuid
        applied_at:
          type: string
          format: date-time
        rejected_at:
          type: string
          format: date-time
        source:
          type: string
          example: "LinkedIn"
        credited_to:
          type: string
          format: uuid
        current_stage:
          type: string
          format: uuid
        reject_reason:
          type: string
          format: uuid
        remote_was_deleted:
          type: boolean
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
    ApplicationRequest:
      type: object
      properties:
        model:
          type: object
          properties:
            candidate:
              type: string
              format: uuid
            job:
              type: string
              format: uuid
            applied_at:
              type: string
              format: date-time
            source:
              type: string
    Job:
      type: object
      description: A job posting in the ATS.
      properties:
        id:
          type: string
          format: uuid
          example: "c640b80b-fac9-409f-aa19-1f9221aec445"
        remote_id:
          type: string
        name:
          type: string
          example: "Software Engineer, Backend"
        status:
          type: string
          enum:
            - OPEN
            - CLOSED
            - DRAFT
            - ARCHIVED
            - PENDING
          example: "OPEN"
        departments:
          type: array
          items:
            type: string
            format: uuid
        offices:
          type: array
          items:
            type: string
            format: uuid
        hiring_managers:
          type: array
          items:
            type: string
            format: uuid
        recruiters:
          type: array
          items:
            type: string
            format: uuid
        remote_created_at:
          type: string
          format: date-time
        remote_updated_at:
          type: string
          format: date-time
        confidential:
          type: boolean
        remote_was_deleted:
          type: boolean
        created_at:
          type: string
          format: date-time
        modified_at:
          type: string
          format: date-time
    Offer:
      type: object
      properties:
        id:
          type: string
          format: uuid
        remote_id:
          type: string
        application:
          type: string
          format: uuid
        creator:
          type: string
          format: uuid
        status:
          type: string
          enum:
            - DRAFT
            - APPROVAL_SENT
            - APPROVED
            - SENT
            - SENT_MANUALLY
            - OPENED
            - DENIED
            - SIGNED
            - DEPRECATED
          example: "SENT"
        start_date:
          type: string
          format: date-time
        closed_at:
          type: string
          format: date-time
        sent_at:
          type: string
          format: date-time
        remote_was_deleted:
          type: boolean
    ScheduledInterview:
      type: object
      properties:
        id:
          type: string
          format: uuid
        remote_id:
          type: string
        application:
          type: string
          format: uuid
        job_interview_stage:
          type: string
          format: uuid
        organizer:
          type: string
          format: uuid
        interviewers:
          type: array
          items:
            type: string
            format: uuid
        location:
          type: string
        start_at:
          type: string
          format: date-time
        end_at:
          type: string
          format: date-time
        status:
          type: string
          enum:
            - SCHEDULED
            - AWAITING_FEEDBACK
            - COMPLETE
        remote_was_deleted:
          type: boolean
    JobInterviewStage:
      type: object
      properties:
        id:
          type: string
          format: uuid
        remote_id:
          type: string
        name:
          type: string
          example: "Phone Screen"
        job:
          type: string
          format: uuid
        stage_order:
          type: integer
        remote_was_deleted:
          type: boolean
    Scorecard:
      type: object
      properties:
        id:
          type: string
          format: uuid
        remote_id:
          type: string
        application:
          type: string
          format: uuid
        interview:
          type: string
          format: uuid
        interviewer:
          type: string
          format: uuid
        submitted_at:
          type: string
          format: date-time
        overall_recommendation:
          type: string
          enum:
            - DEFINITELY_NO
            - NO
            - YES
            - STRONG_YES
            - NO_DECISION
          example: "YES"
        remote_was_deleted:
          type: boolean
    Department:
      type: object
      properties:
        id:
          type: string
          format: uuid
        remote_id:
          type: string
        name:
          type: string
          example: "Engineering"
        remote_was_deleted:
          type: boolean
    Office:
      type: object
      properties:
        id:
          type: string
          format: uuid
        remote_id:
          type: string
        name:
          type: string
          example: "San Francisco"
        location:
          type: string
        remote_was_deleted:
          type: boolean
    EEOC:
      type: object
      properties:
        id:
          type: string
          format: uuid
        remote_id:
          type: string
        candidate:
          type: string
          format: uuid
        race:
          type: string
        gender:
          type: string
        veteran_status:
          type: string
        disability_status:
          type: string
        remote_was_deleted:
          type: boolean
    Activity:
      type: object
      properties:
        id:
          type: string
          format: uuid
        remote_id:
          type: string
        user:
          type: string
          format: uuid
        activity_type:
          type: string
          enum:
            - NOTE
            - EMAIL
            - OTHER
          example: "NOTE"
        subject:
          type: string
          example: "Phone screen follow-up"
        body:
          type: string
          example: "Great conversation with the candidate about their experience."
        remote_was_deleted:
          type: boolean
    ActivityRequest:
      type: object
      properties:
        model:
          type: object
          properties:
            user:
              type: string
              format: uuid
            activity_type:
              type: string
            subject:
              type: string
            body:
              type: string
    Tag:
      type: object
      properties:
        name:
          type: string
          example: "High Priority"
        remote_was_deleted:
          type: boolean
    RemoteUser:
      type: object
      properties:
        id:
          type: string
          format: uuid
        remote_id:
          type: string
        first_name:
          type: string
          example: "Shensi"
        last_name:
          type: string
          example: "Ding"
        email:
          type: string
          format: email
          example: "shensi@merge.dev"
        disabled:
          type: boolean
        access_role:
          type: string
          enum:
            - SUPER_ADMIN
            - ADMIN
            - TEAM_MEMBER
            - LIMITED_TEAM_MEMBER
            - INTERVIEWER
        remote_was_deleted:
          type: boolean
    PaginatedCandidateList:
      type: object
      properties:
        next:
          type: string
        previous:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/Candidate'
    PaginatedApplicationList:
      type: object
      properties:
        next:
          type: string
        previous:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/Application'
    PaginatedJobList:
      type: object
      properties:
        next:
          type: string
        previous:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/Job'
    PaginatedOfferList:
      type: object
      properties:
        next:
          type: string
        previous:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/Offer'
    PaginatedScheduledInterviewList:
      type: object
      properties:
        next:
          type: string
        previous:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/ScheduledInterview'
    PaginatedJobInterviewStageList:
      type: object
      properties:
        next:
          type: string
        previous:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/JobInterviewStage'
    PaginatedScorecardList:
      type: object
      properties:
        next:
          type: string
        previous:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/Scorecard'
    PaginatedDepartmentList:
      type: object
      properties:
        next:
          type: string
        previous:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/Department'
    PaginatedOfficeList:
      type: object
      properties:
        next:
          type: string
        previous:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/Office'
    PaginatedEEOCList:
      type: object
      properties:
        next:
          type: string
        previous:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/EEOC'
    PaginatedActivityList:
      type: object
      properties:
        next:
          type: string
        previous:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/Activity'
    PaginatedTagList:
      type: object
      properties:
        next:
          type: string
        previous:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    PaginatedRemoteUserList:
      type: object
      properties:
        next:
          type: string
        previous:
          type: string
        results:
          type: array
          items:
            $ref: '#/components/schemas/RemoteUser'