> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shoal.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Organization by Name

> Resolve an organization by canonical name or alias

Looks up organizations by name and returns canonical matches. This route remains available for compatibility, but new integrations should prefer `/v1/entities/byName`.

Use this when you have a human-readable name like `Ethereum` or `Coinbase` and need a stable id for older organization-scoped routes.

## Query Parameters

* `name` (string, required)
* `organizationName` (string, optional) — Compatibility alias for `name`

### Request

```bash cURL theme={null}
curl -X GET "https://api.shoal.xyz/v1/organizations/byOrganizationName?name=Ethereum" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Response

Returns an array of canonical organization matches in `data`. Search uses case-insensitive partial matching.

```json theme={null}
{
  "data": [
    {
      "id": 23151,
      "label": "Ethereum",
      "type": "project",
      "aliases": ["Ethereum Foundation", "ETH"],
      "matchedVia": "canonical_name",
      "matchType": "exact",
      "matchRank": 0,
      "matchedValue": "Ethereum"
    }
  ]
}
```

`type` is the canonical entity type for the matched organization. Current live organization responses use `project` for protocol-style entities and may expand as more canonical entity types are exposed.

`aliases` returns a small canonical alias preview so consumers can confirm they selected the correct entity before creating recurring monitoring workflows.

`matchedVia`, `matchType`, `matchRank`, and `matchedValue` describe why a given canonical entity was returned and how strongly it matched the query. Lower `matchRank` values are stronger.

For new entity-first workflows, use `/v1/entities/byName` and then traverse the semantic layer from the returned Shoal entity id.

### Errors

* 400 if `name` missing
* 500 on internal server error