> ## 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 List API

> Retrieve a paginated list of vendors with filters by name, GST number, PAN, and owner

## Authentication

All requests require an API key in the request headers.

**Headers:**

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

## Request

### Query Parameters

| Parameter   | Type    | Required | Description                                                                          |
| ----------- | ------- | -------- | ------------------------------------------------------------------------------------ |
| `name`      | string  | No       | Filter by vendor name (partial match).                                               |
| `gstNumber` | string  | No       | Filter by GST number. Must be a valid 15-character GSTIN.                            |
| `panNumber` | string  | No       | Filter by PAN number. Must be a valid 10-character PAN.                              |
| `userId`    | string  | No       | Filter by the id of the vendor's owner user.                                         |
| `limit`     | integer | No       | Number of records to return. Min 1, Max 100.                                         |
| `cursor`    | string  | No       | Cursor for pagination. Use the `nextCursor` value returned by the previous response. |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.pazy.io/v1.0/vendors?limit=30&name=ABC" \
    -H "Authorization: Api-Key YOUR_API_KEY"
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const params = new URLSearchParams({ limit: '30', name: 'ABC' });
  const response = await fetch(`https://api.pazy.io/v1.0/vendors?${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/vendors"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY"
  }
  params = { "limit": 30, "name": "ABC" }

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

## Success Response

**HTTP Status:** `200 OK`

**Response Fields:**

| Field                              | Type             | Description                                                                 |
| ---------------------------------- | ---------------- | --------------------------------------------------------------------------- |
| `ok`                               | boolean          | Indicates whether the request was successful                                |
| `data`                             | object           | Contains the vendor list response data                                      |
| `data.vendors`                     | array            | List of vendors                                                             |
| `data.vendors[].id`                | string           | Unique identifier (slug) for the vendor                                     |
| `data.vendors[].name`              | string           | Vendor display name (falls back to legal name)                              |
| `data.vendors[].GSTIN`             | string           | Vendor GSTIN. Empty string if not set                                       |
| `data.vendors[].PAN`               | string           | Vendor PAN. Empty string if not set                                         |
| `data.vendors[].dateCreated`       | string           | Date the vendor was created (ISO 8601 format)                               |
| `data.vendors[].email`             | string           | Vendor email address. Empty string if not set                               |
| `data.vendors[].ownerId`           | string           | Unique slug identifier of the vendor owner                                  |
| `data.vendors[].ownerName`         | string           | Full name of the vendor owner                                               |
| `data.vendors[].totalPaidAmount`   | number or string | Total amount paid to the vendor                                             |
| `data.vendors[].outstandingAmount` | number or string | Total outstanding amount for the vendor                                     |
| `data.vendors[].overdueAmount`     | number or string | Total overdue amount for the vendor                                         |
| `data.vendors[].advanceAmount`     | number or string | Total advance amount available for the vendor                               |
| `data.vendors[].currency`          | string           | Currency code for the vendor amount summaries                               |
| `data.vendors[].accountingSynced`  | boolean          | Indicates whether the vendor is synced to the connected accounting platform |
| `data.vendors[].accountingSyncId`  | string           | Identifier of the vendor in the connected accounting platform               |
| `data.vendors[].selfUrl`           | string           | Shareable URL for viewing the vendor in the web interface                   |
| `data.context`                     | object           | Pagination metadata                                                         |
| `data.context.count`               | number           | Total number of vendors matching the filters                                |
| `data.context.hasMore`             | boolean          | Indicates whether there are more vendors to fetch                           |
| `data.context.nextCursor`          | string or null   | Cursor to fetch the next page. `null` when there are no more results        |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "vendors": [
      {
        "id": "vendor_identifier",
        "name": "ABC Suppliers",
        "GSTIN": "29ABCDE1234F1Z5",
        "PAN": "ABCDE1234F",
        "dateCreated": "2026-03-28T08:12:25.088Z",
        "email": "contact@abcsuppliers.com",
        "ownerId": "user_identifier",
        "ownerName": "John Doe",
        "totalPaidAmount": 25000,
        "outstandingAmount": 15000,
        "overdueAmount": 5000,
        "advanceAmount": 10000,
        "currency": "INR",
        "accountingSynced": true,
        "accountingSyncId": "LEDGER-ABC-SUPPLIERS",
        "selfUrl": "https://app.pazy.io/p/vendor/update/vendor_identifier"
      }
    ],
    "context": {
      "count": 120,
      "hasMore": true,
      "nextCursor": "30"
    }
  }
}
```

## Error Responses

### Invalid GST Number

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_GST_NUMBER",
    "message": "Invalid GST number format"
  }
}
```

### Invalid PAN Number

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_PAN_NUMBER",
    "message": "Invalid PAN number format"
  }
}
```

### Validation Error

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

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

### Access Denied

**HTTP Status:** `403 Forbidden`

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Access denied: You can only view vendors you own"
  }
}
```

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

* Use `cursor` and `limit` together to paginate; pass the `nextCursor` from the response as the `cursor` value for the next call
* Combine `name`, `gstNumber`, `panNumber`, and `userId` filters to narrow results
* Use the `id` from the response as the input to the [Vendor Details API](/apis/vendor-details) for full vendor information
* The API returns at most 100 vendors per call regardless of the `limit` value
* Access is limited to users with vendor read permission and an admin or bookkeeper role