External References

Attach your own ids to Shop Commander records and look records up by them — private to your integration.

Most integrations already have an id for the customer, vehicle, or work order on their side. Rather than keeping a mapping table, attach it to the record:

curl -X PUT https://api.shopcommander.com/v1/vehicles/veh_…/external-id \
  -H "Authorization: Bearer $SC_API_KEY" -H "Content-Type: application/json" \
  -d '{"external_id":"FLEET-UNIT-0417"}'

Then:

• the vehicle's external_id field carries "FLEET-UNIT-0417" on every read,
• and GET /v1/vehicles?external_id=FLEET-UNIT-0417 finds it (customers support the same filter).

Requires the external_refs.write scope. PUT …/external-id is available on customers, vehicles, repair orders, and tasks; DELETE …/external-id removes the reference.

Rules

• One external id per record per integration, and one record per external id: assigning an id already used by another record of the same type returns 409 conflict / external_id_in_use.
• References are private to the integration that set them. Another integration sees external_id: null and can set its own.
• Ids are strings of 1–255 characters.
• DELETE /v1/{resource}/{id}/external-id removes one; PUT with a new value replaces it.

Pattern: upsert by external id

GET /v1/customers?external_id=CRM-88213
  → found: PATCH it (with expected_version)
  → empty:  POST /v1/customers (Idempotency-Key: CRM-88213), then PUT …/external-id

The idempotency key makes the create safe to retry, and the reference makes every later sync a lookup rather than a search.