Skip to main content
GET
/
v1
/
organizations
/
byOrganizationName
Get Organization by Name
curl --request GET \
  --url https://api.shoal.xyz/v1/organizations/byOrganizationName \
  --header 'Authorization: Bearer <token>'
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

cURL
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. 
{
  "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