# `maintenance_request_create`

**Create maintenance request.** Submits a maintenance request, the same way the person would in PorchQ.

**Who can use it:** Everyone in the community.

| Scope | Effect | Hints |
|---|---|---|
| `maintenance:write` | write | changes data |

## Description shown to assistants

> Use this when the user asks to submit a new maintenance request.

## Arguments

| Argument | Type | Required | About |
|---|---|---|---|
| `property_id` | string | No | The community's public id (`prop_web…`). Pass it on every call. |
| `title` | string | Yes | A short title for the request. |
| `description` | string | No | What is wrong, in the person's words. |
| `priority` | string | No | `urgent`, `high`, `medium` or `low`. |
| `idempotency_key` | string | No | Optional. A unique value for this change; sending the same value again does nothing twice. At most 200 characters. |

## What it returns

Every result has `content` (one short sentence for the person) and `structuredContent` (the data below). A tool that could not run answers with `isError: true` and a sentence saying why; see [Errors and limits](/developers/mcp/errors-and-limits).

- `property`: the community.
- `maintenance_request`: the new request, with the same fields as in `maintenance_requests_list`.

`structuredContent` follows this JSON Schema, also in `tools/list` as `outputSchema`:

```json
{
  "type": "object",
  "properties": {
    "property": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "name": { "type": "string" },
        "addressLine1": { "type": ["string", "null"] },
        "addressLine2": { "type": ["string", "null"] },
        "city": { "type": ["string", "null"] },
        "state": { "type": ["string", "null"] },
        "postalCode": { "type": ["string", "null"] },
        "timezone": { "type": ["string", "null"] },
        "billingFrequency": { "type": ["string", "null"] },
        "demoClone": { "type": "boolean" },
        "demoPersona": { "type": ["string", "null"] },
        "demoExpiresAt": { "type": ["string", "null"] }
      },
      "required": ["id", "name"]
    },
    "maintenance_request": {
      "type": "object",
      "properties": {
        "id": { "type": "string" },
        "title": { "type": "string" },
        "status": { "type": "string" },
        "priority": { "type": "string" },
        "submittedAt": { "type": ["string", "null"] },
        "updatedAt": { "type": ["string", "null"] },
        "requester": { "type": ["string", "null"] },
        "assignedTo": { "type": ["string", "null"] },
        "summary": { "type": ["string", "null"] },
        "tags": { "type": "array", "items": { "type": "string" } },
        "category": { "type": ["string", "null"] },
        "residentNotes": { "type": ["string", "null"] },
        "slaDueAt": { "type": ["string", "null"] },
        "submittedByResident": { "type": "boolean" },
        "vendorId": { "type": ["string", "null"] },
        "vendorName": { "type": ["string", "null"] }
      },
      "required": ["id", "title", "status", "priority"]
    }
  },
  "required": ["property", "maintenance_request"]
}
```

## Notes

- A resident's request is submitted in their name, exactly as from the resident portal: the community's staff are notified by email, text and push, and the resident's message thread about it opens.
- A request an owner or manager logs follows the staff form: `description` becomes the summary and the person is the requester.
- `priority` is `urgent`, `high`, `medium` or `low`; anything else is saved as `medium`.
- The request records that it came through MCP and the name of the app.

## Example

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "maintenance_request_create",
    "arguments": {
      "property_id": "prop_web4k2m9q7x1v8c3n5b6z0a2s4d",
      "title": "Hallway light out on the 3rd floor",
      "description": "The light by unit 312 has been out since Monday.",
      "priority": "medium",
      "idempotency_key": "6f1c2a9e-0d3b-4c1e-9a77-2b5d8e4f1a03"
    }
  }
}
```