---
title: "Create a line item"
method: POST
path: "/v1/line_items"
tags: ["Line items"]
---

# Create a line item

`POST /v1/line_items`

## Request

- Base URL: `https://api.navigateai.co`
- URL: `https://api.navigateai.co/v1/line_items`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/navigate/apis/navigateai-api/docs/v1/line_items/post.ts> (a function with typed inputs; its response is checked against the schema)

## Request body

- CreateLineItemRequest
  - `scope_id` string, required
  - `title` string, required
  - `description` string, nullable
  - `price_reference_key` string, nullable
  - `notes` string, nullable
  - `custom_fields` object, nullable
  - `status` 'not_complete' | 'in_progress' | 'complete' | 'rejected', nullable: Initial status. Defaults to `not_complete`. Send `rejected` to add and immediately reject the row.
  - `cost_components` CostComponentExternalSchema[], nullable: Granular cost breakdown for the line item's pricing.
    - `kind` 'total' | 'labor' | 'material', required: The type of cost component: "total", "labor", or "material".
    - `label` string, nullable: Optional display label for this component.
    - `unit_type` string, nullable: Unit of measurement (e.g. "each", "sqft"). Defaults to "each" if omitted.
    - `unit_cost_in_cents` integer, nullable: Cost per unit in cents.
    - `quantity` string, required: Number of units as a decimal string (e.g. "1", "2.5").
  - `room_id` string, nullable: ID of a [room](/api-reference/rooms/room-object) at the scope's location. Omit to leave the row unroomed.

## Response `200`

OK

- LineItemRowApiResponse
  - `line_item_row` LineItemRowExternalSchema, required
    - `id` string, required
    - `line_item_row_id` string, required: The stable location-level line item ID.
    - `title` string, required
    - `description` string, required
    - `status` 'suggested' | 'not_complete' | 'in_progress' | 'complete' | 'rejected', required
    - `quantity` integer, required: Deprecated: Use cost_components instead. Total quantity (integer).
    - `unit_type` string, required: Deprecated: Use cost_components instead. Unit of measurement (e.g. "each", "sqft").
    - `unit_cost_cents` integer, nullable, required: Deprecated: Use cost_components instead. Cost per unit in cents.
    - `cost_components` CostComponentExternalSchema[], required: Granular cost breakdown. Replaces the legacy quantity/unit_type/unit_cost_cents fields.
      - `kind` 'total' | 'labor' | 'material', required: The type of cost component: "total", "labor", or "material".
      - `label` string, nullable: Optional display label for this component.
      - `unit_type` string, nullable: Unit of measurement (e.g. "each", "sqft"). Defaults to "each" if omitted.
      - `unit_cost_in_cents` integer, nullable: Cost per unit in cents.
      - `quantity` string, required: Number of units as a decimal string (e.g. "1", "2.5").
    - `price_override_reason` string, nullable: The reason recorded when a cost component's price was overridden (e.g. a labor cost change), if a reason was provided. Reflects the most recent price override. Null when no reason was recorded.
    - `price_reference_key` string, nullable, required: Your external identifier for the pricing item used.
    - `notes` string, required
    - `custom_fields` object, required
    - `evidence` union[], required: Supporting evidence — images, audio segments, or text notes.
      - union
        - ImageEvidenceExternalSchema
          - `type` 'image'
          - `image_id` string, required: Use with the Get Image endpoint to retrieve the image file.
          - `reference_key` string, nullable: For an image from Upload an image, the `reference_key` you sent. Images captured in the NavigateAI app can have a value that the app set.
          - `visit_id` string, nullable: The visit this image was captured during. Null for images from Upload an image.
          - `is_selected` boolean: Whether this image was explicitly selected as evidence.
          - `is_starred` boolean: Whether this image was starred as the primary evidence photo.
        - AudioEvidenceExternalSchema
          - `type` 'audio'
          - `start_ms` integer, required: Start timestamp in the source video, in milliseconds.
          - `end_ms` integer, required: End timestamp in the source video, in milliseconds.
          - `text` string, required: Transcribed text from this audio segment.
          - `visit_id` string, nullable: The visit this audio was recorded during. Null when the evidence item is not tied to a visit.
        - TextEvidenceExternalSchema
          - `type` 'text'
          - `text` string, required
          - `visit_id` string, nullable: The visit this text was recorded during. Null when the answer is not tied to a visit.
    - `area_name` string, nullable, required: Deprecated: Use room.name instead. The room or area this line item applies to.
    - `room` LineItemRoomExternalSchema, required: The room or area a line item applies to.
      - `id` string, nullable, required: The [room](/api-reference/rooms/room-object) ID. Null when the room is not currently one of the location's rooms, for example before the visit that recorded it is reviewed, or after the room is removed.
      - `name` string, required: Display name of the room or area (e.g. 'Bedroom 2', 'Kitchen'). Not guaranteed to be stable over time.
      - `room_type_id` string, nullable: The [room type](/api-reference/room-types/room-type-object) ID.
    - `rejection_reason_option_id` string, nullable: ID of the selected [rejection reason option](/api-reference/rejection-reason-options/rejection-reason-option-object), if applicable.
    - `rejection_reason_text` string, nullable: Reason the line item was rejected, if applicable.
    - `vendor` VendorOrganizationExternalSchema
      - `id` string, required
      - `name` string, required
      - `email` string, nullable, required
      - `reference_key` string, required: Optional unique identifier for this vendor in your system.
      - `is_enabled` boolean, required: Whether this vendor is enabled.
      - `market_ids` string[], required: IDs of the markets this vendor serves. A vendor with no market associations serves all markets.
    - `policy_justifications` LineItemPolicyJustificationExternalSchema[], required: Policies this line item was evaluated against, with the reasoning for each, most relevant first. Empty when there are no policy justifications for this line item.
      - `policy` LineItemPolicyExternalSchema, required: A policy a line item was evaluated against.
        - `title` string, required: The title of the policy the line item was evaluated against.
      - `alignment` 'supports' | 'violates' | 'relates', required: Whether the line item supports, violates, or relates to the policy.
      - `reason` string, required: The reasoning for the alignment.

## Changes

- **2026-10-14** `bbdde99b5256`: 1 info
  - added the required property `line_item_row/room/anyOf[subschema #1: LineItemRoom]/id` to the response with the `200` status
- **2026-09-23** `d184e670d61f`: 1 warning, 3 info
  - added the new `in_progress` enum value to the `line_item_row/status` response property for the response status `200`
  - added the new `in_progress` enum value to the request property `status/anyOf[subschema #1]/`
  - added the optional property `line_item_row/evidence/items/anyOf[subschema #2: AudioEvidence]/visit_id` to the response with the `200` status
  - added the optional property `line_item_row/evidence/items/anyOf[subschema #3: TextEvidence]/visit_id` to the response with the `200` status

[Operation history](https://skmtc.dev/navigate/apis/navigateai-api/changes/v1/line_items/post.md)

---

[API](https://skmtc.dev/navigate/apis/navigateai-api.md) - [All operations](https://skmtc.dev/navigate/apis/navigateai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/navigate/apis/navigateai-api/revisions/912b48581de7?raw)