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

> Create vendor invitations to onboard new vendors to your organization

## 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  | Yes      | 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 |
| `sendEmail` | boolean | No       | Whether to send an email invitation to the vendor. Defaults to `false` if not provided                  |

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://api.pazy.io/v1.0/vendor/invite \
    -H "Authorization: Api-Key YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "ABC Suppliers",
      "email": "contact@abcsuppliers.com",
      "phone": "+919876543210",
      "locality": "DOMESTIC",
      "sendEmail": true
    }'
  ```

  ```javascript JavaScript (Fetch API) theme={null}
  const response = await fetch('https://api.pazy.io/v1.0/vendor/invite', {
    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',
      sendEmail: true
    })
  });

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

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

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

  payload = {
      "name": "ABC Suppliers",
      "email": "contact@abcsuppliers.com",
      "phone": "+919876543210",
      "locality": "DOMESTIC",
      "sendEmail": True
  }

  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 vendor invite creation response data                                                                                                  |
| `data.inviteLink` | string  | Unique invitation link that can be shared with the vendor to complete their onboarding. The vendor can use this link to access the invitation form |

### Response Example

```json theme={null}
{
  "ok": true,
  "data": {
    "inviteLink": "https://app.pazy.io/p/vendor-invite/abc123xyz"
  }
}
```

<Info>
  If `sendEmail` is set to `true`, the invitation email will be sent automatically to the vendor's email address. Otherwise, you can share the `inviteLink` manually.
</Info>

## Error Responses

### Missing Required Fields

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Name and email are 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"
  }
}
```

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

***

### Invalid Phone Number

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

```json theme={null}
{
  "ok": false,
  "error": {
    "code": "INVALID_PHONE",
    "message": "Invalid phone number"
  }
}
```

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

* Use `sendEmail: true` if you want automatic email delivery
* If `sendEmail: false`, share the `inviteLink` manually with the vendor
* Ensure vendor contact information (email, phone) is accurate to avoid duplicate errors
* Check for duplicate errors before attempting to create a vendor invite