# Entity Resolution

Match familiar business wording to an authorized ShelfCycle ID.

Canonical HTML: https://developer.shelfcycle.com/guides/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

```text
GET /entity-resolution
```

Required scope:

```text
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`. |

```bash
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

```json
{
  "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](/guides/tags) 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.