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

# Purchase Order Search API

> Search purchase orders by PO number or vendor. Returns up to 20 matching results.

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
```

## Request

### Query Parameters

At least one of `poNumber` or `vendorId` must be provided.

| Parameter  | Type   | Required | Description                                                |
| ---------- | ------ | -------- | ---------------------------------------------------------- |
| `poNumber` | string | No       | Partial or full PO number to search for (case-insensitive) |
| `vendorId` | string | No       | Exact vendor slug identifier to filter by                  |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  # Search by PO number
  curl -X GET "https://api.pazy.io/v1.0/procurement/purchase-order/search?poNumber=PO-2024" \
    -H "Authorization: Api-Key YOUR_API_KEY"

  # Search by vendor
  curl -X GET "https://api.pazy.io/v1.0/procurement/purchase-order/search?vendorId=vendor_identifier" \
    -H "Authorization: Api-Key YOUR_API_KEY"

  # Search with both filters
  curl -X GET "https://api.pazy.io/v1.0/procurement/purchase-order/search?poNumber=PO-2024&vendorId=vendor_identifier" \
    -H "Authorization: Api-Key YOUR_API_KEY"
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  // Search by PO number
  const params = new URLSearchParams({ poNumber: 'PO-2024' });
  const response = await fetch(`https://api.pazy.io/v1.0/procurement/purchase-order/search?${params}`, {
    method: 'GET',
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY'
    }
  });

  const result = await response.json();
  ```

  ```python Python (requests) theme={null}
  import requests

  url = "https://api.pazy.io/v1.0/procurement/purchase-order/search"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY"
  }

  # Search by PO number
  params = { "poNumber": "PO-2024" }

  response = requests.get(url, headers=headers, params=params)
  result = response.json()
  ```
</CodeGroup>

## Success Response

**HTTP Status:** `200 OK`

Returns up to 20 purchase orders matching the search criteria, ordered by creation date (newest first). Archived POs are excluded from results.

**Response Fields:**

| Field                                   | Type    | Description                                            |
| --------------------------------------- | ------- | ------------------------------------------------------ |
| `ok`                                    | boolean | Indicates whether the request was successful           |
| `data`                                  | object  | Contains the search results                            |
| `data.purchaseOrders`                   | array   | List of matching purchase orders                       |
| `data.purchaseOrders[].poId`            | string  | Unique slug identifier for the purchase order          |
| `data.purchaseOrders[].poNumber`        | string  | Purchase order number                                  |
| `data.purchaseOrders[].state`           | string  | Current state of the PO                                |
| `data.purchaseOrders[].amount`          | number  | Total purchase order amount                            |
| `data.purchaseOrders[].currency`        | string  | Currency code (e.g., `INR`)                            |
| `data.purchaseOrders[].poDate`          | string  | Purchase order date (ISO 8601 format)                  |
| `data.purchaseOrders[].vendor`          | object  | Linked vendor information (`null` if no vendor linked) |
| `data.purchaseOrders[].vendor.vendorId` | string  | Unique slug identifier of the vendor                   |
| `data.purchaseOrders[].vendor.name`     | string  | Vendor display name                                    |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "purchaseOrders": [
      {
        "poId": "po_slug_identifier",
        "poNumber": "PO-2024-001",
        "state": "APPROVED",
        "amount": 12500.00,
        "currency": "INR",
        "poDate": "2024-01-15",
        "vendor": {
          "vendorId": "vendor_identifier",
          "name": "ABC Suppliers"
        }
      },
      {
        "poId": "po_slug_identifier_2",
        "poNumber": "PO-2024-002",
        "state": "DRAFTED",
        "amount": 8000.00,
        "currency": "INR",
        "poDate": "2024-01-20",
        "vendor": null
      }
    ]
  }
}
```

### Empty Results

If no purchase orders match the search criteria, an empty array is returned:

```json theme={null}
{
  "ok": true,
  "data": {
    "purchaseOrders": []
  }
}
```

## Error Responses

### Missing Search Parameters

**HTTP Status:** `400 Bad Request`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "At least one of poNumber or vendorId is required"
  }
}
```

### Authentication Errors

**HTTP Status:** `401 Unauthorized`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_CREDENTIALS",
    "message": "Missing Credentials"
  }
}
```

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid API Key"
  }
}
```

### Permission Errors

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Permission check failed - PERMISSION_CHECK_FAILED"
  }
}
```

### Internal Error

**HTTP Status:** `500 Internal Server Error`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal error"
  }
}
```

## Best Practices

* Provide at least one of `poNumber` or `vendorId` — the API returns a `400` if neither is supplied
* `poNumber` supports partial matching (e.g., searching `PO-2024` will match `PO-2024-001`, `PO-2024-002`, etc.)
* `vendorId` requires an exact match — use the vendor slug returned from the [Vendor Creation API](/apis/vendor-creation) or [Vendor Search API](/apis/vendor-search)
* Results are capped at 20 and sorted newest first — use more specific search terms to narrow results
* Archived POs are excluded from search results