> ## 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.

# Get deal by ID

> GET /deals/{dealId} — retrieve one object

## Endpoint

```http theme={null}
GET https://api.routera.io/deals/{id}
```

**Route:** `/deals/{dealId}`\
**Authentication:** Bearer JWT

**Path parameter:** `dealId` — object ID

## Query parameters

| Parameter    | Type   | Default            | Description                                                                                                                                                                                                                                         |
| ------------ | ------ | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `properties` | string | *(defaults below)* | 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`. |

## Default response fields

When `properties` is omitted:

| 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 |

<Note>
  `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.
</Note>

## Response example

**200**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "external_id": "ext-001",
  "created_at": "2026-05-01T10:00:00.000Z",
  "updated_at": "2026-05-28T12:00:00.000Z",
  "archived": false,
  "deal_name": "Enterprise plan",
  "pipeline": "default",
  "deal_stage": "qualified",
  "deal_owner": "jane@example.com"
}
```

## Errors

| Status | When                                             |
| ------ | ------------------------------------------------ |
| `400`  | Missing `dealId` in path or invalid `properties` |
| `401`  | Missing account context                          |
| `404`  | Object not found                                 |


## OpenAPI

````yaml GET /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}:
    get:
      tags:
        - Deals
      summary: Get deal by ID
      operationId: getDealById
      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
      responses:
        '200':
          description: Object
          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'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
      security:
        - bearerAuth: []
components:
  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)
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT with valid account context.

````