> ## Documentation Index
> Fetch the complete documentation index at: https://internal.mechzie.in/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Book for Someone Else

> Allow customers to book roadside assistance for another person (family, friends)

## Overview

Customers can book a job on behalf of another person — a family member, friend, or anyone who needs roadside help. The **beneficiary** is the person receiving the service, while the **booker** handles payment and job management.

## How It Works

When creating a job, pass optional `beneficiary_name`, `beneficiary_phone`, and `contact_preference` fields:

```bash theme={null}
POST /api/v1/jobs
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json
```

```json theme={null}
{
  "service_category_id": "uuid",
  "pickup_address": "123 MG Road, Bangalore",
  "pickup_lat": 12.9716,
  "pickup_lng": 77.5946,
  "description": "Flat tire on NH44, my mother is stranded",
  "beneficiary_name": "Lakshmi",
  "beneficiary_phone": "+919876543210",
  "contact_preference": "beneficiary"
}
```

## Fields

| Field                | Type                      | Default  | Description                                |
| -------------------- | ------------------------- | -------- | ------------------------------------------ |
| `beneficiary_name`   | string (optional)         | `null`   | Name of the person receiving the service   |
| `beneficiary_phone`  | string (optional)         | `null`   | Phone number in `+91XXXXXXXXXX` format     |
| `contact_preference` | `booker` \| `beneficiary` | `booker` | Who the mechanic should contact on arrival |

<Warning>
  When `contact_preference` is set to `beneficiary`, both `beneficiary_name` and `beneficiary_phone` are **required**. The server returns a 422 validation error if they are missing.
</Warning>

## Mechanic Experience

When a mechanic views the job details (via `GET /jobs/{id}`), the response includes:

```json theme={null}
{
  "data": {
    "id": "uuid",
    "customer": { "id": "uuid", "name": "Priya" },
    "beneficiary_name": "Lakshmi",
    "beneficiary_phone": "+919876543210",
    "contact_preference": "beneficiary",
    ...
  }
}
```

The mobile app should:

1. **Check `contact_preference`** — if `beneficiary`, show the beneficiary's name and phone as the primary contact
2. **Display a "Call" button** that dials `beneficiary_phone` instead of the booker's number
3. **Keep the booker accessible** — the booker is still the `customer` and handles payment/chat

## Contact Preference Logic

```mermaid theme={null}
flowchart TD
    A[Mechanic views job] --> B{contact_preference?}
    B -->|booker| C[Show customer name + phone]
    B -->|beneficiary| D[Show beneficiary name + phone]
    D --> E[Dial beneficiary on arrival]
    C --> F[Dial customer on arrival]
```

## Flutter Integration

```dart theme={null}
// Create job for someone else
final response = await http.post(
  Uri.parse('$baseUrl/api/v1/jobs'),
  headers: {
    'Authorization': 'Bearer $accessToken',
    'Content-Type': 'application/json',
  },
  body: jsonEncode({
    'service_category_id': categoryId,
    'pickup_address': address,
    'pickup_lat': lat,
    'pickup_lng': lng,
    'beneficiary_name': 'Mom',
    'beneficiary_phone': '+919876543210',
    'contact_preference': 'beneficiary',
  }),
);

// Mechanic-side: determine who to contact
final job = jobDetailResponse['data'];
final contactName = job['contact_preference'] == 'beneficiary'
    ? job['beneficiary_name']
    : job['customer']['name'];
final contactPhone = job['contact_preference'] == 'beneficiary'
    ? job['beneficiary_phone']
    : null; // Use customer phone from user profile
```

<Note>
  The booker always remains the `customer` in the job. Payment, chat messages, and job management are tied to the booker's account. Only the contact information shown to the mechanic changes based on `contact_preference`.
</Note>