Entity Resolution

Turn familiar business wording into an authorized ShelfCycle ID before reading detail, running a report, or preparing a write.

Use Entity Resolution when the workflow knows the kind of record it needs but the source text may contain a name, code, alias, family, location, or combined description rather than an exact ID.

Endpoint

GET /entity-resolution

Required scope:

search:read

The acting user must also have current access to the selected class. GET /me reports the available classes in effectiveCapabilities.entityResolution.viewableClasses.

When the key also has tags:read and the acting user has Tags access, results can include relatedTags for the requested class.

Choose a class

Both query parameters are required:

Parameter	Meaning
`q`	The wording to match, from 1 to 200 characters and containing at least one letter or number.
`class`	`customer`, `supplier`, `product`, `product_family`, `sales_order`, or `purchase_order`.

curl "$SHELFCYCLE_API_BASE_URL/entity-resolution?q=Isopropyl%20Alcohol%2099&class=product" \
  -H "Authorization: Bearer $SHELFCYCLE_API_KEY" \
  -H "X-ShelfCycle-Client: Quote intake"

Read the result

{
  "data": {
    "classesSearched": ["product"],
    "classResults": [
      { "matchedClass": "product", "totalMatches": 1 }
    ],
    "candidates": [
      {
        "entityId": "product-id",
        "displayName": "IPA-DRUM · Isopropyl Alcohol 99%",
        "matchedClass": "product",
        "matchRank": "contains",
        "matchBasis": "family",
        "matchedValue": "Isopropyl Alcohol 99%",
        "productCodes": ["IPA-DRUM"]
      }
    ],
    "relatedTags": [
      {
        "label": "Sustainable Solvents",
        "description": "Products in the sustainable solvents collection",
        "matchedClasses": ["product", "product_family"]
      }
    ],
    "archivedRecordsExcluded": true,
    "selectionStatus": "auto_selected",
    "selectedCandidate": {
      "entityId": "product-id",
      "matchedClass": "product"
    }
  },
  "meta": {
    "capabilityKey": "resolve_entity",
    "capabilityVersion": "1.1.0"
  }
}

Every candidate explains the match through matchRank, matchBasis, and matchedValue. Use selectionStatus to choose the next step:

Status	Next step
`auto_selected`	Use `selectedCandidate.entityId` with the endpoint for `selectedCandidate.matchedClass`.
`needs_clarification`	Use the candidate names and match evidence to ask for or apply a narrower choice.
`no_match`	Keep the source wording unresolved rather than guessing an ID.

All three outcomes return HTTP 200. Authentication, scope, permission, and request-shape errors use the standard typed error envelope.

When present, relatedTags provides tag labels, descriptions, and the classes they matched. Use the Tags guide to browse the full vocabulary or page every authorized record carrying one of those exact tags.

Product family matches

A product request can select a product family when the wording identifies the family more clearly than one product. Always branch on selectedCandidate.matchedClass before using the returned ID.

Choose the right lookup

Use GET /entity-resolution to bind wording to one authorized customer, supplier, product, product family, sales order, or purchase order ID.
Use GET /tags and GET /tagged-records when the workflow starts from an exact organization tag.
Use GET /product-directory when the workflow starts from a regulatory product identifier or name and may need several matching products or families.
Existing connections can continue using GET /search to explore related records across several types, including contacts and locations.
Use a root finder such as GET /products or GET /orders when the workflow already has exact filters and may need several rows or continuation.

Once an ID is selected, fetch the exact detail or use it with the relevant report or readiness check.