Entities Structure

Get Entities

List the available entities

GET
https://api.textreveal.com/v3/entities

Each entity has a hidden _score field that is a relevance score. The relevancy of an entity is computed based on the following factors:

  • Does the entity have a lei, ticker, ... same for other identifiers
  • Does the entity have a valid description, website ...

And then based on the query, if the entity is a match or not. When using fuzzy, the score is higher if the entity is close to the query.

Request

Parameters

  • sizeinteger

    Number of records per page

    Default: 10Range: [1, 1000]
  • search_afterstring

    search_after field value from the previous page

  • name(string (operator))[]

    Name of the entity.

    Example: "ilike:hello"
  • alias(string (operator))[]

    Alternative name, abbreviation, or local brand used to refer to a company or entity.

    Example: "ilike:hello"
  • duns(string (operator))[]

    Duns number of the entity.

    Example: "ilike:hello"
  • figi(string (operator))[]

    FIGI (Financial Instrument Global Identifier) of the entity.

    Example: "ilike:hello"
  • isin(string (operator))[]

    International Securities Identification Number used to uniquely identify a financial security.

    Example: "ilike:hello"
  • ticker(string (operator))[]

    Stock market ticker symbol used to identify a publicly traded company on an exchange.

    Example: "ilike:hello"
  • lei(string (operator))[]

    Legal Entity Identifier (LEI) is a 20-character alphanumeric code.

    Example: "ilike:hello"
  • entity_id(string (operator))[]

    SESAMm Unique Entity ID.

    Example: "ilike:hello"
  • website(string (operator))[]

    Website of the entity. Protocol is not always present.

    Example: "ilike:hello"
  • country(string (enum))[]

    County of the entity.

    Values: "afghanistan", "aland islands", "albania", "algeria", "american samoa", "andorra", "angola", "anguilla", "antarctica", "antigua and barbuda", "argentina", "armenia", "aruba", "australia", "austria", "azerbaijan", "bahamas", "bahrain... 
  • client_code(string (operator))[]

    Custom entity identifiers to make it easier to link SESAMm entities with external Knowledge Graphs / client systems. The client code are isolated between the SESAMm company model and are not visible to other client.

    To add yours to the entities of your universe, contact your account manager.

    Example: "ilike:hello"
  • orderfield:direction

    Order to apply to the result.

    Possible fields are: name, _score.

    Possible directions are: asc and desc.

    Default: _score:descExample: "_score:desc"
  • pageinteger

    Page number, 1-based

  • fields(string (enum))[]

    Fields to include in the response

    Default: ["id", "description", "name", "figi", "isin", "ticker", "alias", "website", "country", "lei"]Values: "id", "description", "name", "figi", "isin", "ticker", "alias", "website", "country", "lei", "client_code", "related_universe_count"

Response

Response - 200

Properties of the entities

  • data*object[]

    Properties of the entities.

  • size*integer

    Number of records per page requested.

    Example: 1
  • has_next*boolean

    True if there are more records available.

    Example: true
  • count*integer

    Number of records returned in the current page.

    Example: 1
  • total*integer

    Total number of records.

    Example: 1
  • search_afterstring | null

    Cursor for next page.

Response
{
  "data": [
    {
      "id": "753c48d6-23c8-5fb0-9230-b099898452b5",
      "description": "Fujitsu is a information & communications technology equipment and services firm providing IT & IT infrastructure and other services.",
      "name": "Fujitsu",
      "figi": "BBG000BLNXT1",
      "isin": [
        "US0378331005"
      ],
      "ticker": [
        "AAPL"
      ],
      "alias": [
        "Apple Inc."
      ],
      "website": "https://www.fujitsu.com/",
      "country": "japan",
      "lei": "123400ABCDEFGH56789",
      "client_code": {
        "code1": "ABC123456",
        "code2": "789XYZ"
      },
      "related_universe_count": 0
    }
  ],
  "size": 1,
  "has_next": true,
  "count": 1,
  "total": 1,
  "search_after": "string"
}

Error

Error - 400

Bad request

  • message*string

    Error message.

    Example: "The server returned an unexpected response"
  • code*integer

    Error code.

    Example: 400
  • reason*string (enum)

    Error reason.

    Values: "invalid", "timeout", "offline", "unknown", "not_found", "unauthorized", "forbidden", "internal", "too_many_requests"
  • errorsobject[]

    Possible error causes, like query params, headers or body.

Response
{
  "message": "The server returned an unexpected response",
  "code": 400,
  "reason": "invalid",
  "errors": [
    {
      "message": "Expected number, received string",
      "field": "size",
      "reason": "invalid_type"
    }
  ]
}

Error - 403

Not authorized

  • message*string
    Example: "Not authorized to access this resource"
  • code*number (enum)

    Error code.

    Values: 403
  • reason*string (enum)
    Values: "forbidden"
Response
{
  "message": "Not authorized to access this resource",
  "code": 403,
  "reason": "forbidden"
}

Error - 404

Not found

  • message*string
    Example: "[record] not found."
  • code*number (enum)

    Error code.

    Values: 404
  • reason*string (enum)
    Values: "not_found"
Response
{
  "message": "[record] not found.",
  "code": 404,
  "reason": "not_found"
}

Error - 429

Too many requests

  • message*string
    Example: "You have too many exports in progress."
  • code*number (enum)
    Values: 429
  • reason*string (enum)
    Values: "too_many_requests"
Response
{
  "message": "You have too many exports in progress.",
  "code": 429,
  "reason": "too_many_requests"
}