---
title: "Create or update asset by external ID"
method: PATCH
path: "/assets/external/{externalId}"
tags: ["Assets"]
---

# Create or update asset by external ID

`PATCH /assets/external/{externalId}`

Idempotent upsert keyed on the external ID in the path. If an asset has this external ID, it will be updated (and undeleted, if the asset was previously deleted). Otherwise, a new asset will be created with this external ID.

## Path parameters

- `externalId` string, required

## Query parameters

- `skipWebhook` boolean

## Headers

- `x-organization-id` integer

## Request body

- object
  - `name` string
  - `description` string, nullable
  - `barcode` string, nullable — String encoded barcode
  - `criticalityId` integer, nullable — ID of the criticality of the asset
  - `parentId` integer, nullable — ID of the parent asset
  - `locationId` integer, nullable — ID of the location where the asset is located
  - `teamIds` integer[] — List of teams responsible for the asset
  - `assetTypes` string[] — List of asset types
  - `extraFields` object — Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "My Custom Field")
  - `vendorIds` number[] — Vendor IDs
  - `serialNumber` string, nullable — Serial number of the asset
  - `depreciation` object, nullable — Depreciation information of the asset
    - `id` number — Global ID of the asset depreciation.
    - `accumulatedDepreciation` number, nullable — Accumulated depreciation of the asset.
    - `annualDepreciation` number, nullable — Annual depreciation of the asset.
    - `depreciationStartDate` string, date-time, nullable — Date at which the asset depreciation started.
    - `currentBookValue` number, nullable — Current book value of the asset.
    - `purchasePrice` number, nullable — Purchase price of the asset.
    - `purchaseDate` string, date-time, nullable — Date & time at which the asset was purchased.
    - `salvageValue` number, nullable — Salvage value of the asset.
    - `usefulLifeYears` number, nullable — Useful life of the asset in years.
    - `yearsDepreciated` number, nullable — Years depreciated of the asset.
    - `createdAt` string, date-time, nullable — Date & time at which the asset depreciation was created.
    - `archivedAt` string, date-time, nullable — Date & time at which the asset depreciation was archived.
  - `manufacturer` object, nullable — Manufacturer information for the asset. Set to null to clear manufacturer and model.
    - `id` integer, nullable — ID of an existing manufacturer. If provided, the manufacturer must be either global or belong to your organization. If not provided, the manufacturer will be looked up by name.
    - `name` string, nullable — Name of the manufacturer. Required if id is not provided. When searching by name, the manufacturer must be either global or belong to your organization.
  - `model` object, nullable — Model information for the asset. Set to null to clear model.
    - `id` integer, nullable — ID of an existing model. If provided, the model must be linked to the specified manufacturer and be either global or belong to your organization. If not provided, the model will be looked up by name.
    - `name` string, nullable — Name of the model. Required if id is not provided. When searching by name, the model must be linked to the specified manufacturer and be either global or belong to your organization.

## Response `200`

Successfully updated asset

- object
  - `asset` object, required
    - `id` integer, required — Global ID of the asset
    - `name` string, required
    - `globalUuid` string, nullable — Global unique identifier of the asset used to identify assets as they are being transferred
    - `currentOwnerId` number — Organization id that currently has the active version of this asset
    - `barcode` string, nullable — String encoded barcode
    - `description` string, nullable
    - `criticalityId` integer, nullable — ID of the criticality of the asset
    - `teamIds` integer[] — List of teams responsible for the asset
    - `assetTypes` string[] — List of asset types
    - `parentId` integer, nullable — ID of the parent asset
    - `childrenIds` number[], nullable — IDs of the asset's children
    - `locationId` integer, nullable — ID of the location where the asset is located
    - `serialNumber` string, nullable — Serial number of the asset
    - `thumbnail` object, nullable
      - `id` number, required — Global ID of the attachment
      - `mimeType` string, required — MIME type of the file
      - `fileName` string, required — Attachment's file name
      - `url` string, required — Url of the file. Valid for 60 minutes.
      - `createdAt` string, date-time, required — Date & time at which the attachment was uploaded
      - `width` number, nullable — Width if the file is an image
      - `height` number, nullable — Height if the file is an image
    - `attachments` object[] — List of attachments linked to the asset
      - `id` number, required — Global ID of the attachment
      - `mimeType` string, required — MIME type of the file
      - `fileName` string, required — Attachment's file name
      - `url` string, required — Url of the file. Valid for 60 minutes.
      - `createdAt` string, date-time, required — Date & time at which the attachment was uploaded
      - `width` number, nullable — Width if the file is an image
      - `height` number, nullable — Height if the file is an image
    - `extraFields` object — Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "My Custom Field")
    - `vendorIds` number[] — Vendor IDs
    - `createdAt` string, date-time — Date & time at which the asset was created
    - `updatedAt` string, date-time — Date & time at which the asset was last updated. This doesn't include comments
    - `deletedAt` string, date-time, nullable — Date at which the asset was deleted
    - `creatorId` integer, nullable — ID of the asset creator
    - `depreciation` object, nullable — Depreciation information of the asset
      - `id` number — Global ID of the asset depreciation.
      - `accumulatedDepreciation` number, nullable — Accumulated depreciation of the asset.
      - `annualDepreciation` number, nullable — Annual depreciation of the asset.
      - `depreciationStartDate` string, date-time, nullable — Date at which the asset depreciation started.
      - `currentBookValue` number, nullable — Current book value of the asset.
      - `purchasePrice` number, nullable — Purchase price of the asset.
      - `purchaseDate` string, date-time, nullable — Date & time at which the asset was purchased.
      - `salvageValue` number, nullable — Salvage value of the asset.
      - `usefulLifeYears` number, nullable — Useful life of the asset in years.
      - `yearsDepreciated` number, nullable — Years depreciated of the asset.
      - `createdAt` string, date-time, nullable — Date & time at which the asset depreciation was created.
      - `archivedAt` string, date-time, nullable — Date & time at which the asset depreciation was archived.
    - `manufacturer` string, nullable — Name of the manufacturer of the asset
    - `model` string, nullable — Name of the model of the asset
    - `externalId` string, nullable — External ID for this asset, unique per organization.

## Other responses

- `201` — Successfully created asset
- `400` — OrganizationId was not provided
- `401` — Invalid token
- `404` — Could not find the specified asset.
- `409` — Conflict with existing asset

---

[API](https://skmtc.net/getmaintainx/apis/maintainx-api.md) · [All operations](https://skmtc.net/getmaintainx/apis/maintainx-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/getmaintainx/maintainx-api/revisions/ef9153fcac7c/schema)