---
title: "Get work order by external ID"
method: GET
path: "/workorders/external/{externalId}"
tags: ["Work Orders"]
---

# Get work order by external ID

`GET /workorders/external/{externalId}`

## Request

- Base URL: `https://api.getmaintainx.com/v1`
- URL: `https://api.getmaintainx.com/v1/workorders/external/{externalId}`
- Auth: HTTP bearer

## Path parameters

- `externalId` string, required

## Query parameters

- `expand` string[]: To expand multiple fields: `expand=assignees&expand=asset`

## Headers

- `x-organization-id` integer

## Response `200`

Successfully retrieved workOrder's information

- object
  - `workOrder` object, required
    - `id` integer, required: Global ID of the work order
    - `sequentialId` integer, required: Organization specific ID of the work order
    - `assetId` integer, nullable
    - `attachments` object[]: List of attachments linked to the work order
      - `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
    - `categories` string[]: List of categories that identify the work order
    - `completedAt` string, date-time, nullable: Date & time at which the work order was last marked as DONE
    - `completerId` integer, nullable: ID of the user who completed the work order
    - `createdAt` string, date-time, required: Date & time at which the work order was created
    - `creatorId` integer, nullable, required: ID of the user who created the work order
    - `deletedAt` string, date-time, nullable: Date & time at which the work order was deleted
    - `description` string, nullable
    - `dueDateIsFullDay` boolean, nullable
    - `dueDate` string, date-time, nullable: Date & time at which the work order is due
    - `estimatedTime` integer, nullable: The estimated time taken in seconds to complete the work order (expand with query parameter)
    - `externalData` union: Extra data that can be attached to the work order, for example to help reference to a matching record in an external system.
      - object
      - number
      - string
    - `isParent` boolean, nullable: If this is a parent work order
    - `lastMessageSentAt` string, date-time, nullable: Date & time at which the last comment was added to the work order
    - `startDate` string, date-time, nullable: Date & time at which the work order will show up in the inbox<br />Only valid when <b>dueDate</b> is set
    - `locationId` integer, nullable: Global ID of the location assigned to the work order
    - `nextId` integer, nullable
    - `organizationId` number, required
    - `parentId` integer, nullable: The ID of the parent work order
    - `partsAvailability` 'PARTS_AVAILABLE' | 'PARTS_UNAVAILABLE' | 'PARTIAL_PARTS' | 'PARTS_AVAILABLE_BUT_OVERCOMMITTED': Computed parts availability for this work order based on current inventory levels.
    - `partStatus` 'NO_PARTS' | 'ASSIGNED' | 'RESERVED' | 'KITTED' | 'STAGED' | 'ISSUED': Part stage indicates the current readiness state of parts for this work order.
    - `previousId` integer, nullable
    - `priority` 'NONE' | 'LOW' | 'MEDIUM' | 'HIGH'
    - `recurrenceInfo` union
      - object, nullable
        - `type` 'DAILY', required
        - `automationMeterTrigger` object, nullable: Automation meter trigger configuration
          - `automationTriggerInput` object
            - `conditions` object[], required: Conditions to trigger automation
              - …
            - `meterId` integer, required: ID of the meter to trigger the automation
          - `lastTriggerValue` number: Last trigger value for the meter
          - `newDueDateOffsetSeconds` integer: Offset in seconds for new due date. If you want to set the due date to 2 days from now set this to 172800 - (24 * 60 * 60 * 2)
      - object, nullable
        - `type` 'WEEKLY', required
        - `interval` integer: Number of weeks between events
        - `days` string[], required: Days of the week the event will occur
        - `automationMeterTrigger` object, nullable: Automation meter trigger configuration
          - `automationTriggerInput` object
            - `conditions` object[], required: Conditions to trigger automation
              - …
            - `meterId` integer, required: ID of the meter to trigger the automation
          - `lastTriggerValue` number: Last trigger value for the meter
          - `newDueDateOffsetSeconds` integer: Offset in seconds for new due date. If you want to set the due date to 2 days from now set this to 172800 - (24 * 60 * 60 * 2)
      - object, nullable
        - `type` 'MONTHLY', required
        - `interval` integer: Number of months between events
        - `day` integer, required: Day of the month the event will occur
        - `automationMeterTrigger` object, nullable: Automation meter trigger configuration
          - `automationTriggerInput` object
            - `conditions` object[], required: Conditions to trigger automation
              - …
            - `meterId` integer, required: ID of the meter to trigger the automation
          - `lastTriggerValue` number: Last trigger value for the meter
          - `newDueDateOffsetSeconds` integer: Offset in seconds for new due date. If you want to set the due date to 2 days from now set this to 172800 - (24 * 60 * 60 * 2)
      - object, nullable
        - `type` 'YEARLY', required
        - `interval` integer: Number of years between events
        - `automationMeterTrigger` object, nullable: Automation meter trigger configuration
          - `automationTriggerInput` object
            - `conditions` object[], required: Conditions to trigger automation
              - …
            - `meterId` integer, required: ID of the meter to trigger the automation
          - `lastTriggerValue` number: Last trigger value for the meter
          - `newDueDateOffsetSeconds` integer: Offset in seconds for new due date. If you want to set the due date to 2 days from now set this to 172800 - (24 * 60 * 60 * 2)
      - object, nullable
        - `type` 'PERIODICALLY', required
        - `interval` integer: Number of seconds between events
        - `automationMeterTrigger` object, nullable: Automation meter trigger configuration
          - `automationTriggerInput` object
            - `conditions` object[], required: Conditions to trigger automation
              - …
            - `meterId` integer, required: ID of the meter to trigger the automation
          - `lastTriggerValue` number: Last trigger value for the meter
          - `newDueDateOffsetSeconds` integer: Offset in seconds for new due date. If you want to set the due date to 2 days from now set this to 172800 - (24 * 60 * 60 * 2)
    - `requesterId` integer, nullable: ID of the user who requested the work order through the Work Request feature
    - `status` 'OPEN' | 'IN_PROGRESS' | 'ON_HOLD' | 'DONE' | 'CANCELED' | 'SKIPPED', required: <br /><em>Note:</em> It is also possible to register a webhook to get notified when the status of any work order changes. Please see the <a href="#tag/Subscriptions">Subscriptions</a> section for more information.
    - `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
    - `title` string, required
    - `type` 'CYCLE_COUNT' | 'OTHER' | 'PREVENTIVE' | 'REACTIVE', nullable: Valid types of Work Orders, including options that are not available for creation/update. Historical Work Orders may have a null type.
    - `updatedAt` string, date-time, required: Date & time at which the work order was last updated. This doesn't include comments
    - `extraFields` object: Custom Fields on the entity. The object keys are the exact Custom Field labels, including spaces or special characters. (ie: "Estimated Budget") (expand with query parameter)
    - `vendorIds` number[]: Vendor IDs
    - `assigneeIds` integer[]: List of user ids assigned to the work order
    - `teamIds` integer[]: List of team ids assigned to the work order
    - `customerId` integer, nullable: ID of the customer linked to the work order
    - `procedure` object, nullable: Procedure attached to the work order
      - `id` number: ID representing a procedure
      - `templateIds` number[], nullable: IDs of the procedure template of the procedure
      - `title` string, required: Title of the procedure
      - `maxScore` number: Maximum score of a procedure
      - `score` number: Score of a procedure
      - `fields` object[], required
        - `id` number, required: ID of the procedure field
        - `parentId` number, nullable: ID of the parent of the current procedure field
        - `procedureTemplateId` number, nullable: ID of the procedure template this field originated from.
        - `procedureTemplateFieldId` number, nullable: ID of the procedure template field this field originated from.
        - `required` boolean, required: Indicate if field is required to be filled.
        - `description` string, nullable: Description of the procedure field
        - `type` 'NUMBER' | 'AMOUNT' | 'TEXT' | 'UNSUPPORTED' | 'HEADING' | 'FILE' | 'SIGNATURE' | 'MULTIPLE_CHOICE' | 'INSPECTION_CHECK' | 'YES_NO_NA' | 'CHECKBOX' | 'CHECKLIST' | 'METER' | 'DATE' | 'CYCLE_COUNT', required: Type of procedure field
        - `label` string, required: Label of a procedure field
        - `maxScore` number: Maximum score of a procedure field
        - `score` number: Score of a procedure field
        - `value` object, required: Current value of a procedure field
          - `text` string, nullable
          - `attachment` object
            - `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[]
            - `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
          - `notes` object, nullable: Note added to a procedure field
            - `text` string
          - `hasAttachments` boolean, nullable
        - `meter` object, nullable: Meter of a procedure field. Will be filled if the type of the field is meter
          - `id` number: Global ID of the meter.
          - `name` string: Name of the meters
        - `assignees` object, nullable
          - `userIds` number[]
          - `teamIds` number[]
        - `isDateAndTime` boolean, nullable: Indicate if a DATE field also contains the time
    - `externalId` string, nullable: External ID for this work order, unique per organization.
    - `progress` object, nullable: Progress information on the work order
      - `openCount` number
      - `inProgressCount` number
      - `onHoldCount` number
      - `doneCount` number
    - `workOrderSummary` object, nullable: Work Order Summary. Null when no summary is available.
      - `content` string: The original completion note content
      - `summary` string, nullable: AI-generated summary of the content
      - `authorId` integer, nullable: ID of the user who authored the completion note
    - `assignees` object[]: Either the teamId, the userId or the user email address (expand with query parameter)
      - `type` 'USER' | 'TEAM', required
      - `id` union, required
        - integer
        - string
    - `asset` object, nullable: Asset linked to the element (expand with query parameter)
      - `id` integer, required: Global ID of the asset
      - `name` string, required
      - `description` string, nullable, required
      - `parentId` integer, nullable, required: ID of the parent asset
      - `criticalityId` integer, nullable, required: ID of the criticality of the asset
      - `locationId` integer, nullable, required: ID of the location where the asset is located
      - `serialNumber` string, nullable, required: Serial number of the asset
      - `createdAt` string, date-time, required: Date & time at which the asset was created
      - `updatedAt` string, date-time, required: Date & time at which the asset was last updated. This doesn't include comments
      - `creatorId` integer, nullable, required: ID of the asset creator
      - `assetExtraFields` object: Asset-level custom field values. Present (possibly an empty object) when `asset_extra_fields` is requested and the parent Asset is present. Requesting this implicitly enables `asset` if not already requested.
    - `location` object, nullable: Location linked to the element (expand with query parameter)
      - `id` integer, required: Global ID of the location
      - `name` string, required
      - `description` string, nullable
      - `address` string, nullable: Postal address of the location
      - `parentId` integer, nullable: ID of the parent location
      - `createdAt` string, date-time: Date & time at which the location was created
      - `updatedAt` string, date-time: Date & time at which the location was last updated. This doesn't include comments
      - `locationExtraFields` object: Location-level custom field values. Present (possibly an empty object) when `location_extra_fields` is requested and the parent Location is present. Requesting this implicitly enables `location` if not already requested.
    - `parts` object[]: Parts attached to the Work Order (expand with query parameter)
      - `id` integer, required: Global ID of the part
      - `name` string, required
      - `description` string, nullable, required
      - `area` string, nullable, required
      - `unitCost` integer, nullable, required: Cost in cents. For example, for $1.20, put 120.
      - `availableQuantity` integer, required: Quantity currently in stock
      - `minimumQuantity` integer, required: Minimum quantity before you should restock
      - `barcode` string, nullable, required: String encoded barcode
      - `quantityUsed` integer, required: Quantity used in the work order.
      - `copyOnRecurring` 'NoCopy' | 'Copy' | 'Default', required: Indicates if the parts will be copied to the next work order in the chain (if applicable).
      - `locationId` number, nullable: Global ID of the location of the part
      - `extraFields` object: Work Order-scoped custom fields for this Part on this specific Work Order. These are distinct from Part-level custom fields (see `partExtraFields`).
      - `partExtraFields` object: Part-level custom fields defined on the Part itself (not specific to this Work Order). Present (possibly an empty object) when `part_extra_fields` is requested and Parts are present. Requesting this implicitly enables `parts` if not already requested.
    - `times` object[]: Time entries on the Work Order. Grouped by users (expand with query parameter)
      - `type` 'EXPENSE' | 'PART' | 'TIME': Type of the entry
      - `costPerUnit` number, nullable: Cost per part in cents or cents per hour
      - `description` string, nullable: Description of the expense or part description
      - `quantity` number: Number of parts or number of hours
      - `rowTotal` number: Total cost in cents
      - `durationTotal` number: Total duration in seconds
      - `userId` integer, nullable: ID of the user who logged the time entry
      - `partId` integer, nullable: ID of the part used in this cost entry
    - `timeItems` object[]: Time entries on the Work Order. (expand with query parameter)
      - `type` 'EXPENSE' | 'PART' | 'TIME': Type of the entry
      - `costPerUnit` number, nullable: Cost per part in cents or cents per hour
      - `description` string, nullable: Description of the expense or part description
      - `quantity` number: Number of parts or number of hours
      - `rowTotal` number: Total cost in cents
      - `durationTotal` number: Total duration in seconds
      - `userId` integer, nullable: ID of the user who logged the time entry
      - `partId` integer, nullable: ID of the part used in this cost entry
    - `expenditures` object[]: Other cost entries on the Work Order. Grouped by users (expand with query parameter)
      - `type` 'EXPENSE' | 'PART' | 'TIME': Type of the entry
      - `costPerUnit` number, nullable: Cost per part in cents or cents per hour
      - `description` string, nullable: Description of the expense or part description
      - `quantity` number: Number of parts or number of hours
      - `rowTotal` number: Total cost in cents
      - `durationTotal` number: Total duration in seconds
      - `userId` integer, nullable: ID of the user who logged the time entry
      - `partId` integer, nullable: ID of the part used in this cost entry

## Other responses

- `400`: Error with query
- `401`: Invalid token
- `404`: Could not find the specified workOrder or the user cannot access it.

## Changes

> 30 revisions in range; 1 not diffed.

- **2026-09-14** `bf9ccb1af927`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/getmaintainx/apis/maintainx-api/changes/workorders/external/:externalId/get.md)

---

[API](https://skmtc.dev/getmaintainx/apis/maintainx-api.md) - [All operations](https://skmtc.dev/getmaintainx/apis/maintainx-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getmaintainx/apis/maintainx-api/revisions/6258367c04ff?raw)