Guides
sportal365.com

Custom entities API

Suggest Edits

Custom Entities API Documentation

Overview

The Custom Entities API allows frontend applications to access custom entity data (persons, organizations, places, roles, domains) through the Content API. This interface leverages existing authentication mechanisms and caching while providing a consistent way to query custom entities data.

Base URLs

  • Production: https://content.api.sportal365.com
  • Sandbox: https://content.api.sandbox.sportal365.com

Authentication

All requests require:

  • Authorization header with a valid token
  • Project header specifying the tenant identifier
// Example headers
const headers = {
  'Authorization': 'Bearer YOUR_TOKEN',
  'Project': 'your-project-identifier'
};

Note: Access to custom entities endpoints requires the read_customentities ability, which is included in read-only tokens.

Endpoints

1. Get Single Entity

Retrieve detailed information about a specific custom entity.

GET /custom-entities/{entityType}/{idOrSlug}

Supported Entity Types:

  • person
  • organization
  • place
  • role
  • domain

Parameters:

  • entityType (path): Type of the entity to retrieve
  • idOrSlug (path): ID or slug of the entity

Example Request:

fetch('https://content.api.sandbox.sportal365.com/custom-entities/person/john-doe-123', {
  headers: headers
})
.then(response => response.json())
.then(data => console.log(data));

2. List Available Domains

Retrieve the list of available custom entity domains.

GET /custom-entities/domains

Query Parameters:

  • translation_language (optional): Language code for domain translations

Example Request:

fetch('https://content.api.sandbox.sportal365.com/custom-entities/domains?translation_language=en', {
  headers: headers
})
.then(response => response.json())
.then(data => console.log(data));

3. Search Entities by Type

Search for entities of a specific type with various filtering options.

GET /custom-entities/{entityType}

Supported Entity Types:

  • person
  • organization
  • place
  • role

Query Parameters:

  • translation_language (optional): Language code for entity translations
  • domain (optional): Filter entities by domain
  • offset (optional): Pagination offset
  • limit (optional): Maximum number of results to return
  • query (optional): Search query string

Example Request:

fetch('https://content.api.sandbox.sportal365.com/custom-entities/person?domain=politics&limit=10&offset=0&query=john', {
  headers: headers
})
.then(response => response.json())
.then(data => console.log(data));

Caching

Responses include HTTP cache headers:

  • Cache-Control: public
  • max-age: 60 (60 seconds)

Custom Entity Object Types

The Custom Entities API supports several entity types, each with its own structure and relationships. Below are detailed explanations and examples for each entity type.

Domain

Domains are the top-level custom entities in the API. They represent broad categories under which other entities are organized.

Examples include: Sport, Politics, Entertainment, Technology, Business

Example Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_type": "domain",
  "name": "Politics",
  "short_name": "politics",
  "three_letter_code": null,
  "display_asset": {
    "url": "https://example.com/politics-banner.jpg"
  },
  "icon": {
    "url": "https://example.com/politics-icon.png"
  },
  "translations": [
    {
      "language": "en",
      "name": "Politics",
      "short_name": "politics",
      "three_letter_code": null
    }
  ],
  "slug": "politics",
  "custom_order": null,
  "default_language": "en"
}

Place

Places represent geographical locations. A place can optionally have a parent place where it is contained (e.g., a city within a country).

Example Response:

{
  "id": "7be6efac-8942-4263-b524-0a39e0f322dd",
  "entity_type": "place",
  "name": "Sofia",
  "short_name": "Sofia",
  "three_letter_code": "SOF",
  "address": "Sofia, Bulgaria",
  "telephone": {
    "country_code": "+359",
    "number": "897577567",
    "country_iso_code": "BG"
  },
  "website": null,
  "geo": {
    "latitude": "42",
    "longitude": "27"
  },
  "display_asset": {
    "url": "https://example.com/sofia.jpg"
  },
  "icon": {
    "url": "https://example.com/sofia-icon.png"
  },
  "translations": [
    {
      "language": "en",
      "name": "Sofia",
      "short_name": "Sofia",
      "three_letter_code": "SOF",
      "address": "Sofia, Bulgaria"
    }
  ],
  "slug": "sofia",
  "default_language": "en",
  "contained_in_domain": "550e8400-e29b-41d4-a716-446655440000",
  "contained_in_place": "c12e7b4a-9e0c-4e75-a66d-1fdd59334b21",
  "social_media_links": [
    {
      "slug": "facebook",
      "value": "https://facebook.com/sofia"        
    },
    {
      "slug": "youtube",
      "value": "https://youtube.com/sofia"        
    }
  ]
}

Organization

Organizations represent entities like companies, government bodies, or sports federations. They can be related to a place, domain, and optionally a parent organization.

Example Response:

{
  "id": "87bf4d2e-d959-43c7-b4d3-6e2f47836753",
  "entity_type": "organization",
  "name": "Bulgarian Football Union",
  "short_name": "BFU",
  "three_letter_code": null,
  "address": "Sofia, Tsar Ivan Asen II St 26",
  "website": null,
  "email": null,
  "telephone": {
    "country_code": "+359",
    "number": "897577567",
    "country_iso_code": "BG"
  },
  "display_asset": {
    "url": "https://example.com/bfu.jpg"
  },
  "icon": {
    "url": "https://example.com/bfu-icon.png"
  },
  "translations": [
    {
      "language": "en",
      "name": "Bulgarian Football Union",
      "short_name": "BFU",
      "three_letter_code": null,
      "address": "Sofia, Tsar Ivan Asen II St 26"
    }
  ],
  "slug": "bfu",
  "default_language": "en",
  "contained_in_domain": "550e8400-e29b-41d4-a716-446655440000",
  "contained_in_place": "7be6efac-8942-4263-b524-0a39e0f322dd",
  "founding_date": "1878-11-12",
  "founding_year": "1878",
  "contained_in_organization": "a34f21c8-7e9d-48bc-9a2e-8c34f881d593",
  "social_media_links": [
    {
      "slug": "facebook",
      "value": "https://facebook.com/bfu"        
    },
    {
      "slug": "youtube",
      "value": "https://youtube.com/bfu"        
    }
  ]
}

Role

Roles represent positions or functions that can be assigned to a person. Importantly, roles are not scoped by domain and can be reused across multiple domains.

Example Response:

{
  "id": "ca684fcb-1fe5-4642-a4b9-49635ed828f0",
  "entity_type": "role",
  "name": "President",
  "short_name": "president",
  "three_letter_code": null,
  "translations": [
    {
      "language": "en",
      "name": "President",
      "short_name": "president",
      "three_letter_code": null
    }
  ],
  "slug": "president",
  "default_language": "en"
}

Person

Persons represent individuals. They can be related to places (nationality, birthplace) and have one or more roles, which may be associated with specific organizations and places.

Example Response:

{
  "id": "b48de12b-4306-4b92-b142-4364de18ca0b",
  "entity_type": "person",
  "name": "Borislav Mihaylov",
  "short_name": "B. Mihaylov",
  "three_letter_code": null,
  "display_asset": {
    "url": "https://example.com/mihaylov.jpg"
  },
  "icon": {
    "url": "https://example.com/mihaylov-icon.png"
  },
  "translations": [
    {
      "language": "en",
      "name": "Borislav Mihaylov",
      "short_name": "B. Mihaylov",
      "three_letter_code": null
    }
  ],
  "slug": "borislav-mihaylov",
  "default_language": "en",
  "contained_in_domain": "550e8400-e29b-41d4-a716-446655440000",
  "birthdate": "1963-02-12",
  "gender": "MALE",
  "height": "170",
  "weight": "100",
  "website": "https://example.com/mihaylov",
  "email": "[email protected]",
  "nationality": "06ba9b89-6261-422c-a923-fca313b6ee42",
  "birth_place": "7be6efac-8942-4263-b524-0a39e0f322dd",
  "roles": [
    {
      "role": "ca684fcb-1fe5-4642-a4b9-49635ed828f0",
      "organization": "87bf4d2e-d959-43c7-b4d3-6e2f47836753",
      "place": "04f26742-72dd-4c96-b245-1944ab5d8059"
    }
  ],
  "social_media_links": [
    {
      "slug": "facebook",
      "value": "https://facebook.com/mihaylov"
    },
    {
      "slug": "youtube",
      "value": "https://youtube.com/mihaylov"
    }
  ]
}

Social Media Links

The following entities can have social media links:

  • Person
  • Organization
  • Place

Currently supported social media types (slug values):

  • facebook
  • youtube
  • whatsapp
  • instagram
  • tiktok
  • x
  • linkedin
  • snapchat
  • telegram

Updated 14 days ago