# Entity References

Source: https://docs.havilo.ai/reference/ai-engine/entity-refs

Entity-scoped runs need an entity reference. The most reliable reference is a resolved entity UUID.

## Reference Shapes

```json
{ "id": "550e8400-e29b-41d4-a716-446655440002" }
```

```json
{ "external_uri": "vault:company/example" }
```

```json
{ "external_id": "example", "source": "custom" }
```

Supported `source` values are `vault`, `linkedin`, `crunchbase`, and `custom`.

## Resolve Entities

Use `GET /entities/resolve` before creating a preset run when you are not sure a reference exists in the workspace.

```bash
curl "https://havilo.ai/api/v1/entities/resolve?refs=%5B%7B%22id%22%3A%22550e8400-e29b-41d4-a716-446655440002%22%7D%5D" \
  -H "Authorization: Bearer $HAVILO_API_KEY"
```

```json
{
  "results": [
    {
      "ref": {
        "id": "550e8400-e29b-41d4-a716-446655440002"
      },
      "resolved": true,
      "entity_id": "550e8400-e29b-41d4-a716-446655440002",
      "entity_name": "Example Company",
      "entity_type": "Company"
    }
  ]
}
```

Unresolved references return a per-result error:

```json
{
  "results": [
    {
      "ref": {
        "external_uri": "custom:missing"
      },
      "resolved": false,
      "error": {
        "code": "entity_not_resolvable",
        "message": "No entity matching the reference could be found in this workspace."
      }
    }
  ]
}
```

For dossier runs, pass the resolved UUID form:

```json
{
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440002"
  }
}
```