API Documentation

List Entities

GET /api/v1/entities

Get a paginated list of entities (organizations) with optional filtering by type and search. Includes both public sector organizations and private companies involved in the decentralized identity ecosystem.

Request

Query Parameters

Parameter Type Required Default Description
page integer No 1 Page number (1-indexed)
per_page integer No 20 Number of results per page (1-100)
q string No - Search query for entity names or trade names
type string No - Filter by entity type: "Public" or "Private"

Example Requests

bash 
# Get first page of entities
curl -X GET "https://www.weboftrust.org/api/v1/entities" \
  -H "X-API-Key: YOUR_API_KEY"

# Search for entities containing "microsoft"
curl -X GET "https://www.weboftrust.org/api/v1/entities?q=microsoft" \
  -H "X-API-Key: YOUR_API_KEY"

# Get only public sector entities
curl -X GET "https://www.weboftrust.org/api/v1/entities?type=Public&per_page=50" \
  -H "X-API-Key: YOUR_API_KEY"

# Get page 5 with 100 results per page
curl -X GET "https://www.weboftrust.org/api/v1/entities?page=5&per_page=100" \
  -H "X-API-Key: YOUR_API_KEY"

Response

Success Response (200 OK)

Response Headers

Header Value Description
X-License CC-BY-4.0 License identifier
X-Attribution Web of Trust Map - Key State Capital Required attribution
Cache-Control public, max-age=30, s-maxage=120, stale-while-revalidate=600 Caching directives

Response Schema

typescript 
interface EntityListResponse {
  data: EntitySummary[];
  pagination: {
    page: number;       // Current page (1-indexed)
    per_page: number;   // Items per page
    total: number;      // Total number of entities
    total_pages: number; // Total number of pages
  };
}

interface EntitySummary {
  id: number;
  name: string;
  trade_name?: string;
  type: string[];  // ["Public"] or ["Private"]
  lei?: string;    // Legal Entity Identifier
  website?: string;
  logo_url?: string;  // Full URL to entity logo
  address?: string;
  country?: {
    id: number;
    name: string;
    code: string;  // ISO 3166-1 alpha-2 code
  };
  coordinates?: {
    latitude: number;
    longitude: number;
  };
  stats: {
    total_links: number;  // Total number of relationships
  };
}

Example Response

json 
{
  "data": [
    {
      "id": 649,
      "name": "European Commission",
      "trade_name": "European Commission",
      "type": ["Public"],
      "lei": "254900ZNYA1FLUQ9U393",
      "website": "https://commission.europa.eu/index_en",
      "logo_url": "https://weboftrust.org/icons/commission.europa.eu.webp",
      "address": "Rue Belliard 28 (Secondary entrance : Rue de l'Industrie 21), 1000 Bruxelles / Brussel, Belgium",
      "country": {
        "id": 17,
        "name": "Belgium",
        "code": "BE"
      },
      "coordinates": {
        "latitude": 50.8422911,
        "longitude": 4.3703692
      },
      "stats": {
        "total_links": 122
      }
    },
    {
      "id": 3,
      "name": "Microsoft Corporation",
      "trade_name": "Microsoft Corporation (Microsoft)",
      "type": ["Private"],
      "lei": "INR2EJN1ERAN0W5ZP974",
      "website": "https://www.microsoft.com",
      "logo_url": "https://weboftrust.org/icons-overwrite/microsoft.com.webp",
      "address": "One Microsoft Way, Redmond, WA 98052, United States",
      "country": {
        "id": 197,
        "name": "United States of America",
        "code": "US"
      },
      "coordinates": {
        "latitude": 47.6435274501991,
        "longitude": -122.130607282319
      },
      "stats": {
        "total_links": 44
      }
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 2,
    "total": 5545,
    "total_pages": 2773
  }
}

Error Responses

400 Bad Request

Invalid query parameters

json 
{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid page parameter"
  }
}

500 Internal Server Error

json 
{
  "error": {
    "code": "internal_error",
    "message": "Failed to fetch entities"
  }
}

Field Descriptions

  • type: Entity classification
    • Public - Government agencies, public institutions, regulatory bodies
    • Private - Companies, corporations, private organizations
  • lei: Legal Entity Identifier - a unique 20-character alphanumeric code for legal entities
  • trade_name: Alternative or commonly used name for the entity
  • logo_url: Automatically derived from website domain, cached and optimized
  • stats.total_links: Number of connections to projects, standards, regulations, etc.

Entity Types

Public Entities

  • Government agencies
  • Regulatory bodies
  • International organizations
  • Research institutions
  • Standards organizations

Private Entities

  • Technology companies
  • Consulting firms
  • Identity solution providers
  • Blockchain companies
  • Financial institutions

Pagination

  • Default page size is 20 items
  • Maximum page size is 100 items
  • Pages are 1-indexed (first page is page=1)
  • Total count includes all matching entities (considering filters)