Decisiv Customer Assets API

openapi: 3.2.0
info:
  version: 0.48.24
  termsOfService: https://www.decisiv.com/terms-of-use
  contact:
    name: Decisiv Support
    email: support@decisiv.com
    url: https://www.decisiv.com
  title: Service Management Customer Assets API
  description: The **Decisiv SRM Gateway** `Service Management` module provides the API functionality for managing an asset's case lifecycle from a Service Providers perspective.
  license:
    name: Proprietary
    identifier: proprietary
    url: https://www.decisiv.com/terms-of-use/
servers:
- url: https://srm-api.staging.decisivapps.com
- url: https://srm-api.decisivapps.com
security:
- OAuth2AuthorizationCode: []
  AccessToken: []
- OAuth2Password: []
  AccessToken: []
tags:
- name: Customer Assets
paths:
  /service_management/{srm_account_id}/v1/customer_assets:
    get:
      summary: List all customer assets for the requested account
      tags:
      - Customer Assets
      parameters:
      - name: srm_account_id
        in: path
        description: The account ID for SRM
        required: true
        schema:
          type: string
      - name: filter[serial_number]
        in: query
        required: false
        schema:
          type: string
          minLength: 8
          maxLength: 9
        description: Filter `customer_assets` matching the *exact* `serial_number` attribute.
      - name: filter[unit_number]
        in: query
        required: false
        schema:
          type: string
        description: Filter `customer_assets` matching the *exact* `unit_number` attribute.
      - name: filter[vin]
        in: query
        required: false
        schema:
          type: string
          minLength: 17
          maxLength: 17
        description: Filter `customer_assets` matching the *exact* `vin` attribute.
      - name: filter[chassis_id]
        in: query
        required: false
        schema:
          type: string
          maxLength: 50
        description: Filter `customer_assets` matching the *exact* `chassis_id` attribute.
      - name: filter[customer.id]
        in: query
        required: false
        schema:
          type: string
          format: uuid
        description: Filter `customer_assets` matching the *exact* `customer.id` attribute.
      - name: filter[service_status]
        in: query
        required: false
        schema:
          type: string
          enum:
          - active
          - inactive
          - archived
        description: Filter `customer_assets` matching the *exact* `service_status` attribute.
      - name: filter[service_status:includes]
        in: query
        required: false
        schema:
          type: string
        description: List `customer_assets` whose `service_status` is in the supplied comma-separated list. Accepted values are `active`, `inactive`, `archived`.
      - name: filter[service_status:excludes]
        in: query
        required: false
        schema:
          type: string
        description: List `customer_assets` whose `service_status` is **NOT** in the supplied comma-separated list. Accepted values are `active`, `inactive`, `archived`.
      - name: page[number]
        in: query
        required: false
        schema:
          type: integer
          default: 1
          minimum: 1
        description: Sets the desired `page` when encountering larger result sets
      - name: page[size]
        in: query
        required: false
        schema:
          type: integer
          default: 25
          minimum: 1
        description: Sets the desired maximum number of results per page
      - name: include
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - customer
            - srm_verified_asset
        description: Return specified included relationships upon request
      - name: sort
        in: query
        required: false
        schema:
          type: string
          example: -year
        description: 'Sort `customer_assets` by a single attribute; prefix with `-` for descending order. Valid attributes: `year`, `make`, `model`'
      responses:
        '200':
          description: Returns list of customer assets
          content:
            application/vnd.api+json:
              example:
                data:
                - id: aa3e7935-bfe2-475e-9be2-80ccef5477c8
                  type: customer_assets
                  attributes:
                    vin: 3B7HF13Z11M269883
                    serial_number: HN991562
                    unit_number: NU2695
                    chassis_id: N-991562
                    make: Make
                    model: CH613
                    year: 2017
                    service_status: active
                    engine:
                      make: Engine Make
                      model: X15
                      displacement: 14.8L
                      serial_number: '79412345'
                    odometer_value: 125000
                    odometer_unit: mi
                    vmrs:
                      asset_type:
                        code_key: '2'
                        code: D
                  links:
                    source_application: https://{host}/vehicles/{id}/edit
                    self: https://srm-api.decisivapps.com/api/service_management/{srm_account_id}/v1/customer_assets/aa3e7935-bfe2-475e-9be2-80ccef5477c8
                  relationships:
                    customer:
                      data:
                        type: customers
                        id: cd91f5cb-5c38-4f10-90cb-de2efad3ee82
                    srm_verified_asset:
                      data:
                        type: srm_verified_assets
                        id: a6cfb121-5e78-4ec4-a7ea-223900c76607
                - id: bd4f8a46-cf03-586f-acf3-91dde0cc88e0
                  type: customer_assets
                  attributes:
                    vin: 1FUJBBCK57LX12345
                    serial_number: HN991563
                    unit_number: NU2696
                    chassis_id: N-991563
                    make: Make
                    model: CH613
                    year: 2018
                    service_status: archived
                    engine:
                      make: Engine Make
                      model: X15
                      displacement: 14.8L
                      serial_number: '79412345'
                    odometer_value: 125000
                    odometer_unit: mi
                    vmrs:
                      asset_type:
                        code_key: '2'
                        code: D
                  links:
                    source_application: https://{host}/vehicles/{id}/edit
                    self: https://srm-api.decisivapps.com/api/service_management/{srm_account_id}/v1/customer_assets/bd4f8a46-cf03-586f-acf3-91dde0cc88e0
                  relationships:
                    customer:
                      data:
                        type: service_group_customers
                        id: de92a6dc-6d49-5021-a1dc-ef3fae4ef933
                    srm_verified_asset:
                      data:
                        type: srm_verified_assets
                        id: b7d0c232-6f89-5fd5-b8fb-334a11d87718
              schema:
                $ref: '#/components/schemas/customer_assets'
        '400':
          description: This response may occur when an invalid request has been provided to the server.  The request may be corrected by the consumer and resubmitted.
          content:
            application/vnd.api+json:
              examples:
                Filter not allowed:
                  value:
                    errors:
                    - title: Filter not allowed
                      detail: '''{{filter_name}}'' is not allowed. Valid filters: {{filters_list}}'
                      code: decisiv:filters:001
                      status: '400'
                      source:
                        parameter: filter[filter_name]
                Invalid filter value:
                  value:
                    errors:
                    - title: Invalid filter value
                      detail: '''{{invalid_value}}'' is not a valid value. Valid values: {{valid_values}}'
                      code: decisiv:filters:002
                      status: '400'
                      source:
                        parameter: filter[service_status:includes]
              schema:
                $ref: '#/components/schemas/errors_response'
        '401':
          description: This response may occur when the access token provided within the Authorization token has expired.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Access unauthorized
                  detail: Access unauthorized
                  code: decisiv::access_token:001
                  status: '401'
              schema:
                $ref: '#/components/schemas/errors_response'
        '403':
          description: This response may occur when the authenticated user embedded within the Authorization header does not have access to the requested resource.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Forbidden
                  detail: User does not have permission to perform this action on the requested resource(s)
                  code: decisiv:access:001
                  status: '403'
              schema:
                $ref: '#/components/schemas/errors_response'
        '404':
          description: This response may occur when the requested resource is not found.
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '404'
                  code: decisiv:resource:001
                  title: Resource not found
                  detail: The parent resource could not be found
                  source:
                    parameter: id
              schema:
                $ref: '#/components/schemas/errors_response'
        '424':
          description: This response may occur when there is an unresolved data dependency or configuration required inside of the Decisiv Platform preventing access to the requested action.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Failed Dependency
                  detail: Failed Dependency
                  code: '424'
                  status: '424'
              schema:
                $ref: '#/components/schemas/errors_response'
        '504':
          description: This response may occur when there is an unexpected system timeout.
          content:
            application/vnd.api+json:
              example:
                errors:
                - code: '504'
                  detail: Gateway timeout error
                  status: '504'
                  title: Gateway timeout error
              schema:
                $ref: '#/components/schemas/errors_response'
    post:
      summary: Create a new Customer Asset
      tags:
      - Customer Assets
      parameters:
      - name: srm_account_id
        in: path
        description: The account ID for SRM
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Creates a new Customer Asset record
          content:
            application/vnd.api+json:
              example:
                data:
                  id: aa3e7935-bfe2-475e-9be2-80ccef5477c8
                  type: customer_assets
                  attributes:
                    vin: 3B7HF13Z11M269883
                    serial_number: HN991562
                    unit_number: NU2695
                    chassis_id: N-991562
                    make: Make
                    model: CH613
                    year: 2017
                    service_status: active
                    engine:
                      make: Engine Make
                      model: X15
                      displacement: 14.8L
                      serial_number: '79412345'
                    odometer_value: 125000
                    odometer_unit: mi
                    vmrs:
                      asset_type:
                        code_key: '2'
                        code: D
                  links:
                    source_application: https://{host}/vehicles/{id}/edit
                    self: https://srm-api.decisivapps.com/api/service_management/{srm_account_id}/v1/customer_assets/aa3e7935-bfe2-475e-9be2-80ccef5477c8
                  relationships:
                    customer:
                      data:
                        type: customers
                        id: cd91f5cb-5c38-4f10-90cb-de2efad3ee82
                    srm_verified_asset:
                      data:
                        type: srm_verified_assets
                        id: a6cfb121-5e78-4ec4-a7ea-223900c76607
              schema:
                $ref: '#/components/schemas/customer_asset'
        '400':
          description: This response may occur when an invalid request has been provided to the server.  The request may be corrected by the consumer and resubmitted.
          content:
            application/vnd.api+json:
              examples:
                Filter not allowed:
                  value:
                    errors:
                    - title: Filter not allowed
                      detail: '''{{filter_name}}'' is not allowed. Valid filters: {{filters_list}}'
                      code: decisiv:filters:001
                      status: '400'
                      source:
                        parameter: filter[filter_name]
                Missing required attributes:
                  value:
                    errors:
                    - status: '400'
                      code: decisiv:request_attributes:001
                      title: Missing required attribute key
                      detail: Required key not provided in request body
                      source:
                        pointer: /data/attributes/serial_number
                    - status: '400'
                      code: decisiv:request_attributes:001
                      title: Missing required attribute key
                      detail: Required key not provided in request body
                      source:
                        pointer: /data/attributes/make
                    - status: '400'
                      code: decisiv:request_attributes:001
                      title: Missing required attribute key
                      detail: Required key not provided in request body
                      source:
                        pointer: /data/attributes/model
                    - status: '400'
                      code: decisiv:request_attributes:002
                      title: Missing required attribute value
                      detail: Required key must be populated
                      source:
                        pointer: /data/attributes/year
              schema:
                $ref: '#/components/schemas/errors_response'
        '401':
          description: This response may occur when the access token provided within the Authorization token has expired.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Access unauthorized
                  detail: Access unauthorized
                  code: decisiv::access_token:001
                  status: '401'
              schema:
                $ref: '#/components/schemas/errors_response'
        '403':
          description: This response may occur when the authenticated user embedded within the Authorization header does not have access to the requested resource.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Forbidden
                  detail: User does not have permission to perform this action on the requested resource(s)
                  code: decisiv:access:001
                  status: '403'
              schema:
                $ref: '#/components/schemas/errors_response'
        '422':
          description: Invalid vmrs.asset_type.code / Invalid vmrs.asset_type.code_key
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/errors_response'
              examples:
                Invalid vmrs.asset_type.code:
                  value:
                    errors:
                    - status: '422'
                      code: decisiv:request_attributes:010
                      title: Invalid Attribute Value
                      detail: Invalid vmrs.asset_type.code value provided - the value provided is not a valid code according to VMRS code key 2
                      source:
                        pointer: /data/attributes/vmrs/asset_type/code
                Invalid vmrs.asset_type.code_key:
                  value:
                    errors:
                    - status: '422'
                      code: decisiv:request_attributes:010
                      title: Invalid Attribute Value
                      detail: Invalid vmrs.asset_type.code_key value provided - vmrs.asset_type.code_key must be '2'
                      source:
                        pointer: /data/attributes/vmrs/asset_type/code_key
        '429':
          description: This response will often be associated as a result of an over abundance of calls by a specific Application, Account, or IP Address resulting in a required cool off period.
          content:
            application/vnd.api+json:
              example:
                errors:
                - code: '429'
                  detail: The maximum number of requests for this application has been far exceeded with the given credentials.
                  status: '429'
                  title: Too Many Requests
              schema:
                $ref: '#/components/schemas/errors_response'
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              oneOf:
              - $ref: '#/components/schemas/create_customer_asset'
              - $ref: '#/components/schemas/create_customer_asset_registered'
            examples:
              Using Local Customer:
                summary: Customer Asset using a local Customer
                description: 'Customer branch — the supplied `vmrs.asset_type.code` is written

                  onto the newly-created vehicle''s `asset_type`.

                  '
                value:
                  data:
                    type: customer_assets
                    attributes:
                      vin: 3B7HF13Z11M269883
                      serial_number: HN991562
                      unit_number: NU2695
                      chassis_id: N-991562
                      make: Make
                      model: CH613
                      year: 2017
                      vmrs:
                        asset_type:
                          code_key: '2'
                          code: R
                    relationships:
                      customer:
                        data:
                          type: customers
                          id: cd91f5cb-5c38-4f10-90cb-de2efad3ee82
              Using Registered Asset:
                summary: Customer Asset using an existing Registered Asset
                description: 'Registered-asset branch — the supplied `vmrs.asset_type.code`

                  is written onto the existing vehicle''s `asset_type` ONLY when

                  that vehicle has no value yet (silent no-op otherwise).

                  Overwriting / clearing belong on

                  `PATCH /asset_management/{srm_account_id}/v1/registered_assets/{uuid}`.

                  '
                value:
                  data:
                    type: customer_assets
                    attributes:
                      unit_number: NU2695
                      make: Make
                      year: 2017
                      vmrs:
                        asset_type:
                          code_key: '2'
                          code: R
                    relationships:
                      registered_asset:
                        data:
                          type: registered_assets
                          id: cd91f5cb-5c38-4f10-90cb-de2efad3ee82
  /service_management/{srm_account_id}/v1/customer_assets/{id}:
    get:
      summary: List details on a specific Customer Asset
      tags:
      - Customer Assets
      parameters:
      - name: srm_account_id
        in: path
        description: The account ID for SRM
        required: true
        schema:
          type: string
      - name: id
        in: path
        schema:
          type: string
          format: uuid
        description: The resource UUID
        required: true
      - name: include
        in: query
        required: false
        schema:
          type: array
          items:
            type: string
            enum:
            - customer
            - srm_verified_asset
        description: Return specified included relationships upon request
      responses:
        '200':
          description: Show details for requested Customer Asset
          content:
            application/vnd.api+json:
              example:
                data:
                  type: customer_assets
                  id: aa3e7935-bfe2-475e-9be2-80ccef5477c8
                  attributes:
                    vin: 3B7HF13Z11M269883
                    serial_number: HN991562
                    unit_number: NU2695
                    chassis_id: N-991562
                    make: Make
                    model: CH613
                    year: 2017
                    service_status: active
                    engine:
                      make: Engine Make
                      model: X15
                      displacement: 14.8L
                      serial_number: '79412345'
                    odometer_value: 125000
                    odometer_unit: mi
                    vmrs:
                      asset_type:
                        code_key: '2'
                        code: D
                  relationships:
                    customer:
                      data:
                        type: customers
                        id: cd91f5cb-5c38-4f10-90cb-de2efad3ee82
                    srm_verified_asset:
                      data:
                        type: srm_verified_assets
                        id: a6cfb121-5e78-4ec4-a7ea-223900c76607
              schema:
                $ref: '#/components/schemas/customer_asset_by_id'
        '404':
          description: This response may occur when the requested resource is not found.
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '404'
                  code: decisiv:resource:001
                  title: Resource not found
                  detail: The parent resource could not be found
                  source:
                    parameter: id
              schema:
                $ref: '#/components/schemas/errors_response'
  /service_management/{srm_account_id}/v1/customer_assets/{id}/create_case:
    post:
      summary: Create a case for the specific Customer Asset
      tags:
      - Customer Assets
      parameters:
      - name: srm_account_id
        in: path
        description: The account ID for SRM
        required: true
        schema:
          type: string
      - name: id
        in: path
        schema:
          type: string
          format: uuid
        description: The resource UUID
        required: true
      - name: X-DECISIV-IDEMPOTENCY-KEY
        in: header
        required: false
        description: 'Optional idempotency key. The first successful create_case for a given (account, key) pair is cached briefly; a repeat request with the same key replays that original response (with X-Decisiv-Idempotent-Replay: true) instead of creating a duplicate case. A concurrent request with the same in-flight key gets 409; a key longer than 128 characters gets 400.'
        schema:
          type: string
          maxLength: 128
      responses:
        '201':
          description: Creates a Case for the specified Customer Asset
          headers:
            X-Decisiv-Idempotent-Replay:
              description: Present and set to 'true' when this response was replayed from a prior request with the same X-DECISIV-IDEMPOTENCY-KEY (no new case was created).
              schema:
                type: string
                enum:
                - 'true'
          content:
            application/vnd.api+json:
              example:
                data:
                  id: 487136d2-c4d6-424c-b018-f1ed8a740c6a
                  type: cases
                  attributes:
                    reference_number: 1234
                    created_at: null
                    updated_at: null
                    service_management_service_providers_id: null
                    service_management_customer_assets_id: null
                    service_management_customers_id: null
                    complaint: CEL on
                    po_number: V2479-128
                    auth_number: DV793957
                    ro_number: U2112550
                    cause: Diagnostic check required
                    correction: Reset Diagnostics
                    asset_information: null
                    event_timestamps:
                      followup_time: '2025-10-10T13:30:41Z'
                      asset_uptime: '2025-04-10T13:00:41Z'
                      asset_downtime: '2025-04-10T10:30:41Z'
                      asset_arrived: '2025-04-10T11:30:41Z'
                      asset_checked_in: '2025-04-10T12:30:41Z'
                      estimated_time_to_repair: '2025-04-10T13:15:41Z'
                      actual_time_to_repair: '2025-04-10T13:10:41Z'
                    breakdown:
                      location: Outside Seneca Lodge
                      city: Watkins Glen
                      state: NY
                      country: US
                    repair_status: null
                    invoice: null
                    vmrs:
                      reason_for_repair:
                        code_key: '14'
                        code: '01'
                      repair_priority:
                        code_key: '16'
                        code: '1'
                      repair_site:
                        code_key: '17'
                        code: '1'
                    tag_number: case_123
                  relationships:
                    assignee:
                      data:
                        type: internal_users
                        id: 6383dc89-05b6-4572-8979-a6257f3597ec
                    driver:
                      data:
                        type: contacts
                        id: 98bf9011-6dcd-4ea8-ac60-3dc6a66f77a2
                    primary_contact:
                      data:
                        type: contacts
                        id: e3fe0737-d53c-49d1-ad35-0f5ee21c9c03
                    billing_contact:
                      data:
                        type: contacts
                        id: bbf7dec7-83b9-413a-be5e-6bb7e74b9acf
                    program_type:
                      data:
                        type: program_types
                        id: fc8b1a9f-4705-4444-b3cc-fdaa06f5defe
                    department:
                      data:
                        type: departments
                        id: SERVICE
                    shipping_customer:
                      data:
                        type: customers
                        id: fab7f731-3191-425b-a3b7-076c9ab63f14
                    billing_customer:
                      data:
                        type: customers
                        id: fab7f731-3312-67jn-a3b7-076c9ab63f14
                    customer:
                      data:
                        type: customers
                        id: 9b1f3c52-7e44-4a8d-9c2f-1d6e0a2b4c8e
              schema:
                $ref: '#/components/schemas/case'
        '400':
          description: The X-DECISIV-IDEMPOTENCY-KEY header exceeds the maximum length.
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '400'
                  code: decisiv:idempotency_key:002
                  title: Idempotency Key Length Exceeded
                  detail: X-DECISIV-IDEMPOTENCY-KEY can not exceed 128 characters
                  source:
                    header: X-DECISIV-IDEMPOTENCY-KEY
              schema:
                $ref: '#/components/schemas/errors_response_with_header'
        '401':
          description: This response may occur when the access token provided within the Authorization token has expired.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Access unauthorized
                  detail: Access unauthorized
                  code: decisiv::access_token:001
                  status: '401'
              schema:
                $ref: '#/components/schemas/errors_response_with_header'
        '403':
          description: This response may occur when the authenticated user embedded within the Authorization header does not have access to the requested resource.
          content:
            application/vnd.api+json:
              example:
                errors:
                - title: Forbidden
                  detail: User does not have permission to perform this action on the requested resource(s)
                  code: decisiv:access:001
                  status: '403'
              schema:
                $ref: '#/components/schemas/errors_response_with_header'
        '404':
          description: This response may occur when the requested resource is not found.
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '404'
                  code: decisiv:resource:001
                  title: Resource not found
                  detail: The parent resource could not be found
                  source:
                    parameter: id
              schema:
                $ref: '#/components/schemas/errors_response_with_header'
        '409':
          description: A concurrent request with the same X-DECISIV-IDEMPOTENCY-KEY is already being processed. Retry to receive the original response.
          content:
            application/vnd.api+json:
              example:
                errors:
                - status: '409'
                  code: decisiv:idempotency_key:001
                  title: Idempotency Key In Progress
                  detail: A request with this idempotency key is already being processed. Retry to receive the original response.
                  source:
                    header: X-DECISIV-IDEMPOTENCY-KEY
              schema:
                $ref: '#/components/schemas/errors_response_with_header'
        '422':
          description: Unprocessable record / Attribute can't be used error / Relationship not found / Registered Asset associated to the Customer Asset is deactivated
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/errors_response_with_header'
              examples:
                Unprocessable record:
                  value:
                    errors:
                    - code: '422'
                      detail: Validation Error
                      status: '422'
                      title: Validation Error
                Attribute can't be used error:
                  value:
                    errors:
                    - status: '422'
                      code: attribute-001
                      title: Can't be used
                      detail: /data/attributes/attribute
                Department relationship not found (unknown code or feature disabled):
                  value:
                    errors:
                    - status: '422'
                      code: decisiv:request_attributes:003
                      title: Identifier not found
                      detail: Identifier not found
                      source:
                        pointer

# --- truncated at 32 KB (108 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/decisiv/refs/heads/main/openapi/decisiv-customer-assets-api-openapi.yml