> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routera.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Update deal
> PATCH /deals/{dealId} — update fields on an active object
## Endpoint
```http theme={null}
PATCH https://api.routera.io/deals/{id}
```
**Route:** `/deals/{dealId}`\
**Authentication:** Bearer JWT
**Path parameter:** `dealId` — object ID
## Query parameters
Comma-separated list of **additional** property names to include alongside the default set for this object type (e.g. `?properties=phone`). Names already in the default set are not duplicated. Invalid or disallowed property names return `400`.
## Request body
The body is a JSON object with a single `fields` property. Each key inside `fields` is a field **internal\_name** (the same names returned in GET responses, not nested under `fields` in the response).
Only include keys you want to change. Omitted fields keep their current values.
```json theme={null}
{
"fields": {
"deal_name": "Enterprise plan"
}
}
```
| Key | Description |
| -------------------- | -------------------------------------------------------------- |
| `fields` | Required. Map of `internal_name` → value for this object type. |
| `fields.external_id` | Optional. External identifier for sync with outside systems. |
Custom fields configured in your account use the same key names inside `fields`.
## Default response fields
**200** returns the updated object using the default property set:
| Property | Description |
| ------------- | ------------------------------------------------ |
| `id` | Internal object ID |
| `deal_name` | Custom or system field (flat on the object) |
| `pipeline` | Custom or system field (flat on the object) |
| `deal_stage` | Custom or system field (flat on the object) |
| `deal_owner` | Assigned owner email |
| `external_id` | External identifier (nullable) |
| `archived` | `false` when active; ISO timestamp when archived |
`created_at` and `updated_at` are always included in every response (ISO 8601 UTC), even when not listed above. When an object is **archived**, `archived_by` is also included automatically.
## Errors
| Status | When |
| ------ | --------------------------------------------------------------------------------------------------- |
| `400` | Missing `dealId`, invalid `properties`, invalid JSON, validation failure, or forbidden system field |
| `401` | Missing account context |
| `404` | Object not found |
| `409` | Object is archived — cannot update |
| `409` | Duplicate active record (unique key collision) |
```json theme={null}
{ "message": "Cannot update an archived object", "error": true }
```
## OpenAPI
````yaml PATCH /deals/{dealId}
openapi: 3.0.1
info:
title: Routera API
description: >-
Routera v2 REST API. Objects CRUD for contacts, companies, deals, and
tickets, routers read API, plus router dispatch.
version: 1.0.0
servers:
- url: https://api.routera.io
description: >-
API Gateway base URL (override with ROUTERA_API_BASE_URL when generating
docs)
security: []
tags:
- name: Authentication
description: Access token issuance
- name: Contacts
description: Contact records
- name: Companies
description: Company records
- name: Deals
description: Deal records
- name: Tickets
description: Ticket records
- name: Routers
description: Router configuration
- name: Dispatch
description: Router assignment
paths:
/deals/{dealId}:
patch:
tags:
- Deals
summary: Update deal
operationId: updateDeal
parameters:
- name: dealId
in: path
required: true
description: Object identifier
schema:
type: string
- name: properties
in: query
description: >-
Comma-separated additional property names to include alongside
defaults (e.g. phone). Invalid or disallowed names return 400.
schema:
type: string
requestBody:
$ref: '#/components/requestBodies/DealUpdateBody'
responses:
'200':
description: Updated
content:
application/json:
schema:
$ref: '#/components/schemas/Deal'
'400':
description: Bad request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'404':
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'409':
description: Conflict — archived object or duplicate key
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
security:
- bearerAuth: []
components:
requestBodies:
DealUpdateBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/DealWriteRequest'
example:
fields:
deal_name: Enterprise plan
schemas:
Deal:
type: object
properties:
id:
type: string
external_id:
type: string
nullable: true
deal_name:
type: string
nullable: true
pipeline:
type: string
nullable: true
deal_stage:
type: string
nullable: true
deal_owner:
type: string
nullable: true
description: Assigned owner email
example: jane@example.com
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
archived:
description: false when active, or ISO timestamp when archived
oneOf:
- type: boolean
- type: string
format: date-time
archived_by:
type: string
ApiError:
type: object
required:
- message
- error
properties:
message:
type: string
error:
type: boolean
enum:
- true
field:
type: string
description: Field that caused a conflict (409 duplicate responses)
DealWriteRequest:
type: object
required:
- fields
description: >-
Write payload for POST create and PATCH update. Keys inside `fields`
match field internal names returned in GET responses.
properties:
fields:
type: object
description: >-
Field values keyed by internal_name. Custom account fields use the
same key names.
properties:
external_id:
type: string
description: Optional external identifier for sync with outside systems
example: ext-001
x-default: ext-001
deal_name:
type: string
example: Enterprise plan
x-default: Enterprise plan
description: Value for `deal_name` (field internal_name)
pipeline:
type: string
example: default
x-default: default
description: Value for `pipeline` (field internal_name)
deal_stage:
type: string
example: qualified
x-default: qualified
description: Value for `deal_stage` (field internal_name)
additionalProperties: true
example:
fields:
external_id: ext-001
deal_name: Enterprise plan
pipeline: default
deal_stage: qualified
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Bearer JWT with valid account context.
````