# List & Get Suppliers

Retrieve your supplier information to view contact details, addresses, and other vendor information. Use the list endpoint to see all suppliers, or get a specific supplier by ID for detailed information.

## List Suppliers

Use the GET method with `/v2/suppliers` to retrieve a paginated list of all your suppliers.

### Query Parameters

| Query Parameter | Type | Description |
|  --- | --- | --- |
| `supplier_name` | *string* | Filter by supplier name (partial match, case-insensitive) |
| `page_size` | *integer* | Number of results per page (default: 50, minimum: 1, maximum: 500) |


### Response Properties

The response includes a `suppliers` array with the following properties for each supplier:

| Property | Type | Description |
|  --- | --- | --- |
| `supplier_id` | *string* | Unique identifier for the supplier |
| `supplier_name` | *string* | Name of the supplier company |
| `supplier_email` | *string* (email) | Email address for purchase order notifications |
| `address_line_1` | *string* | First line of supplier's address |
| `address_line_2` | *string* | Second line of supplier's address (suite, unit, etc.) |
| `city` | *string* | City |
| `state` | *string* | State or province |
| `postal_code` | *string* | Postal or ZIP code |
| `country_code` | *string* | ISO 3166-1 alpha-2 country code (e.g., "US", "CA", "GB") |
| `contact_name` | *string* | Name of the primary contact person |
| `contact_phone` | *string* | Phone number for the contact person |


The response also includes pagination metadata: `total` and `links`. The cursor for the next page is embedded in the `links.next.href` URL.

### Example Request & Response

**GET /v2/suppliers**

## Get Supplier Details

Use the GET method with `/v2/suppliers/{supplier_id}` to retrieve detailed information about a specific supplier.

### Path Parameters

| Parameter | Type | Description |
|  --- | --- | --- |
| `supplier_id` | *string* | The unique identifier of the supplier |


### Response

Returns a single supplier object with all the properties listed in the table above.

### Example Request & Response

**GET /v2/suppliers/{supplier_id}**

## Filtering and Search

### Search by Supplier Name

Use the `supplier_name` query parameter to filter suppliers by name. The search performs a partial, case-insensitive match:


```http
GET /v2/suppliers?supplier_name=Acme
```

This returns all suppliers whose name contains "Acme" (e.g., "Acme Widgets Inc", "Acme Supply Co", "Best Acme Parts").

### Search Examples

**Find suppliers with "Widget" in the name:**


```http
GET /v2/suppliers?supplier_name=Widget
```

**Find suppliers and paginate results:**


```http
GET /v2/suppliers?supplier_name=Supply&page_size=25
```

**Get next page using cursor from response links:**


```http
GET /v2/suppliers?cursor=eyJQYWdlIjoyLCJQYWdlU2l6ZSI6MjUsIlN1cHBsaWVyTmFtZSI6IlN1cHBseSJ9&page_size=25
```

**List all suppliers (no filter):**


```http
GET /v2/suppliers?page_size=100
```

### Pagination Tips

- **First page**: Make request without `cursor` parameter
- **Next page**: Use the `cursor` value from `links.next.href` in the response
- **Page size**: Control number of results with `page_size` (default: 50, max: 500)
- **End of results**: When `links.next` is null, you've reached the last page


### Filter Tips

- **Partial matching**: The search matches any part of the supplier name
- **Case-insensitive**: "acme", "ACME", and "Acme" all return the same results
- **Exact matches**: For exact matching, filter results in your application code after retrieval


## Related Resources

- [Create Suppliers](/suppliers/create) - Add new supplier information
- [Update Suppliers](/suppliers/update) - Modify existing supplier information
- [Create Purchase Orders](/purchase-orders/create) - Use supplier_id to create orders
- [List Purchase Orders](/purchase-orders/list) - Find orders by supplier