External Identifiers

When a MaintainX® entity is created, it's assigned an internal ID, called an MX ID. External systems—e.g., enterprise resource planning (ERP) software, integration platform as a service (iPaaS) platforms, or custom tooling—typically have their own stable identifiers for the same records, and can't easily store or look up MX IDs.

External identifier (externalId) fields solve this problem by letting you attach your own identifier to any supported entity, and use it in API calls without first resolving it to an MX ID.

note

If you use external identifiers, your organization Administrator can make them visible in the MaintainX web application interface, where they appear in entity detail pages.

Why Use External Identifiers

If you only use MX IDs, writing a single record from an external system to MaintainX requires multiple steps:

1. Search for the entity using the appropriate API endpoint.
2. Decide whether to create or update based on the result.
3. If updating, pull the MX ID from the search result.
4. Execute the correct call (POST or PATCH) using the MX ID.

This pattern creates complex orchestration logic in iPaaS tools, and creates duplicate records when a lookup fails or is skipped.

When you use external identifiers, you can write a record in a single step regardless of whether it already exists in MaintainX. Your system sets the identifier and MaintainX handles the create or update logic.

Example: Sending Parts Data from SAP to MaintainX

Let's say a manufacturing company uses SAP as their master data system for parts. To send new or updated parts to MaintainX, logic needs to be built into the integration layer to search MaintainX for the matching record, then use the MX ID to write the update. If the part exists, but the lookup fails, a duplicate can be created.

If the integration uses externalId fields instead, the SAP part number is stored in the MaintainX Part record. The integration can send a single upsert call using the SAP ID. If the part exists, it's updated. If it doesn't, it's created. No lookup is required, and there's no risk of creating duplicate records.

Supported Entities

The following entity types support externalId fields:

• Parts

Working With External Identifiers

Set an External Identifier

You can assign an externalId when you create an entity, or add one to an existing entity by its MX ID.

Creating for a new entity:

POST /v1/parts
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Hydraulic filter",
  "externalId": "ERP-PART-00412"
}

Adding to an existing entity by MX ID:

PATCH /v1/parts/{mxId}
Authorization: Bearer {token}
Content-Type: application/json

{
  "externalId": "ERP-PART-00412"
}

Remove an External Identifier

To clear an external identifier, set it to null:

PATCH /v1/parts/{mxId}
Authorization: Bearer {token}
Content-Type: application/json

{
  "externalId": null
}

Upsert by External Identifier

A common use for external identifiers is the upsert operation. MaintainX provides separate routes for upsert operations.

PATCH /v1/{entityType}/external/{externalId}

Send the externalId value as a path parameter (not in the request body) and MaintainX determines whether to create or update the record.

For example:

PATCH /v1/parts/external/ERP-PART-00412
Authorization: Bearer {token}
Content-Type: application/json

{
  "name": "Hydraulic filter",
  "unitCost": 24.99
}

• If an entity with a matching externalId exists, MaintainX updates it with the provided fields.

• If no entity with a matching externalId exists, MaintainX creates a new entity with the externalId set.

  The request body must contain all fields required to create the entity. If it doesn't, the API returns a 400 Bad Request error.

• If an archived entity with a matching externalId exists, MaintainX unarchives and updates it instead of returning a conflict error.

Fetch an Entity by External Identifier

You can retrieve an entity directly using its externalId:

GET /v1/parts/external/{externalId}
Authorization: Bearer {token}

Returns the full entity object if found, or 404 Not Found if no entity with that externalId exists in the organization.

Delete an Entity by External Identifier

You can delete an entity directly using its externalId:

DELETE /v1/parts/external/{externalId}
Authorization: Bearer {token}

Deletes the entity using the same behavior as delete-by-MX-ID. Returns 404 Not Found if no entity with that externalId exists.

External Identifiers in List Responses

The externalId field is always included in list responses for supported entity types.

externalId: "<external id>"

If an entity doesn't have an externalId assigned, the field is included with a null value.

externalId: null

External Identifiers in Webhooks

Webhook payloads for supported entity types include an <entity>ExternalId field at the webhook root, along with other standard fields like <entity>Id, orgId, occurredAt, etc. The <entity> prefix is the entity type. For example, the payload for a parts webhook includes a partId field and a partExternalId field.

{
  "partId": 123,
  "partExternalId": "ext-part-001",
  "orgId": 345,
  "occurredAt": "<date>",
  ... (other fields, depending on the webhook)
}

Limitations

External identifiers have the following limitations.

Uniqueness

External identifiers must be unique within organizations and entity types.

• Two parts in the same organization can't have the same externalId.
• A part and a work order in the same organization can have the same externalId.

If you try to assign an externalId that's already assigned to another entity of the same type in the same organization, MaintainX returns a 409 Conflict error.

{
  "error": "Part with externalId 'EXT-001' already exists in this organization.",
  "conflictingMxId": 123,
  "isDeleted": false
}

The conflictingMxId field shows the MX ID of the entity that has the identifier you're trying to assign.

One External Identifier Per Entity

An entity can only have one externalId. You can't, for example, assign multiple external identifiers from different systems to the same entity.

System Attribution

The externalId field only stores the ID value. It doesn't track which external system set the value or when.

API-Only Editing

You can only set or change the externalId via the REST API. Your organization administrator can make it visible in the MaintainX web application, but it will be read-only.

Error Reference

Status	Cause
400 Bad Request	Required fields are missing or invalid
404 Not Found	No entity with the specified externalId exists in this organization
409 Conflict	An entity of the same type already holds the specified externalId in this organization, or an entity with this externalId was archived after being transferred to another organization and cannot be unarchived.