# Job warranties

A job warranty is a record of **no-charge warranty work** the customer reviews and approves, like a change order with no money attached: a numbered title, a description and the schedule impact in days. In TruTec it's the **Quick warranty approval request** on a job's Warranties page. Warranties never change the contract value, costing or invoices.

The customer approves or declines from a review link with a typed-name signature; the API reads their answer but never decides for them.

Writes are made as the person who created the API key and need operations turned on for the workspace (`403` `Operations not enabled` otherwise).

## The warranty object

| Field | Type | Description |
|---|---|---|
| `id` | integer | Warranty id. |
| `job_id`, `job` | integer, object | The job. |
| `number` | integer | Numbered per job: 1, 2, 3… |
| `title`, `description` | string | What the work is. |
| `days_delta` | integer | Schedule impact in whole days (+/-). |
| `status` | string | `draft`, `sent`, `approved`, `declined` or `void`. Approved, declined and void are final. |
| `source` | string | `office`, or `field` when a crew reported it from the crew app. |
| `customer_name`, `customer_email` | string or null | Who reviews it. |
| `review_url` | string or null | The customer's review link, once sent. |
| `sent_at`, `signed_at` | string or null | UTC timestamps. |
| `signature_name`, `decision_comment` | string or null | The customer's typed signature and comment. |
| `created_by` | object or null | `{id, name}`. |
| `created_at`, `updated_at` | string | UTC timestamps. |

## List warranties

`GET /v1/job-warranties`

**Permission:** Read jobs

Takes `job_id`, `status`, `updated_after`, `limit` and `offset`. Most recently changed first.

## Get a warranty

`GET /v1/job-warranties/{id}`

**Permission:** Read jobs

## Create a warranty

`POST /v1/job-warranties`

**Permission:** Write jobs

| Field | Type | Required | Description |
|---|---|---|---|
| `job_id` | integer | Yes | The job. |
| `title` | string | Yes | Up to 200 characters. |
| `description` | string | No | |
| `days_delta` | integer | No | Schedule impact in whole days. Default 0. |
| `customer_name`, `customer_email` | string | No | Who reviews it. |

```bash
curl -X POST "https://trutec.ai/api/v1/job-warranties" \
  -H "X-API-Key: sk_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "job_id": 70412, "title": "Repair settling at north entrance", "description": "Remove and replace the affected pavement.", "days_delta": 1, "customer_name": "Property Manager", "customer_email": "pm@example.com" }'
```

Returns `201` with the warranty as a draft. Nothing is sent.

## Update a warranty

`PATCH /v1/job-warranties/{id}`

**Permission:** Write jobs

Takes the fields above except `job_id`. Only the fields sent change. Approved, declined and void warranties are locked (`400`).

## Send it to the customer

`POST /v1/job-warranties/{id}/send`

**Permission:** Write jobs

!!! warning
    This emails your customer (`customer_email`) a link to review and approve or decline the warranty, from the connected mailbox of the person who created the API key.

Marks the warranty `sent` and returns it with `review_url` and `emailed`. When there is no customer email, or the email can't be sent, it is still marked sent and `emailed` is `false`: share `review_url` with the customer yourself. Sending again re-sends the same link.

## Void a warranty

`POST /v1/job-warranties/{id}/void`

**Permission:** Write jobs

Voids a draft or sent warranty. Its review link no longer takes a decision. Cannot be undone.