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

# Create Phlebotomy Order

> Atomic create: validate refs + the client-rendered PDF → upload → insert
Document + PatientPhlebotomyOrder.

The order PDF is stamped in the browser onto OneBlood's published Form-96
(the single source of truth shared with the preview) and sent as the
``pdf`` part; the structured fields arrive as a JSON ``payload`` part. This
endpoint validates the patient / ordering provider / recipient (if
present) references and that the upload is a real PDF, then persists the
passed-in bytes — it does not re-derive the document. ``provider``
(CurrentProvider) gates the caller to an authenticated provider; the
*ordering* provider is chosen on the form and validated in the service, so
it need not match the caller.


## OpenAPI

````yaml post /phlebotomy-orders
openapi: 3.1.0
info:
  title: Decoda API
  description: External API documentation for the Decoda Health platform.
  version: '1.0'
servers: []
security: []
paths:
  /phlebotomy-orders:
    post:
      tags:
        - Phlebotomy Orders
      summary: Create Phlebotomy Order
      description: >-
        Atomic create: validate refs + the client-rendered PDF → upload → insert

        Document + PatientPhlebotomyOrder.


        The order PDF is stamped in the browser onto OneBlood's published
        Form-96

        (the single source of truth shared with the preview) and sent as the

        ``pdf`` part; the structured fields arrive as a JSON ``payload`` part.
        This

        endpoint validates the patient / ordering provider / recipient (if

        present) references and that the upload is a real PDF, then persists the

        passed-in bytes — it does not re-derive the document. ``provider``

        (CurrentProvider) gates the caller to an authenticated provider; the

        *ordering* provider is chosen on the form and validated in the service,
        so

        it need not match the caller.
      operationId: create_phlebotomy_order_phlebotomy_orders_post
      parameters:
        - name: TENANT
          in: header
          required: true
          schema:
            type: string
            title: Tenant
          description: The tenant you are making this request on behalf of
        - name: API-KEY
          in: header
          required: true
          schema:
            type: string
            title: Api-Key
          description: Your api key
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: >-
                #/components/schemas/Body_create_phlebotomy_order_phlebotomy_orders_post
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PhlebotomyOrderResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Body_create_phlebotomy_order_phlebotomy_orders_post:
      properties:
        payload:
          type: string
          title: Payload
        pdf:
          type: string
          contentMediaType: application/octet-stream
          title: Pdf
      type: object
      required:
        - payload
        - pdf
      title: Body_create_phlebotomy_order_phlebotomy_orders_post
    PhlebotomyOrderResponse:
      properties:
        id:
          type: string
          title: Id
        patientId:
          type: string
          title: Patientid
        orderingProviderId:
          type: string
          title: Orderingproviderid
        recipientFaxContactId:
          anyOf:
            - type: string
            - type: 'null'
          title: Recipientfaxcontactid
        diagnosisHh:
          type: boolean
          title: Diagnosishh
        diagnosisTt:
          type: boolean
          title: Diagnosistt
        otherDiagnoses:
          anyOf:
            - type: string
            - type: 'null'
          title: Otherdiagnoses
        frequency:
          anyOf:
            - $ref: '#/components/schemas/PhlebotomyFrequency'
            - type: 'null'
        otherFrequency:
          anyOf:
            - type: string
            - type: 'null'
          title: Otherfrequency
        hemoglobinThreshold:
          anyOf:
            - type: string
              pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
            - type: 'null'
          title: Hemoglobinthreshold
        amount:
          anyOf:
            - $ref: '#/components/schemas/PhlebotomyAmount'
            - type: 'null'
        otherAmountMl:
          anyOf:
            - type: integer
            - type: 'null'
          title: Otheramountml
        comments:
          anyOf:
            - type: string
            - type: 'null'
          title: Comments
        signatureUrl:
          anyOf:
            - type: string
            - type: 'null'
          title: Signatureurl
        formVersion:
          type: string
          title: Formversion
        sentAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Sentat
        sentChannels:
          items:
            $ref: '#/components/schemas/PhlebotomyOrderSentVia'
          type: array
          title: Sentchannels
        completedDate:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Completeddate
        completedByProviderId:
          anyOf:
            - type: string
            - type: 'null'
          title: Completedbyproviderid
        documentId:
          type: string
          title: Documentid
        documentFilePath:
          type: string
          title: Documentfilepath
        documentTitle:
          type: string
          title: Documenttitle
        createdDate:
          type: string
          format: date-time
          title: Createddate
      type: object
      required:
        - id
        - patientId
        - orderingProviderId
        - recipientFaxContactId
        - diagnosisHh
        - diagnosisTt
        - otherDiagnoses
        - frequency
        - otherFrequency
        - hemoglobinThreshold
        - amount
        - otherAmountMl
        - comments
        - signatureUrl
        - formVersion
        - sentAt
        - sentChannels
        - completedDate
        - completedByProviderId
        - documentId
        - documentFilePath
        - documentTitle
        - createdDate
      title: PhlebotomyOrderResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    PhlebotomyFrequency:
      type: string
      enum:
        - ONE_TIME
        - WEEKLY
        - EVERY_2_WEEKS
        - EVERY_4_WEEKS
        - EVERY_8_WEEKS
        - OTHER
      title: PhlebotomyFrequency
      description: |-
        Draw frequency on the OneBlood Form-96 phlebotomy order.

        Rendered as checkboxes on the form but functionally exclusive — a single
        selection, not independent booleans. ``OTHER`` carries free text in
        ``PatientPhlebotomyOrder.other_frequency``.
    PhlebotomyAmount:
      type: string
      enum:
        - ONE_UNIT
        - OTHER
      title: PhlebotomyAmount
      description: |-
        Draw amount on the OneBlood Form-96 phlebotomy order.

        Rendered as checkboxes on the form but functionally exclusive — a single
        selection, not independent booleans. ``OTHER`` carries a free-text mL
        amount in ``PatientPhlebotomyOrder.other_amount_ml``.
    PhlebotomyOrderSentVia:
      type: string
      enum:
        - EMAIL
        - FAX
        - PORTAL
      title: PhlebotomyOrderSentVia
      description: >-
        A channel a phlebotomy order's document went out on.


        Derived, never stamped — each member corresponds to a link that already

        exists once the document leaves the building:


        - ``FAX``: a ``fax_attachment`` row references the document

        - ``EMAIL``: an ``email_attachment`` row references the document

        - ``PORTAL``: ``document.shared_with_patient`` is set (a portal share,
        or
          the SMS that texts the patient a portal link)

        An order can therefore be on several channels at once, which is why the

        response carries a list rather than one "how was it sent" value.
    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

````