# Endpoint: Create Quotation Request

This document details the `POST /api/customer/quotation-requests/create` endpoint and maps the customer mobile app's **Get Monthly Quotation** form design elements to their corresponding API parameters.

## Endpoint Details

* **URL**: `/api/customer/quotation-requests/create`
* **Method**: `POST`
* **Headers**:
  * `Content-Type: application/json`
  * `Authorization: Bearer <customer_token>`

---

## Design-to-API Payload Mapping

Below is a breakdown of how the UI form fields map to the API request payload:

| UI Section & Element | Form Field / Control | API Parameter | Parameter Type | Description / Seed Value mapping |
| :--- | :--- | :--- | :--- | :--- |
| **Header Section** | Vendor Profile Header | `vendor_id` | `integer` (Required) | The ID of the agency vendor (e.g. `1` for *Spotless Solutions*). |
| **SERVICE DETAILS** | Number of Maids | `number_of_helpers` | `integer` (Optional, default `1`) | The counter value indicating how many helpers are requested. |
| **PREFERENCES** | Preferred Nationalities | `preferred_nationality_id` | `integer` (Optional) | Maps Selected Tag:<br>• `Philippines` $\rightarrow$ `1`<br>• `Sri Lanka` $\rightarrow$ `3`<br>• `Ethiopia` $\rightarrow$ `4`<br>• `Nepal` $\rightarrow$ `5`<br>• `No Preference` $\rightarrow$ `null` |
| **PREFERENCES** | Specialized Skills | `specialty_ids` | `array of integers` (Optional) | Maps selected specialized skill tags to their corresponding specialty IDs:<br>• `Baby Sitting` $\rightarrow$ `1` (Baby Care)<br>• `Cooking` $\rightarrow$ `4`<br>• `Deep Cleaning` $\rightarrow$ `5` (Cleaning) |
| **ACCOMMODATION** | Live-in / Live-out selection | `service_model_id` | `integer` (Optional) | Maps selection:<br>• `Live-in (Provided by you)` $\rightarrow$ `1`<br>• `Live-out (Company transport)` $\rightarrow$ `2` |
| **ADDITIONAL DETAILS** | Text Area | `additional_notes` | `string` (Optional) | Any specific requirements, timings, or rules entered in the text box (Max 200 chars in UI). |
| **Internal Routing** | Request Type | `request_type` | `string` (Required) | Determines type of quote request. Set to `"general_vendor"` since this is a general agency quote request (not selecting a specific maid). |

---

## Example Request Payload

Based on the screenshot design (Spotless Solutions vendor, 1 maid, Preferred Nationality: Philippines, Specialized Skills: Cooking, Accommodation: Live-in):

```json
{
  "vendor_id": 1,
  "request_type": "general_vendor",
  "number_of_helpers": 1,
  "preferred_nationality_id": 1,
  "specialty_ids": [4],
  "service_model_id": 1,
  "additional_notes": "We need the helper to start early in the morning and have experience in cooking Filipino food."
}
```

---

## Response Formats

### 1. Success Response (`201 Created`)
```json
{
  "success": true,
  "message": "Quotation request submitted successfully",
  "data": {
    "id": 15,
    "customer_id": 1,
    "vendor_id": 1,
    "maid_id": null,
    "request_type": "general_vendor",
    "service_model_id": 1,
    "accommodation_type_id": null,
    "preferred_nationality_id": 1,
    "start_date": "2026-05-25",
    "duration_months": 12,
    "number_of_helpers": 1,
    "additional_notes": "We need the helper to start early in the morning and have experience in cooking Filipino food.",
    "status": "pending",
    "created_at": "2026-05-24 04:59:00",
    "updated_at": null,
    "vendor_name": "Spotless Solutions",
    "maid_name": null
  }
}
```

### 2. Validation Error (`422 Unprocessable Entity`)
```json
{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "vendor_id": "Selected vendor does not exist",
    "request_type": "The request_type field is required."
  }
}
```