# Contact Us Form API Integration Guide

## Endpoint
**POST** `/api/v1/contact-us`

**Base URL**: `http://your-api-domain/api/v1`

**Full URL**: `http://your-api-domain/api/v1/contact-us`

---

## Request Payload

### Required Fields
- `first_name` (string, max 255) - User's first/given name
- `email` (string, valid email, max 255) - Valid email address
- `mobile` (string, max 20) - Phone number (can include country code)

### Optional Fields
- `last_name` (string, max 255) - User's family/last name
- `method_of_contact` (string, max 255) - How the user found you (dropdown value)
- `message` (string) - Additional message or remarks

### Example Request
```json
{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "mobile": "+971501234567",
  "method_of_contact": "Google",
  "message": "I am interested in properties in Dubai."
}
```

### JavaScript/Axios Example
```javascript
import axios from 'axios';

const submitContactForm = async (formData) => {
  try {
    const response = await axios.post(
      'http://your-api-domain/api/v1/contact-us',
      {
        first_name: formData.firstName,
        last_name: formData.lastName,
        email: formData.email,
        mobile: formData.phoneNumber,
        method_of_contact: formData.howDidYouFindUs,
        message: formData.additionalMessage
      }
    );
    return response.data;
  } catch (error) {
    throw error.response.data;
  }
};
```

---

## Response Formats

### Success Response (HTTP 201)
```json
{
  "success": true,
  "status_code": 201,
  "message": "Your message has been received. We will get back to you soon.",
  "data": {
    "id": 123
  }
}
```

**Handle Success**:
- Display success message: "Your message has been received. We will get back to you soon."
- Clear the form
- Optionally store the contact ID for reference
- Show confirmation screen or navigate to thank you page

---

### Validation Error Response (HTTP 422)
```json
{
  "success": false,
  "message": "Validation failed",
  "status_code": 422,
  "errors": {
    "first_name": [
      "Name is required"
    ],
    "email": [
      "Email address is required",
      "Please provide a valid email address"
    ],
    "mobile": [
      "Phone number is required"
    ]
  },
  "error_code": "VALIDATION_FAILED"
}
```

**Error Messages by Field**:
- `first_name.required` → "Name is required"
- `email.required` → "Email address is required"
- `email.email` → "Please provide a valid email address"
- `mobile.required` → "Phone number is required"

**Handle Validation Errors**:
- Display field-specific error messages near the input fields
- Highlight invalid fields in red
- Focus on the first error field
- Allow user to correct and resubmit

---

### Server Error Response (HTTP 500)
```json
{
  "success": false,
  "message": "Failed to submit contact form: <error details>",
  "status_code": 500
}
```

**Handle Server Error**:
- Display generic error message: "An error occurred while submitting the form. Please try again later."
- Log the error for debugging
- Optionally show a retry button
- Do NOT expose the error details to the user in production

---

## Implementation Checklist

### Form Fields
- [ ] Name (text input, required)
- [ ] Email (email input, required)
- [ ] Phone Number (tel input, required)
- [ ] How Did You Find Us? (dropdown, optional)
- [ ] Message (textarea, optional)
- [ ] Submit button
- [ ] Form validation on client-side

### Submit Handling
- [ ] Send request to POST `/api/v1/contact-us`
- [ ] Show loading/spinner while submitting
- [ ] Disable submit button during submission
- [ ] Handle success response (201)
- [ ] Handle validation errors (422)
- [ ] Handle server errors (500)

### User Feedback
- [ ] Show success message after submission
- [ ] Clear form on successful submission
- [ ] Display validation errors for each field
- [ ] Show appropriate error messages
- [ ] Provide clear feedback for network/server errors

### Data Validation (Client-Side)
- [ ] First name: required, non-empty
- [ ] Email: required, valid email format
- [ ] Phone: required, basic format validation
- [ ] Message: optional, no restrictions

---

## Testing

### Test Cases
1. **Submit with all fields**
   - Expected: 201 success
   - Data saved to database

2. **Submit with only required fields**
   - Payload: first_name, email, mobile
   - Expected: 201 success

3. **Missing first_name**
   - Expected: 422 validation error
   - Error: "Name is required"

4. **Invalid email format**
   - Payload: email = "invalid-email"
   - Expected: 422 validation error
   - Error: "Please provide a valid email address"

5. **Missing mobile**
   - Expected: 422 validation error
   - Error: "Phone number is required"

6. **Valid email with different formats**
   - Test: user@example.com, user+tag@example.co.uk, user_123@test-domain.com
   - Expected: All should pass validation

---

## Additional Information

### GET Contact Us Page Data
To fetch the Contact Us page information (title, description, contact details, social media, branches):

**Endpoint**: GET `/api/v1/contact-us-page`

**Response Example**:
```json
{
  "success": true,
  "status_code": 200,
  "data": {
    "title": "Contact Us",
    "description": "Get in touch with us...",
    "phone": "+971 1 234 5678",
    "email": "contact@mmzr.com",
    "whatsapp": "+971501234567",
    "social_media": [
      {
        "icon": "https://...",
        "link": "https://facebook.com/..."
      }
    ],
    "our_branches": [
      {
        "title": "Dubai",
        "branch_image": "https://...",
        "mobile": "+971...",
        "email": "dubai@mmzr.com",
        "location": "Dubai, UAE"
      }
    ],
    "seo": {
      "meta_title": "Contact MMZR",
      "meta_description": "..."
    }
  }
}
```

---

## Error Handling Example (Vue.js)
```javascript
export default {
  data() {
    return {
      form: {
        firstName: '',
        lastName: '',
        email: '',
        phoneNumber: '',
        howDidYouFindUs: '',
        additionalMessage: ''
      },
      errors: {},
      loading: false,
      success: false
    }
  },
  methods: {
    async submitForm() {
      this.loading = true;
      this.errors = {};
      this.success = false;
      
      try {
        const response = await axios.post('/api/v1/contact-us', {
          first_name: this.form.firstName,
          last_name: this.form.lastName,
          email: this.form.email,
          mobile: this.form.phoneNumber,
          method_of_contact: this.form.howDidYouFindUs,
          message: this.form.additionalMessage
        });
        
        this.success = true;
        this.resetForm();
        // Show success message or redirect
      } catch (error) {
        if (error.response?.status === 422) {
          // Validation errors
          this.errors = error.response.data.errors;
        } else {
          // Server error
          this.errors = { submit: ['Failed to submit form. Please try again.'] };
        }
      } finally {
        this.loading = false;
      }
    },
    resetForm() {
      this.form = {
        firstName: '',
        lastName: '',
        email: '',
        phoneNumber: '',
        howDidYouFindUs: '',
        additionalMessage: ''
      };
    }
  }
}
```

---

## Database Notes

Submitted forms are stored in the `contacts` table with:
- `contact_type` = 'Website Contact Form' (hardcoded)
- `created_at` and `updated_at` timestamps
- All form data preserved for reference/follow-up