> ## 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.

# Vendor Search API

> Search vendors by GSTIN, PAN, or name. 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 `gstin`, `pan`, or `name` must be provided.

| Parameter | Type   | Required | Description                                                  |
| --------- | ------ | -------- | ------------------------------------------------------------ |
| `gstin`   | string | No       | Exact GSTIN (15 characters) to search for                    |
| `pan`     | string | No       | Exact PAN (10 characters) to search for                      |
| `name`    | string | No       | Partial or full vendor name to search for (case-insensitive) |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  # Search by GSTIN
  curl -X GET "https://api.pazy.io/v1.0/vendor/search?gstin=29ABCDE1234F1Z5" \
    -H "Authorization: Api-Key YOUR_API_KEY"

  # Search by PAN
  curl -X GET "https://api.pazy.io/v1.0/vendor/search?pan=ABCDE1234F" \
    -H "Authorization: Api-Key YOUR_API_KEY"

  # Search by name
  curl -X GET "https://api.pazy.io/v1.0/vendor/search?name=ABC+Suppliers" \
    -H "Authorization: Api-Key YOUR_API_KEY"
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  // Search by GSTIN
  const params = new URLSearchParams({ gstin: '29ABCDE1234F1Z5' });
  const response = await fetch(`https://api.pazy.io/v1.0/vendor/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/vendor/search"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY"
  }

  # Search by GSTIN
  params = { "gstin": "29ABCDE1234F1Z5" }

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

## Success Response

**HTTP Status:** `200 OK`

Returns up to 20 vendors matching the search criteria.

**Response Fields:**

| Field                     | Type    | Description                                                               |
| ------------------------- | ------- | ------------------------------------------------------------------------- |
| `ok`                      | boolean | Indicates whether the request was successful                              |
| `data`                    | object  | Contains the search results                                               |
| `data.vendors`            | array   | List of matching vendors                                                  |
| `data.vendors[].vendorId` | string  | Unique slug identifier for the vendor (use this as `vendorId` in PO APIs) |
| `data.vendors[].name`     | string  | Vendor display name                                                       |
| `data.vendors[].gstin`    | string  | Vendor GSTIN (`null` if not set)                                          |
| `data.vendors[].pan`      | string  | Vendor PAN (`null` if not set)                                            |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "vendors": [
      {
        "vendorId": "vendor_identifier",
        "name": "ABC Suppliers",
        "gstin": "29ABCDE1234F1Z5",
        "pan": "ABCDE1234F"
      }
    ]
  }
}
```

### Empty Results

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

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

## Error Responses

### Missing Search Parameters

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

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

### Invalid GSTIN Format

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /query/gstin: must NOT have more than 15 characters"
  }
}
```

### Invalid PAN Format

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /query/pan: must NOT have more than 10 characters"
  }
}
```

### 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 `gstin`, `pan`, or `name` — the API returns a `400` if none are supplied
* `gstin` and `pan` require exact matches (15 and 10 characters respectively)
* `name` supports partial matching — searching `ABC` will match `ABC Suppliers`, `ABC Trading Co.`, etc.
* The `vendorId` in the response is the slug to use when creating or updating purchase orders via the [PO Creation API](/apis/po-creation) or [PO Update API](/apis/po-update)
* Results are capped at 20 — use more specific search terms if needed