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

# Search orders

> Search orders by order number, ID, patient fields, or a substring.



## OpenAPI

````yaml /openapi-public.yml get /api/v1/search/orders
openapi: 3.0.3
info:
  title: Blend API
  version: 1.0.0
  description: API for Blend
servers:
  - url: https://api.byblend.com
    description: Blend production server
security:
  - bearerAuth: []
tags:
  - name: Orders
    description: Order management endpoints
  - name: Patients
    description: Patient management endpoints
  - name: Reports
    description: Reporting endpoints
  - name: Products and Materials
    description: Product catalog and inventory endpoints
  - name: Electronic Prescriptions
    description: Electronic prescription management endpoints
  - name: Prescriptions
    description: Prescription management endpoints
  - name: Authentication
    description: Authentication endpoints
  - name: Notifications
    description: User management endpoints
  - name: Prescribers
paths:
  /api/v1/search/orders:
    get:
      tags:
        - Search
      summary: Search orders
      description: Search orders by order number, ID, patient fields, or a substring.
      parameters:
        - name: q
          in: query
          required: true
          description: Search query
          schema:
            type: string
            example: ORD8272
        - name: limit
          in: query
          required: false
          description: >-
            Optional limit on the number of results to return. Max is 100,
            default is 50.
          schema:
            type: integer
            example: 10
      responses:
        '200':
          description: Successful response with array of orders
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      allOf:
                        - $ref: '#/components/schemas/SearchRank'
                        - type: object
                          properties:
                            is_patient_order:
                              type: boolean
                              example: true
                              description: If the result matched on the order's patient.
                        - $ref: '#/components/schemas/Order'
components:
  schemas:
    SearchRank:
      type: object
      properties:
        rank:
          type: number
          example: 0.7
          description: >-
            Ranking score of the search result, from 0 to 1, indicating
            relevance to the search query
    Order:
      allOf:
        - $ref: '#/components/schemas/ID'
        - $ref: '#/components/schemas/Timestamps'
        - type: object
          properties:
            address:
              $ref: '#/components/schemas/Address'
            custom_shipping:
              $ref: '#/components/schemas/OrderCustomShipping'
              description: >-
                Custom shipping details for the order if your account has custom
                shipping enabled, and you have provided prepaid label details.
            customer_id:
              type: string
              format: uuid
              example: b658f16f-819c-4503-aede-bd555fc4ebfb
            external_id:
              type: string
              example: my-system-128318AA2
              description: External (your own system's) ID associated with the order.
            is_replacement:
              type: boolean
              example: false
              description: Whether the order is a replacement order
            order_number:
              type: string
              example: ORD250312003548IAU4
              description: Friendlier identifier for the order. Auto-generated.
            original_order_id:
              type: string
              format: uuid
              example: 0227d1e5-ba9a-42b5-8fe2-38882aa65708
              description: ID of the original order, if this is a replacement order
            patient:
              $ref: '#/components/schemas/PatientOrder'
            prescription_count:
              type: integer
              example: 1
              description: >-
                Number of prescriptions associated with the order (expected to
                be the same as the number of prescription products in the
                products object)
            priority_requested:
              type: boolean
              example: false
              description: Whether the order has a priority request
            cancellation_requested:
              type: boolean
              example: false
              description: >-
                Whether the customer has requested cancellation for an order in
                picked or verified status
            replacement_order_ids:
              type: array
              items:
                type: string
                format: uuid
                example: 0227d1e5-ba9a-42b5-8fe2-38882aa65708
                description: >-
                  IDs of any replacement orders, if they have been created from
                  this order
            replacement_reason:
              type: string
              example: Product arrived damaged
              description: If this is a replacement order, reason for the replacement
            replacement_requested:
              type: boolean
              example: false
              description: >-
                Whether the order has a replacement request. This field is
                deprecated and will be removed in a future version. Please use
                replacement_request_status instead.
            replacement_request_status:
              type: string
              example: pending
              description: Status of the replacement request
              enum:
                - pending
                - fulfilled
                - declined
                - cancelled
            replacement_requested_at:
              type: string
              example: '2025-01-01T00:00:00Z'
              description: Date and time a replacement request was made
            replacement_requested_reason:
              type: string
              example: Product arrived damaged
              description: Reason for the replacement request
            shipments:
              type: array
              items:
                $ref: '#/components/schemas/OrderShipment'
                description: >-
                  Once an order has been shipped, details on its shipment(s)
                  will be provided in this array.
            shipping:
              type: object
              properties:
                carrier:
                  type: string
                  example: usps
                  description: Desired shipment carrier.
                service_level:
                  type: string
                  example: usps_ground_advantage
                  description: Desired shipment service level.
            status:
              type: string
              example: received
              description: >-
                Order status. One of `received`, `picked`, `verified`,
                `exception`, `paused`, `shipped`, `delivered`, `cancelled`,
                `returned`.
            paused_until:
              type: string
              format: date-time
              nullable: true
              example: '2026-08-07T00:00:00'
              description: >-
                When an order is paused, midnight UTC of the pause-until
                calendar day. The order automatically unpauses when this date is
                reached. `null` when the pause is indefinite or the order is not
                paused.
    ID:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier
          example: 0227d1e5-ba9a-42b5-8fe2-38882aa65708
    Timestamps:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
          description: Date and time of creation
          example: '2025-03-15T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: Date and time of last update
          example: '2025-03-15T12:00:00Z'
    Address:
      allOf:
        - $ref: '#/components/schemas/ID'
        - type: object
          properties:
            address_1:
              type: string
              example: 140 Lindgren Streets
            address_2:
              type: string
              example: Apt 227
            city:
              type: string
              example: North Consueloburgh
            state:
              type: string
              description: Two-letter state abbreviation
              example: CA
            country:
              type: string
              description: Two-letter country code
              example: US
            type:
              type: string
              description: Type of address, if applicable
              example: shipping
            zip_code:
              type: string
              description: 5-digit ZIP code or ZIP+4 code, e.g. 02108 or 02108-1234
              example: '02108'
    OrderCustomShipping:
      type: object
      properties:
        label_url:
          type: string
          example: https://example.com/label.pdf
          description: URL of the printable (4x6) custom shipping label
        tracking_number:
          type: string
          example: TEST123456
          description: Tracking number from the custom shipping label
        tracking_url:
          type: string
          example: https://example.com/track/TEST123456
          description: Tracking URL of the custom shipping label
        carrier:
          type: string
          example: UPS
          description: Carrier of the custom shipping label
    PatientOrder:
      allOf:
        - $ref: '#/components/schemas/ID'
        - $ref: '#/components/schemas/Timestamps'
        - $ref: '#/components/schemas/PatientBase'
    OrderShipment:
      type: object
      properties:
        carrier:
          type: string
          example: USPS
          description: Shipment carrier.
        created_at:
          type: string
          format: date-time
          example: '2026-04-17T18:31:05.175498'
          description: >-
            Date and time the package label was purchased and the item marked
            shipped.
        delivered_at:
          type: string
          format: date-time
          example: '2026-04-17T18:31:05.175498'
          description: Date and time the shipment was delivered.
        id:
          type: string
          format: uuid
          example: 0239CA06-9A71-4FFE-8A8D-5403540A19E7
          description: Blend internal shipment ID.
        service_level:
          type: string
          example: Ground Advantage
          description: Shipment service level.
        status:
          type: string
          example: shipped
          description: Status of the shipment.
          enum:
            - shipped
            - cancelled
            - delivered
        tracking_number:
          type: string
          example: '9200190347375200467807'
          description: Tracking number for the shipment.
        tracking_url:
          type: string
          example: >-
            https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9200190347375200467807
          description: Tracking URL for the shipment.
    PatientBase:
      type: object
      properties:
        first_name:
          type: string
          example: Willard
        middle_name:
          type: string
          example: Moises
        last_name:
          type: string
          example: Donnelly
        gender:
          type: string
          enum:
            - male
            - female
          example: male
          description: Gender of the patient
        email:
          type: string
          example: Harmon43@gmail.com
        phone:
          type: string
          description: 10-digit phone number without formatting, e.g. 6417383445
          example: '6417383445'
        date_of_birth:
          type: string
          format: date
          example: '1990-01-01'
        driver_license_number:
          type: string
          example: B49188319
        driver_license_state:
          type: string
          example: CA
        ssn:
          type: string
          example: '123456789'
          description: Social Security number. Can be provided with or without hyphens.
        primary_language:
          type: string
          description: ISO 639-1 language code
          example: en
        guardian_name:
          type: string
          description: Name of the patient's guardian. Required if patient is a minor.
          example: John Guardian
        guardian_phone:
          type: string
          example: '6417383445'
        guardian_email:
          type: string
          example: parent@example.com
        guardian_relationship:
          type: string
          description: >-
            Relationship of the guardian to the patient. See relationship types
            lookup for available values; most common are `parent` and
            `legal_guardian`; and `other` can be used.
          example: parent
        height_inches:
          type: integer
          example: 72
          description: Height of the patient in inches
        weight_pounds:
          type: integer
          example: 180
          description: Weight of the patient in pounds
        external_id:
          type: string
          example: '1234567890'
          description: >-
            External (your own) ID for the patient, to be used for prescription
            matching
        is_smoker:
          type: boolean
          example: false
          description: Whether the patient is a smoker
        is_diabetic:
          type: boolean
          example: false
          description: Whether the patient is diabetic
        is_pregnant:
          type: boolean
          example: false
          description: Whether the patient is pregnant
        receive_sms:
          type: boolean
          example: true
          description: >-
            Whether the patient should receive SMS notifications for shipments.
            This is only applicable if you have authorized Blend to send patient
            communications on your behalf.
        receive_email:
          type: boolean
          example: true
          description: >-
            Whether the patient should receive email notifications for
            shipments. This is only applicable if you have authorized Blend to
            send patient communications on your behalf.
        address:
          $ref: '#/components/schemas/AddressCreate'
    AddressCreate:
      type: object
      required:
        - address_1
        - city
        - state
        - zip_code
      properties:
        address_1:
          type: string
          example: 140 Lindgren Streets
        address_2:
          type: string
          example: Apt 227
        city:
          type: string
          example: North Consueloburgh
        state:
          type: string
          description: Two-letter state abbreviation
          example: CA
        country:
          type: string
          description: Two-letter country code, defaults to US
          example: US
        zip_code:
          type: string
          description: 5-digit ZIP code or 9-digit ZIP+4 code, e.g. 02108 or 02108-1234.
          example: '02108'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````