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

> Create new vendors in your organization with comprehensive details

## Authentication

All requests require an API key in the request headers.

**Headers:**

```
Authorization: Api-Key YOUR_API_KEY
Content-Type: application/json
```

## Request

**Content-Type:** `application/json`

### Body Parameters

| Parameter      | Type   | Required | Description                                                                                             |
| -------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `name`         | string | Yes      | Vendor name (1-255 characters)                                                                          |
| `email`        | string | No       | Vendor email address (must be valid email format)                                                       |
| `phone`        | string | No       | Vendor phone number (must include country code, e.g., +919876543210)                                    |
| `locality`     | string | No       | Vendor locality type. Valid values: `DOMESTIC`, `INTERNATIONAL`. Defaults to `DOMESTIC` if not provided |
| `paymentTerms` | string | No       | Payment terms for the vendor. See accepted values below                                                 |
| `gstNumber`    | string | No       | GST number for the vendor                                                                               |
| `panNumber`    | string | No       | PAN number for the vendor                                                                               |
| `address`      | object | No       | Vendor address details (see Address Object below)                                                       |

### Address Object

If you provide a valid and verified `gstNumber`, the address will be automatically extracted from GST data.
However, if you also provide an `address` object, the user-provided address will always take **precedence** over the GST-derived one.

When providing an `address`, the following fields are available:

| Parameter      | Type   | Required | Description                                    |
| -------------- | ------ | -------- | ---------------------------------------------- |
| `addressLine1` | string | Yes      | Primary address line                           |
| `addressLine2` | string | No       | Secondary address line                         |
| `city`         | string | No       | City name                                      |
| `state`        | string | Yes      | State Name (below is the list of valid values) |
| `zipCode`      | string | Yes      | ZIP or postal code                             |
| `country`      | string | No       | Country name                                   |

\*Required only if `address` object is provided

#### State Values

The `state` field should use **uppercase underscore-separated codes** (e.g., `UTTAR_PRADESH`, `MAHARASHTRA`, etc.).

Below is the complete list of supported **State** and **Union Territory** values:

| State / UT Name                          | Value                                      |
| ---------------------------------------- | ------------------------------------------ |
| Andhra Pradesh                           | `ANDHRA_PRADESH`                           |
| Arunachal Pradesh                        | `ARUNACHAL_PRADESH`                        |
| Assam                                    | `ASSAM`                                    |
| Bihar                                    | `BIHAR`                                    |
| Chhattisgarh                             | `CHHATTISGARTH`                            |
| Goa                                      | `GOA`                                      |
| Gujarat                                  | `GUJARAT`                                  |
| Haryana                                  | `HARYANA`                                  |
| Himachal Pradesh                         | `HIMACHAL_PRADESH`                         |
| Jharkhand                                | `JHARKHAND`                                |
| Karnataka                                | `KARNATAKA`                                |
| Kerala                                   | `KERALA`                                   |
| Madhya Pradesh                           | `MADHYA_PRADESH`                           |
| Maharashtra                              | `MAHARASHTRA`                              |
| Manipur                                  | `MANIPUR`                                  |
| Meghalaya                                | `MEGHALAYA`                                |
| Mizoram                                  | `MIZORAM`                                  |
| Nagaland                                 | `NAGALAND`                                 |
| Odisha                                   | `ODISHA`                                   |
| Punjab                                   | `PUNJAB`                                   |
| Rajasthan                                | `RAJASTHAN`                                |
| Sikkim                                   | `SIKKIM`                                   |
| Tamil Nadu                               | `TAMIL_NADU`                               |
| Telangana                                | `TELANGANA`                                |
| Tripura                                  | `TRIPURA`                                  |
| Uttar Pradesh                            | `UTTAR_PRADESH`                            |
| Uttarakhand                              | `UTTARAKHAND`                              |
| West Bengal                              | `WEST_BENGAL`                              |
| Andaman and Nicobar Islands              | `ANDAMAN_AND_NICOBAR_ISLANDS`              |
| Chandigarh                               | `CHANDIGARH`                               |
| Dadra and Nagar Haveli and Daman and Diu | `DADRA_AND_NAGAR_HAVELI_AND_DAMAN_AND_DIU` |
| Lakshadweep                              | `LAKSHADWEEP`                              |
| Delhi                                    | `DELHI`                                    |
| Puducherry                               | `PUDUCHERRY`                               |
| Jammu and Kashmir                        | `JAMMU_AND_KASHMIR`                        |
| Ladakh                                   | `LADAKH`                                   |

### Payment Terms Values

Payment terms defaults to organization's default if not provided.

The `paymentTerms` field accepts the following values:

* `due_eom`
* `due_on_receipt`
* `net_7`
* `net_15`
* `net_30`
* `net_45`
* `net_60`
* `net_90`
* `net_120`
* `net_150`
* `net_180`
* `none`

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pazy.io/v1.0/vendor \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "ABC Suppliers",
      "email": "contact@abcsuppliers.com",
      "phone": "+919876543210",
      "locality": "DOMESTIC",
      "paymentTerms": "net_30",
      "gstNumber": "29ABCDE1234F1Z5",
      "panNumber": "ABCDE1234F",
      "address": {
        "addressLine1": "123 Business Park",
        "addressLine2": "Near Tech Hub",
        "city": "Mumbai",
        "state": "MAHARASHTRA",
        "zipCode": "400001",
        "country": "India"
      }
    }'
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/vendor', {
    method: 'POST',
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      name: 'ABC Suppliers',
      email: 'contact@abcsuppliers.com',
      phone: '+919876543210',
      locality: 'DOMESTIC',
      paymentTerms: 'net_30',
      gstNumber: '29ABCDE1234F1Z5',
      panNumber: 'ABCDE1234F',
      address: {
        addressLine1: '123 Business Park',
        addressLine2: 'Near Tech Hub',
        city: 'Mumbai',
        state: 'MAHARASHTRA',
        zipCode: "400001",
        country: 'India'
      }
    })
  });

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

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

  url = "https://api.pazy.io/v1.0/vendor"
  headers = {
      "Authorization": "Api-Key YOUR_API_KEY",
      "Content-Type": "application/json"
  }

  payload = {
      "name": "ABC Suppliers",
      "email": "contact@abcsuppliers.com",
      "phone": "+919876543210",
      "locality": "DOMESTIC",
      "paymentTerms": "net_30",
      "gstNumber": "29ABCDE1234F1Z5",
      "panNumber": "ABCDE1234F",
      "address": {
          "addressLine1": "123 Business Park",
          "addressLine2": "Near Tech Hub",
          "city": "Mumbai",
          "state": "MAHARASHTRA",
          "zipCode": "400001",
          "country": "India"
      }
  }

  response = requests.post(url, headers=headers, json=payload)
  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 created vendor details          |
| `data.vendorId`    | string  | Unique vendor ID                             |
| `data.vendorState` | string  | Created Vendor State                         |

### VendorStatus Values

* **ACTIVE**: The vendor is created and is in active state
* **APPROVAL\_PENDING**: The vendor is yet to be approved by the organization's vendor admins

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "vendorId": "<vendorId>",
    "vendorState": "ACTIVE"
  }
}
```

## Error Responses

### Missing Required Fields

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Name is required"
  }
}
```

### Invalid Email Format

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed: /body/email: must match format \"email\""
  }
}
```

### Invalid Locality

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_LOCALITY",
    "message": "Invalid locality. Must be DOMESTIC or INTERNATIONAL"
  }
}
```

### Invalid Payment Terms

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid payment terms value"
  }
}
```

### Address Validation Errors

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Address validation failed: addressLine1, state, and zipCode are required when address is provided"
  }
}
```

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

```json theme={null}
{
    "ok": false,
    "error": {
        "code": "INVALID_ADDRESS",
        "message": "Invalid zipCode format"
    }
}
```

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

```json theme={null}
{
    "ok": false,
    "error": {
        "code": "INVALID_ADDRESS",
        "message": "Invalid state value"
    }
}
```

### Duplicate Vendor Errors

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

**Duplicate Phone Number:**

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "DUPLICATE_PHONE_NUMBER",
    "message": "Vendor with same phone number already exists"
  }
}
```

**Duplicate Email:**

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "DUPLICATE_EMAIL",
    "message": "Vendor with same email already exists"
  }
}
```

**Duplicate Vendor Name:**

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "DUPLICATE_VENDOR_NAME",
    "message": "Vendor with same name already exists"
  }
}
```

### 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"
  }
}
```

### Vendor Creation Errors

**HTTP Status:** `400 Bad Request` or `500 Internal Server Error`

```json theme={null}
{
  "ok": false,
  "error" : {
    "code": "VENDOR_CREATION_FAILED",
    "message": "Error creating vendor"
  }
}
```

```json theme={null}
{
  "ok": false,
   "error" : {
    "code": "USER_CREATION_FAILED",
    "message": "Failed to create vendor user"
  }
}
```

## Best Practices

### Vendor Creation

* Only `name` is required; all other fields are optional
* Provide complete address information if you include the `address` object (addressLine1, state, and zipCode are mandatory within the address)
* Use appropriate `locality` values (DOMESTIC for vendors within your country, INTERNATIONAL for foreign vendors)
* Include GST and PAN numbers for Indian domestic vendors for tax compliance
* Ensure vendor contact information (email, phone) is unique to avoid duplicate errors
* Validate payment terms against your organization's configured options