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

# Create a Placement

> Bind a candidate to a job. Idempotent on `(jobId, externalUser)` — a repeat call returns the existing placement.



## OpenAPI

````yaml POST /placement
openapi: 3.0.1
info:
  title: Ready Health API
  description: ''
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.readyhealth.com
security:
  - ApiKeyAuth: []
paths:
  /placement:
    post:
      summary: Create a placement
      description: >-
        Bind a candidate to a job. Idempotent on `(jobId, externalUser)` — a
        repeat call returns the existing placement.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NewPlacement'
      responses:
        '201':
          description: Placement. Same shape as `GET /placement/{id}`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Placement'
components:
  schemas:
    NewPlacement:
      type: object
      required:
        - externalId
        - jobId
      properties:
        externalId:
          type: string
          description: Candidate ID in your system.
        jobId:
          type: string
          format: uuid
          description: Ready Health job ID (`POST /job` / `GET /job/{id}`).
        atsPlacementRefId:
          type: string
          description: Placement ID in the ATS.
        vmsPlacementRefId:
          type: string
        candidateName:
          type: string
        candidateEmail:
          type: string
        candidatePhone:
          type: string
        startDate:
          type: string
          format: date
          description: Assignment start date (`YYYY-MM-DD` or ISO).
    Placement:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          $ref: '#/components/schemas/PlacementStatus'
        job:
          type: object
          properties:
            id:
              type: string
              format: uuid
            title:
              type: string
              nullable: true
            vmsJobRefId:
              type: string
        candidate:
          type: object
          properties:
            id:
              type: string
              format: uuid
            externalId:
              type: string
        atsPlacementRefId:
          type: string
          nullable: true
        vmsPlacementRefId:
          type: string
          nullable: true
        packets:
          type: array
          items:
            $ref: '#/components/schemas/PacketRef'
        requirementCount:
          type: integer
        fulfilledCount:
          type: integer
        requirements:
          type: array
          items:
            $ref: '#/components/schemas/PlacementRequirement'
    PlacementStatus:
      type: string
      enum:
        - ACTIVE
        - COMPLETED
        - CANCELLED
    PacketRef:
      type: object
      properties:
        id:
          type: string
          format: uuid
        packetGroup:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/PacketStatus'
    PlacementRequirement:
      type: object
      properties:
        id:
          type: string
          format: uuid
        vmsRequirementName:
          type: string
        packetGroup:
          type: string
          nullable: true
        fulfillmentType:
          $ref: '#/components/schemas/FulfillmentType'
        documentCategory:
          type: string
          nullable: true
        documentType:
          type: string
          nullable: true
        requirementKey:
          type: string
          nullable: true
        status:
          $ref: '#/components/schemas/RequirementStatus'
        isMapped:
          type: boolean
        sortOrder:
          type: integer
    PacketStatus:
      type: string
      enum:
        - INCOMPLETE
        - COMPLETE
        - COMPILING
        - COMPILED
        - UPLOADING
        - UPLOADED
        - FAILED
    FulfillmentType:
      type: string
      enum:
        - DOCUMENT
        - REGISTRY_SEARCH
        - STATEMENT
        - PASS_THROUGH
    RequirementStatus:
      type: string
      enum:
        - PENDING
        - AWAITING_CONFIG
        - IN_PROGRESS
        - FULFILLED
        - REJECTED
        - INVALIDATED
        - EXPIRED
        - SKIPPED
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````