openapi: 3.0.3
info:
  title: iSeeCars Data API
  version: 1.0.0
servers:
  - url: https://www.iseecars.com
security:
  - bearerAuth: []
paths:
  /api/data/v1/capabilities:
    get:
      operationId: discoverVinInsightsCapabilities
      summary: Discover VIN Insights operations available to this request
      description: |
        Read-only discovery costs no credits and has a separate 30 requests/minute limit.
        An API key is not required for eligible requests. First call `GET /api/data/v1/capabilities` without Authorization. If the returned operation specifies `bearer_required: false`, submit that operation without an Authorization header. Otherwise, a valid Bearer API key is required. Access remains subject to availability and usage limits.
        Requests without a Bearer API key receive generic requirements unless
        the server verifies their current eligibility. A valid Bearer API key
        returns caller-specific eligible VIN Insights operations and limits.
        The server determines eligibility; do not claim a client identity in a
        header. Follow each returned operation's bearer_required and
        authorization_header instructions and limits. Do not invent a token
        when instructed to omit Authorization. If no operations are available,
        report the access requirement instead of attempting a lookup.
        An invalid supplied credential is rejected. Availability is checked again
        when executing an operation; discovery does not reserve credits or quota.
        Responses are caller-specific and must not be cached or shared.
      security:
        - {}
        - bearerAuth: []
      responses:
        '200':
          description: Current capabilities, or generic API-key requirements
          headers:
            Cache-Control:
              schema:
                type: string
                example: 'private, no-store'
          content:
            application/json:
              schema:
                type: object
                required: [scope, documentation_url, bearer_required, discovery_credit_cost, operations, message]
                properties:
                  scope:
                    type: string
                    enum: [vin_insights]
                  documentation_url:
                    type: string
                    format: uri
                  bearer_required:
                    type: boolean
                  discovery_credit_cost:
                    type: integer
                    enum: [0]
                  message:
                    type: string
                  operations:
                    type: array
                    items:
                      type: object
                      required: [method, path, bearer_required, authorization_header, products, max_vehicles, requests_per_minute]
                      properties:
                        method:
                          type: string
                          enum: [POST, GET]
                        path:
                          type: string
                          enum: [/api/data/v1/vin-insights]
                        bearer_required:
                          type: boolean
                        authorization_header:
                          type: string
                          description: Whether to omit Authorization or supply a Bearer API key
                        products:
                          type: array
                          items:
                            type: string
                            enum: [market_value, depreciation, remaining_lifespan]
                        max_vehicles:
                          type: integer
                        requests_per_minute:
                          type: integer
                        debug_allowed:
                          type: boolean
                        test_mode_allowed:
                          type: boolean
                        query_parameters:
                          type: array
                          description: Accepted URL query parameters for GET; no request body is accepted.
                          items:
                            type: string
                        required_query_parameters:
                          type: array
                          items:
                            type: string
                        message:
                          type: string
        '401':
          description: Invalid supplied credential or inactive identity
        '403':
          description: Credential is not permitted for this operation
        '405':
          description: Use GET; only GET and OPTIONS are supported
        '429':
          description: Separate discovery rate limit exceeded; honor Retry-After
        '503':
          description: Discovery or verification is temporarily unavailable
  /api/data/v1/vin-insights:
    get:
      operationId: retrieveSingleVinMarketValue
      summary: Retrieve market value for one VIN using URL query parameters.
      description: |
        Use GET for a single VIN market-value lookup, including clients that cannot send POST.
        Supply vin and optionally mileage and zip in the URL, without a request body.
        GET always requests market_value only. Other parameters, repeated parameters,
        batch input, debug and test mode are rejected. Use POST for other products and batches.

        An API key is not required for eligible requests. First call GET /api/data/v1/capabilities
        without Authorization and follow the returned GET operation. If bearer_required is false,
        omit Authorization; otherwise supply a valid Bearer API key. Eligibility, entitlements
        and rate limits are checked on every call. Search crawlers are not granted lookup access.

        Responses use the same results format as POST, with an additional billing_request_id.
        Identical normalized VIN, mileage and ZIP inputs for the same account and key reuse
        one billing identity within each fixed UTC minute. Each HTTP call has its own request_id
        and counts toward the rate limit. A lookup in a later minute may incur a new charge,
        even immediately across a minute boundary. Omitted optional inputs differ from supplied
        inputs. Matching billing outcomes reuse the existing debit; changed status or cost within
        the retry window returns 503 without a second debit. Valuations may be recomputed on retry.

        Responses are private, no-store and noindex. Do not cache or prefetch valuation URLs.
        HEAD is not supported and never executes or bills a valuation.
      security:
        - {}
        - bearerAuth: []
      parameters:
        - name: vin
          in: query
          required: true
          description: One 17-character VIN; letters are normalized to uppercase.
          schema:
            type: string
            pattern: '^[A-HJ-NPR-Za-hj-npr-z0-9]{17}$'
          example: SAJWA6ATXH8K41808
        - name: mileage
          in: query
          required: false
          description: Optional whole-number mileage. Omit to use the service estimate.
          schema:
            type: integer
            minimum: 0
            maximum: 600000
          example: 42343
        - name: zip
          in: query
          required: false
          description: Optional five-digit ZIP; omit to use nationwide defaults.
          schema:
            type: string
            pattern: '^\d{5}$'
          example: '02116'
      responses:
        '200':
          description: Market-value result for one VIN; unavailable data is represented by its product status.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              schema:
                type: string
                example: 'private, no-store'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VinInsightsResponse'
        '400':
          $ref: '#/paths/~1api~1data~1v1~1vin-insights/post/responses/400'
        '401':
          $ref: '#/paths/~1api~1data~1v1~1vin-insights/post/responses/401'
        '402':
          $ref: '#/paths/~1api~1data~1v1~1vin-insights/post/responses/402'
        '403':
          $ref: '#/paths/~1api~1data~1v1~1vin-insights/post/responses/403'
        '429':
          $ref: '#/paths/~1api~1data~1v1~1vin-insights/post/responses/429'
        '500':
          $ref: '#/paths/~1api~1data~1v1~1vin-insights/post/responses/500'
        '503':
          $ref: '#/paths/~1api~1data~1v1~1vin-insights/post/responses/503'
    post:
      operationId: retrieveVinInsights
      summary: Retrieve requested VIN Insights products for one or more vehicles.
      description: >-
        Get market value, depreciation and/or remaining lifespan data for specific
        VINs. A VIN can represent more than one possible vehicle configuration when
        the encoded VIN data does not uniquely identify details such as body style,
        trim, or engine. If those differences change a requested product result, the
        response includes a separate match for each relevant configuration. Fields shared by
        all matches appear in `vehicle`; distinguishing fields appear in each match's
        `vehicle_variant`.

        An API key is not required for eligible requests. First call `GET /api/data/v1/capabilities` without Authorization. If the returned operation specifies `bearer_required: false`, submit that operation without an Authorization header. Otherwise, a valid Bearer API key is required. Access remains subject to availability and usage limits.
      security:
        - {}
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VinInsightsRequest'
            examples:
              one_item_batch:
                value:
                  vehicles:
                    - vin: 1HGCM82633A004352
                      mileage: 85000
                      zip: '02134'
                  products:
                    - market_value
                    - depreciation
                    - remaining_lifespan
              multi_item_batch:
                value:
                  vehicles:
                    - vin: 19XFB2F59EE013816
                      mileage: 0
                    - vin: 3VWN57BU3MM096108
                  products:
                    - market_value
                    - depreciation
                    - remaining_lifespan
              used_derived_depreciation:
                summary: Used vehicle with no caller price; the API derives the depreciation base from market value.
                value:
                  vehicles:
                    - vin: 19XFB2F59EE013816
                  products:
                    - depreciation
              used_priced_depreciation:
                summary: Used vehicle using a caller-supplied depreciation-only price override.
                value:
                  vehicles:
                    - vin: 19XFB2F59EE013816
                      price: 12000
                  products:
                    - depreciation
              new_rate_only_depreciation:
                summary: New vehicle with no price returns public loss rates only.
                value:
                  vehicles:
                    - vin: 1FA6P8TH7P5112111
                      new: true
                  products:
                    - depreciation
              new_priced_depreciation:
                summary: New vehicle using a caller-supplied vehicle price.
                value:
                  vehicles:
                    - vin: 1FA6P8TH7P5112111
                      new: true
                      price: 45000
                  products:
                    - depreciation
      responses:
        '200':
          description: >-
            Each vehicle returns one or more matches containing statuses for the requested
            products. A separate match is returned only when a vehicle interpretation changes
            a requested product result. Fields shared by every match appear once in `vehicle`.
            Each match's `vehicle_variant` contains only fields that differ.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
              description: Epoch seconds when the current rate-limit window resets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VinInsightsResponse'
              examples:
                all_products:
                  value:
                    request_id: 7cc2b425-63a4-4f7a-9f46-0bd0ee5d6786
                    testMode: true
                    results:
                      - vin: 19XFB2F59EE013816
                        vehicle:
                          year: 2014
                          make: Honda
                          model: Civic
                          trim: LX
                          body_type: Sedan
                          fuel_type: Gasoline
                          drive_type: FWD
                        matches:
                          - market_value:
                              status: success
                              data:
                                value: 11235
                                currency: USD
                                estimated_mileage: 85000
                            depreciation:
                              status: success
                              data:
                                three_years: 2505
                                five_years: 3994
                                three_year_depreciation_rate: 0.2230012468
                                five_year_depreciation_rate: 0.3554969102
                                currency: USD
                            remaining_lifespan:
                              status: success
                              data:
                                years: 7.7
                                miles: 169811
                      - vin: BADVIN
                        error:
                          code: invalid_vin
                          message: Invalid VIN
                multiple_matches:
                  summary: Only vehicle alternatives that change a requested result create matches.
                  value:
                    request_id: 2b6088d2-c2a5-4f16-9a72-91971d3b933e
                    testMode: true
                    results:
                      - vin: 1FTFW1ET1DFA00001
                        vehicle:
                          year: 2013
                          make: Ford
                          model: F-150
                          trim: XLT
                          body_type: Pickup Truck
                          fuel_type: Gasoline
                          drive_type: 4WD
                        matches:
                          - vehicle_variant:
                              body_subtype: Crew Cab
                            market_value:
                              status: success
                              data:
                                value: 17350
                                currency: USD
                          - vehicle_variant:
                              body_subtype: Extended Cab
                            market_value:
                              status: success
                              data:
                                value: 16825
                                currency: USD
                used_derived_depreciation:
                  summary: Used vehicle without caller price uses its calculated market value as the depreciation base.
                  value:
                    request_id: 15f1ec53-ea4e-4b87-a999-7702f74972c9
                    testMode: true
                    results:
                      - vin: 19XFB2F59EE013816
                        vehicle:
                          year: 2014
                          make: Honda
                          model: Civic
                        matches:
                          - depreciation:
                              status: success
                              data:
                                three_year_depreciation_rate: 0.2230012468
                                five_year_depreciation_rate: 0.3554969102
                                three_years: 2505
                                five_years: 3994
                                currency: USD
                used_priced_depreciation:
                  summary: Used caller price produces reproducible amounts from the published rates.
                  value:
                    request_id: 2c1fb653-ea4e-4b87-a999-7702f74972c9
                    testMode: true
                    results:
                      - vin: 19XFB2F59EE013816
                        vehicle:
                          year: 2014
                          make: Honda
                          model: Civic
                        matches:
                          - depreciation:
                              status: success
                              data:
                                three_year_depreciation_rate: 0.2230012468
                                five_year_depreciation_rate: 0.3554969102
                                three_years: 2676
                                five_years: 4266
                                currency: USD
                new_rate_only_depreciation:
                  summary: New vehicle without a caller price returns depreciation rates without dollar amounts.
                  value:
                    request_id: 3c1fb653-ea4e-4b87-a999-7702f74972c9
                    testMode: true
                    results:
                      - vin: 1FA6P8TH7P5112111
                        vehicle:
                          year: 2023
                          make: Ford
                          model: Mustang
                        matches:
                          - depreciation:
                              status: success
                              data:
                                three_year_depreciation_rate: 0.2365774729
                                five_year_depreciation_rate: 0.3146231150
                new_priced_depreciation:
                  summary: New-vehicle loss from the submitted price to estimated used value.
                  value:
                    request_id: d8c31583-405b-4f4a-b103-f50080152ead
                    testMode: true
                    results:
                      - vin: 1FA6P8TH7P5112111
                        vehicle:
                          year: 2023
                          make: Ford
                          model: Mustang
                          body_type: Coupe
                          fuel_type: Gasoline
                          drive_type: RWD
                        matches:
                          - depreciation:
                              status: success
                              data:
                                three_year_depreciation_rate: 0.2365774729
                                five_year_depreciation_rate: 0.3146231150
                                three_years: 10646
                                five_years: 14158
                                currency: USD
                fixed_only:
                  summary: Disabled or unentitled products do not require VIN decoding.
                  value:
                    request_id: 2b6088d2-c2a5-4f16-9a72-91971d3b933e
                    testMode: true
                    results:
                      - vin: 19XFB2F59EE013816
                        vehicle: null
                        matches:
                          - depreciation:
                              status: disabled
        '400':
          description: Invalid JSON, request shape, new/price combination, mileage, ZIP, trim, products, or required fields.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid bearer token.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '402':
          description: >-
            `insufficient_funds` — contact your account representative before retrying.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The authenticated key lacks the required data:vin_insights scope, or testMode=true was requested without data:vin_insights:test.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            Retry-After:
              schema:
                type: integer
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '413':
          description: Request body exceeds 65,536 bytes.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '415':
          description: Content-Type is missing or is not application/json.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Unexpected server error.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Authentication or rate-limit infrastructure is unavailable.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/data/v1/window-sticker/lookups:
    post:
      operationId: startWindowStickerLookup
      summary: Request a Window Sticker or Build Sheet.
      description: |
        Request a document for one VIN. A successful result may be either a Window
        Sticker or a Build Sheet, identified by `result.document_type`.

        This operation is asynchronous because the document may not be ready immediately:

        1. Submit the VIN with this endpoint.
        2. Save the `lookup_id` or `status_url` from the `202` response.
        3. Check the status endpoint no more often than every two seconds, and honor
           `Retry-After` when it is returned.
        4. Continue until the status is `success`, `not_available`, or `failed`.

        Processing may take several seconds. Continue polling until a terminal status is
        returned; do not assume the document is ready when this request returns.

        Requires `data:window_sticker` and enabled Window Sticker access. Test mode requires
        `data:window_sticker:test` and uses the same live fulfillment flow as a standard
        request. By default, test mode is restricted to a small set of approved VINs.
        Accounts approved for unrestricted test use may submit any otherwise valid VIN.
        Other test-mode VINs return `400 test_vin_not_allowed` for restricted accounts.

        By default, an account may create 10 Window Sticker lookup requests per minute
        across all of its API keys. This limit can be adjusted per account based on expected
        usage patterns. Status requests do not count toward this limit. Unavailable service
        returns `503 temporarily_unavailable`; disabled account access returns `403
        forbidden_window_sticker`. A request remains readable by the account that created it.
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WindowStickerLookupRequest'
            example:
              vin: 1FTEW1E50JKF86414
              testMode: false
              devServerAffinity: false
      responses:
        '202':
          description: The request was accepted and queued; the document is not ready yet.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WindowStickerQueuedResponse'
        '400':
          $ref: '#/components/responses/WindowStickerBadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          $ref: '#/components/responses/InsufficientFunds'
        '403':
          $ref: '#/components/responses/Forbidden'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/TemporarilyUnavailable'
  /api/data/v1/window-sticker/lookups/{lookup_id}:
    get:
      operationId: getWindowStickerLookupStatus
      summary: Get a Window Sticker request's status or result.
      description: >-
        Keep the `lookup_id` or `status_url` returned when the lookup is created.
        Wait at least two seconds between status requests. If a response includes
        `Retry-After`, wait the specified number of seconds before trying again.
        `queued` and `running` mean processing is not finished. Continue until the
        status is `success`, `not_available`, or `failed`. A `success` response includes
        `result.document_url` for the PDF. `not_available` means no Window Sticker or Build
        Sheet was found. `failed` means processing did not complete; see the returned error
        for more information. The JSON `request_id` remains the creation request UUID; each
        HTTP response has its own `X-Request-ID`. Each status request only returns the current
        state of that original request and never submits another Window Sticker request. A
        request is readable only by the account that created it.
      security:
        - bearerAuth: []
      parameters:
        - name: lookup_id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/WindowStickerLookupId'
      responses:
        '200':
          description: Current lookup state.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              schema:
                type: integer
            X-RateLimit-Remaining:
              schema:
                type: integer
            X-RateLimit-Reset:
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WindowStickerLookupResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: >-
            `lookup_not_found` — the lookup does not exist or belongs to another account.
          headers:
            X-Request-ID:
              $ref: '#/components/headers/RequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/TemporarilyUnavailable'
components:
  responses:
    BadRequest:
      description: >-
        `bad_request` or `invalid_vin` — correct the request before retrying.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    WindowStickerBadRequest:
      description: >-
        `bad_request` or `invalid_vin` means the request must be corrected.
        `dev_server_affinity_unavailable` means `devServerAffinity=true` was
        sent somewhere other than a supported development server.
        `test_vin_not_allowed` means a restricted account submitted a VIN that
        is not approved for test mode; its exact message is
        `This VIN is not available in test mode.`
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: An `unauthorized_*` code identifies a missing or invalid bearer token, revoked key, or inactive account. Correct the credentials before retrying.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: A `forbidden_*` code identifies a missing scope, unavailable test mode, or disabled account feature. Update the key or account access before retrying.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InsufficientFunds:
      description: >-
        `insufficient_funds` — prepaid credits are required and the account does
        not have enough. Contact your account representative before retrying.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PayloadTooLarge:
      description: >-
        `payload_too_large` — reduce the request body below 65,536 bytes before retrying.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnsupportedMediaType:
      description: >-
        `unsupported_media_type` — send the request as `application/json`.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    RateLimited:
      description: >-
        `rate_limited` — the account's general request limit or Window Sticker
        creation limit was exceeded. Wait for `Retry-After` before retrying.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          schema:
            type: integer
        X-RateLimit-Limit:
          schema:
            type: integer
        X-RateLimit-Remaining:
          schema:
            type: integer
        X-RateLimit-Reset:
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: >-
        `internal_error` — an unexpected server error occurred.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TemporarilyUnavailable:
      description: >-
        `temporarily_unavailable` or `unknown_error` — a required authentication,
        rate-limit, or Window Sticker service is temporarily unavailable. Honor
        `Retry-After` when present.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/RequestId'
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying, when supplied.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    RequestId:
      description: >-
        Server-generated UUID used to correlate this HTTP response with its usage records.
      schema:
        type: string
        format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    WindowStickerLookupId:
      type: string
      pattern: '^wslk_[a-f0-9]{32}$'
    WindowStickerLookupRequest:
      type: object
      additionalProperties: false
      required:
        - vin
      properties:
        vin:
          type: string
          pattern: '^[A-HJ-NPR-Za-hj-npr-z0-9]{17}$'
          description: A 17-character VIN, normalized to uppercase.
        testMode:
          type: boolean
          default: false
          description: >-
            Requires `data:window_sticker:test`. It follows the same request,
            status, and response contract as a standard lookup and uses live
            fulfillment. By default, test mode is restricted to a small set of
            approved VINs. Accounts approved for unrestricted test use may
            submit any otherwise valid VIN.
        devServerAffinity:
          type: boolean
          default: false
          description: >-
            Development-only diagnostic option. When true on a supported
            development server, all processing attempts for the lookup are
            restricted to that receiving server. The request is rejected when
            the receiving development worker cannot provide that guarantee.
    WindowStickerLookupResponse:
      oneOf:
        - $ref: '#/components/schemas/WindowStickerQueuedResponse'
        - $ref: '#/components/schemas/WindowStickerRunningResponse'
        - $ref: '#/components/schemas/WindowStickerSuccessResponse'
        - $ref: '#/components/schemas/WindowStickerNotAvailableResponse'
        - $ref: '#/components/schemas/WindowStickerFailedResponse'
      discriminator:
        propertyName: status
        mapping:
          queued: '#/components/schemas/WindowStickerQueuedResponse'
          running: '#/components/schemas/WindowStickerRunningResponse'
          success: '#/components/schemas/WindowStickerSuccessResponse'
          not_available: '#/components/schemas/WindowStickerNotAvailableResponse'
          failed: '#/components/schemas/WindowStickerFailedResponse'
    WindowStickerQueuedResponse:
      type: object
      additionalProperties: false
      required:
        - request_id
        - lookup_id
        - status
        - vin
        - status_url
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
        lookup_id:
          $ref: '#/components/schemas/WindowStickerLookupId'
        status:
          type: string
          enum:
            - queued
        vin:
          type: string
        status_url:
          type: string
          pattern: '^/api/data/v1/window-sticker/lookups/wslk_[a-f0-9]{32}$'
        created_at:
          type: string
          format: date-time
      example:
        request_id: 86db5f02-8b32-4609-9710-c84242e17576
        lookup_id: wslk_6f1a2b3c4d5e6789a123456789abcdef
        status: queued
        vin: 1FTEW1E50JKF86414
        status_url: /api/data/v1/window-sticker/lookups/wslk_6f1a2b3c4d5e6789a123456789abcdef
        created_at: '2026-08-21T16:00:00Z'
    WindowStickerRunningResponse:
      type: object
      additionalProperties: false
      required:
        - request_id
        - lookup_id
        - status
        - vin
        - created_at
      properties:
        request_id:
          type: string
          format: uuid
        lookup_id:
          $ref: '#/components/schemas/WindowStickerLookupId'
        status:
          type: string
          enum:
            - running
        vin:
          type: string
        created_at:
          type: string
          format: date-time
      example:
        request_id: 86db5f02-8b32-4609-9710-c84242e17576
        lookup_id: wslk_6f1a2b3c4d5e6789a123456789abcdef
        status: running
        vin: 1FTEW1E50JKF86414
        created_at: '2026-08-21T16:00:00Z'
    WindowStickerSuccessResponse:
      type: object
      additionalProperties: false
      required:
        - request_id
        - lookup_id
        - status
        - vin
        - created_at
        - completed_at
        - result
      properties:
        request_id:
          type: string
          format: uuid
        lookup_id:
          $ref: '#/components/schemas/WindowStickerLookupId'
        status:
          type: string
          enum:
            - success
        vin:
          type: string
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        result:
          $ref: '#/components/schemas/WindowStickerDocumentResult'
      example:
        request_id: 86db5f02-8b32-4609-9710-c84242e17576
        lookup_id: wslk_6f1a2b3c4d5e6789a123456789abcdef
        status: success
        vin: 1FTEW1E50JKF86414
        created_at: '2026-08-21T16:00:00Z'
        completed_at: '2026-08-21T16:00:12Z'
        result:
          document_type: window_sticker
          document_format: pdf
          document_url: https://www.iseecars.com/window-sticker-show?vin=1FTEW1E50JKF86414&key=example-share-key&pdf=true&v=83&fullMode&dapi=true
          year: 2018
          make: Ford
          model: F-150
    WindowStickerNotAvailableResponse:
      type: object
      additionalProperties: false
      required:
        - request_id
        - lookup_id
        - status
        - vin
        - created_at
        - completed_at
        - result
      properties:
        request_id:
          type: string
          format: uuid
        lookup_id:
          $ref: '#/components/schemas/WindowStickerLookupId'
        status:
          type: string
          enum:
            - not_available
        vin:
          type: string
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        result:
          type: object
          nullable: true
          enum:
            - null
      example:
        request_id: 86db5f02-8b32-4609-9710-c84242e17576
        lookup_id: wslk_6f1a2b3c4d5e6789a123456789abcdef
        status: not_available
        vin: 1FTEW1E50JKF86414
        created_at: '2026-08-21T16:00:00Z'
        completed_at: '2026-08-21T16:00:12Z'
        result: null
    WindowStickerFailedResponse:
      type: object
      additionalProperties: false
      required:
        - request_id
        - lookup_id
        - status
        - vin
        - created_at
        - completed_at
        - error
      properties:
        request_id:
          type: string
          format: uuid
        lookup_id:
          $ref: '#/components/schemas/WindowStickerLookupId'
        status:
          type: string
          enum:
            - failed
        vin:
          type: string
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        error:
          $ref: '#/components/schemas/WindowStickerFailure'
      example:
        request_id: 86db5f02-8b32-4609-9710-c84242e17576
        lookup_id: wslk_6f1a2b3c4d5e6789a123456789abcdef
        status: failed
        vin: 1FTEW1E50JKF86414
        created_at: '2026-08-21T16:00:00Z'
        completed_at: '2026-08-21T16:00:12Z'
        error:
          code: lookup_failed
          message: A service error prevented this lookup. The document may still be available; please try again.
    # Internal integrity guarantee: persist only a validated relative share path,
    # then compose document_url from the status-serving environment's origin.
    WindowStickerDocumentResult:
      type: object
      additionalProperties: false
      required:
        - document_type
        - document_format
        - document_url
      properties:
        document_type:
          type: string
          enum:
            - window_sticker
            - build_sheet
        document_format:
          type: string
          enum:
            - pdf
        document_url:
          type: string
          format: uri
          description: Absolute URL for downloading the PDF. Treat this URL as opaque and use it exactly as returned.
        year:
          type: integer
        make:
          type: string
        model:
          type: string
        trim:
          type: string
    WindowStickerFailure:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - lookup_failed
        message:
          type: string
          enum:
            - A service error prevented this lookup. The document may still be available; please try again.
    VinInsightsRequest:
      type: object
      required:
        - vehicles
      additionalProperties: false
      properties:
        vehicles:
          type: array
          minItems: 1
          maxItems: 50
          items:
            $ref: '#/components/schemas/VinInsightsVehicleRequest'
        testMode:
          type: boolean
          default: false
          description: When true, the bearer key must include data:vin_insights:test. The scope alone does not activate test mode when this field is false or omitted.
        products:
          type: array
          minItems: 1
          items:
            type: string
            enum:
              - market_value
              - depreciation
              - remaining_lifespan
    VinInsightsVehicleRequest:
      type: object
      required:
        - vin
      additionalProperties: false
      description: >-
        One vehicle to evaluate. The vehicle is treated as used when `new` is omitted
        or false. `price` is optional and is used only to calculate depreciation; it
        does not change the market-value result.
      properties:
        vin:
          type: string
          pattern: '^[A-HJ-NPR-Za-hj-npr-z0-9]{17}$'
          description: Letters are case-insensitive and normalized to uppercase.
        mileage:
          type: integer
          minimum: 0
          maximum: 600000
          description: Optional mileage for this vehicle item only.
        trim:
          type: string
          description: Optional trim hint for this vehicle item only.
        zip:
          type: string
          pattern: '^\d{5}$'
          description: Optional five-digit ZIP for this vehicle. Omit it to use nationwide defaults.
        new:
          type: boolean
          default: false
          description: >-
            Whether the vehicle is new for depreciation. Omitted is equivalent to
            false. When true, depreciation always projects from new to vehicle ages
            three and five; the VIN model year still selects the coefficient row.
            Price is optional for either condition.
        price:
          type: integer
          format: int32
          minimum: 1
          maximum: 2147483647
          nullable: true
          description: >-
            Caller-supplied positive whole-dollar USD vehicle-only purchase or list
            price used only as the depreciation base for either new or used vehicles.
            A null or omitted price provides no caller base. For used vehicles, a
            supplied price overrides derived market/listing value only for depreciation;
            it does not alter market_value. For new vehicles, no other base is inferred.
    VinInsightsResponse:
      type: object
      additionalProperties: false
      required:
        - request_id
        - testMode
        - results
      properties:
        request_id:
          type: string
          format: uuid
        billing_request_id:
          type: string
          format: uuid
          description: GET only. Shared product-usage and debit identity for equivalent inputs in a fixed UTC minute; request_id remains unique per HTTP call.
        testMode:
          type: boolean
        results:
          type: array
          items:
            $ref: '#/components/schemas/VinInsightResult'
    VinInsightResult:
      oneOf:
        - $ref: '#/components/schemas/VinInsightSuccessResult'
        - $ref: '#/components/schemas/VinInsightErrorResult'
    VinInsightSuccessResult:
      type: object
      required:
        - vin
        - vehicle
        - matches
      additionalProperties: false
      properties:
        vin:
          type: string
        vehicle:
          $ref: '#/components/schemas/Vehicle'
        matches:
          type: array
          minItems: 1
          maxItems: 20
          description: >-
            One match is returned for each vehicle configuration that changes a
            requested product result.
          items:
            $ref: '#/components/schemas/VinInsightMatch'
    VinInsightErrorResult:
      type: object
      required:
        - vin
        - error
      additionalProperties: false
      properties:
        vin:
          type: string
        error:
          $ref: '#/components/schemas/ErrorResponse'
    VinInsightMatch:
      type: object
      additionalProperties: false
      description: >-
        Requested product results for one vehicle configuration. To construct the
        complete vehicle for a match, start with the result-level `vehicle` object and
        replace any fields also supplied in `vehicle_variant`. The variant contains only
        differing fields and is omitted when there are none. When `vehicle` is null, the
        response contains one match, no variant, and no successful product results.
      properties:
        vehicle_variant:
          $ref: '#/components/schemas/VehicleVariant'
        market_value:
          $ref: '#/components/schemas/MarketValueProductResult'
        depreciation:
          $ref: '#/components/schemas/DepreciationProductResult'
        remaining_lifespan:
          $ref: '#/components/schemas/RemainingLifespanProductResult'
    Vehicle:
      type: object
      nullable: true
      additionalProperties: false
      description: >-
        Decoded fields shared by every returned match. A response with one decoded match
        contains all vehicle fields here and omits `vehicle_variant`. This value is null
        when the API cannot return a usable decoded vehicle. If the available fields
        cannot distinguish configurations that produce different product results, the
        API returns null here and `internal_error` for products it attempted to evaluate;
        products that are disabled or not entitled keep those statuses.
      properties:
        year:
          type: integer
        make:
          type: string
        model:
          type: string
        trim:
          type: string
        body_type:
          type: string
          description: Decoded DataOne body type.
        body_subtype:
          type: string
        fuel_type:
          type: string
        drive_type:
          type: string
        bed_length:
          type: number
          format: float
          minimum: 0
          exclusiveMinimum: true
          description: Pickup bed length in feet; present only when needed to distinguish matches.
        transmission:
          type: string
          minLength: 1
          maxLength: 100
          description: Normalized transmission label; present only when needed to distinguish matches.
        engine_displacement:
          type: number
          format: float
          minimum: 0
          exclusiveMinimum: true
          description: Engine displacement in liters; present only when needed to distinguish matches.
        engine_cylinders:
          type: integer
          minimum: 1
          description: Engine cylinder count; present only when needed to distinguish matches.
        doors:
          type: integer
          minimum: 1
          description: Door count; present only when needed to distinguish matches.
        wheelbase:
          type: number
          format: float
          minimum: 0
          exclusiveMinimum: true
          description: Wheelbase in inches; present only when needed to distinguish matches.
        style:
          type: string
          minLength: 1
          maxLength: 100
          description: Decoded customer-readable style; present only when needed to distinguish matches.
    VehicleVariant:
      type: object
      minProperties: 1
      additionalProperties: false
      description: >-
        Non-empty residual decoded fields for one match after removing every field in
        the result-level shared vehicle. Omitted when no fields remain. Core fields may
        appear here when they differ; optional decoded fields appear only as the minimum
        sufficient discriminator set selected before ordering and calculation.
      properties:
        year:
          type: integer
        make:
          type: string
        model:
          type: string
        trim:
          type: string
        body_type:
          type: string
          description: Decoded DataOne body type.
        body_subtype:
          type: string
        fuel_type:
          type: string
        drive_type:
          type: string
        bed_length:
          type: number
          format: float
          minimum: 0
          exclusiveMinimum: true
          description: Pickup bed length in feet; present only when needed to distinguish matches.
        transmission:
          type: string
          minLength: 1
          maxLength: 100
          description: Normalized transmission label; present only when needed to distinguish matches.
        engine_displacement:
          type: number
          format: float
          minimum: 0
          exclusiveMinimum: true
          description: Engine displacement in liters; present only when needed to distinguish matches.
        engine_cylinders:
          type: integer
          minimum: 1
          description: Engine cylinder count; present only when needed to distinguish matches.
        doors:
          type: integer
          minimum: 1
          description: Door count; present only when needed to distinguish matches.
        wheelbase:
          type: number
          format: float
          minimum: 0
          exclusiveMinimum: true
          description: Wheelbase in inches; present only when needed to distinguish matches.
        style:
          type: string
          minLength: 1
          maxLength: 100
          description: Decoded customer-readable style; present only when needed to distinguish matches.
    MarketValueProductResult:
      oneOf:
        - $ref: '#/components/schemas/MarketValueSuccessProductResult'
        - $ref: '#/components/schemas/NotAvailableProductResult'
        - $ref: '#/components/schemas/NotEntitledProductResult'
        - $ref: '#/components/schemas/DisabledProductResult'
        - $ref: '#/components/schemas/InternalErrorProductResult'
    DepreciationProductResult:
      oneOf:
        - $ref: '#/components/schemas/DepreciationSuccessProductResult'
        - $ref: '#/components/schemas/NotAvailableProductResult'
        - $ref: '#/components/schemas/NotEntitledProductResult'
        - $ref: '#/components/schemas/DisabledProductResult'
        - $ref: '#/components/schemas/InternalErrorProductResult'
    RemainingLifespanProductResult:
      oneOf:
        - $ref: '#/components/schemas/RemainingLifespanSuccessProductResult'
        - $ref: '#/components/schemas/NotAvailableProductResult'
        - $ref: '#/components/schemas/NotEntitledProductResult'
        - $ref: '#/components/schemas/DisabledProductResult'
        - $ref: '#/components/schemas/InternalErrorProductResult'
    MarketValueSuccessProductResult:
      type: object
      required:
        - status
        - data
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
            - success
        data:
          $ref: '#/components/schemas/MarketValueData'
    DepreciationSuccessProductResult:
      type: object
      required:
        - status
        - data
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
            - success
        data:
          $ref: '#/components/schemas/DepreciationData'
    RemainingLifespanSuccessProductResult:
      type: object
      required:
        - status
        - data
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
            - success
        data:
          $ref: '#/components/schemas/RemainingLifespanData'
    NotAvailableProductResult:
      type: object
      required:
        - status
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
            - not_available
    NotEntitledProductResult:
      type: object
      required:
        - status
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
            - not_entitled
    DisabledProductResult:
      type: object
      required:
        - status
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
            - disabled
    InternalErrorProductResult:
      type: object
      required:
        - status
      additionalProperties: false
      properties:
        status:
          type: string
          enum:
            - internal_error
    MarketValueData:
      type: object
      additionalProperties: false
      required:
        - value
      properties:
        value:
          type: integer
          minimum: 0
        currency:
          type: string
          enum:
            - USD
        estimated_mileage:
          type: integer
          description: Effective mileage used for the market-value result when known.
        zip:
          type: string
          description: Present only when the request vehicle item supplied ZIP.
    DepreciationData:
      type: object
      description: >-
        For each available three-year or five-year period, the API returns a loss rate
        from 0 through 1, rounded to ten decimal places using half-up rounding. When a
        positive starting value is available, it also returns the corresponding whole-dollar
        USD loss and `currency`. For used vehicles, a submitted price is used first;
        otherwise the API uses market value, then an available listing or asking price.
        Used depreciation is unavailable when none of those values is positive. New vehicles
        without a submitted price return rates without dollar amounts and do not infer a
        price. Model year 2010 or newer is required. Used future model years are unsupported.
        New vehicles may use model years through the next calendar model year and are always
        projected from age zero. For used vehicles, a period is returned only when the
        vehicle's current age plus that period is no more than 20 years.
      additionalProperties: false
      oneOf:
        - title: Rate only
          anyOf:
            - required:
                - three_year_depreciation_rate
            - required:
                - five_year_depreciation_rate
          not:
            anyOf:
              - required:
                  - three_years
              - required:
                  - five_years
              - required:
                  - currency
        - title: Three-year amount
          required:
            - three_year_depreciation_rate
            - three_years
            - currency
          not:
            anyOf:
              - required:
                  - five_year_depreciation_rate
              - required:
                  - five_years
        - title: Five-year amount
          required:
            - five_year_depreciation_rate
            - five_years
            - currency
          not:
            anyOf:
              - required:
                  - three_year_depreciation_rate
              - required:
                  - three_years
        - title: Both amounts
          required:
            - three_year_depreciation_rate
            - three_years
            - five_year_depreciation_rate
            - five_years
            - currency
      properties:
        three_years:
          type: integer
          minimum: 0
          description: Nonnegative USD depreciation loss over three years. Omitted when the used-vehicle target age exceeds 20 or required inputs are unavailable.
        five_years:
          type: integer
          minimum: 0
          description: Nonnegative USD depreciation loss over five years. Omitted when the used-vehicle target age exceeds 20 or required inputs are unavailable.
        currency:
          type: string
          enum:
            - USD
        three_year_depreciation_rate:
          type: number
          minimum: 0
          maximum: 1
          multipleOf: 0.0000000001
          description: Loss rate over three years, rounded to ten decimal places using half-up rounding.
        five_year_depreciation_rate:
          type: number
          minimum: 0
          maximum: 1
          multipleOf: 0.0000000001
          description: Loss rate over five years, rounded to ten decimal places using half-up rounding.
    RemainingLifespanData:
      type: object
      additionalProperties: false
      anyOf:
        - required:
            - years
        - required:
            - miles
      properties:
        years:
          type: number
          format: double
          minimum: 0
        miles:
          type: integer
          minimum: 0
    ErrorResponse:
      type: object
      additionalProperties: false
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Stable machine-readable error code. Use the HTTP status and this value to decide whether to correct the request, update access, or retry.
          enum:
            - bad_request
            - invalid_vin
            - trim_not_supported
            - unauthorized_missing_bearer
            - unauthorized_invalid_scheme
            - unauthorized_malformed_token
            - unauthorized_invalid_key
            - unauthorized_invalid_account
            - unauthorized_revoked_key
            - unauthorized_inactive_account
            - forbidden_scope
            - forbidden_test_mode
            - forbidden_window_sticker
            - dev_server_affinity_unavailable
            - test_vin_not_allowed
            - insufficient_funds
            - payload_too_large
            - unsupported_media_type
            - rate_limited
            - temporarily_unavailable
            - unknown_error
            - internal_error
            - not_found
            - lookup_not_found
            - method_not_allowed
        message:
          type: string