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>'

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.

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