Entities Structure

Get External Candidates

Retrieve information about entities using external sources

GET
https://api.textreveal.com/v3/entities/external-candidates

Request

Parameters

  • sizeinteger

    Number of records per page

    Default: 10Range: [1, 50]
  • fields(string (enum))[]

    Fields to include in the response

    Default: ["name", "country", "region", "city", "ticker", "registration_codes", "industry_codes", "alias", "website", "revenue", "linkage"]Values: "name", "country", "region", "city", "ticker", "registration_codes", "industry_codes", "alias", "website", "revenue", "linkage"
  • namestring

    Name of the entity.

    Example: "Fujitsu"
  • aliasstring

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

    Example: "Apple Computer"
  • dunsstring | null

    Duns number of the entity.

    Example: "000000000"
  • tickerstring

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

    Example: "AAPL"
  • websiteuri | null

    Website of the entity. Protocol is not always present.

    Example: "https://www.fujitsu.com/"
  • countryiso3166-2 (enum)

    Country code in ISO3166 alpha-2 standard (2 letters).

    Values: "ad", "ae", "af", "ag", "ai", "al", "am", "ao", "aq", "ar", "as", "at", "au", "aw", "ax", "az", "ba", "bb", "bd", "be", "bf", "bg", "bh", "bi", "bj", "bl", "bm", "bn", "bo", "bq", "br", "bs", "bt", "bv", "bw", "by", "bz", "ca", "cc"... 
  • regionstring

    Administrative region or state in which the entity is located. Value is in lowercase.

  • citystring

    Name of the city, town, township, village, borough, etc. where the entity is located. Value is in lowercase.

    Example: "miami"
  • industry_codestring

    Industry classification codes for the entity.

    Example: "1811"

Response

Response - 200

Properties of the candidates

  • total*number

    Total number of candidates matched

    Example: 27
  • data*object[]

    Search result

    Array length: [0, 50]
Response
{
  "total": 27,
  "data": [
    {
      "external_id": "41_LoE96n4OtUzOdQQSXg0Yr9p-_0fOu25u5QyR-la78PbQUNw",
      "name": "Fujitsu",
      "country": "united states of america",
      "region": "florida",
      "city": "miami",
      "ticker": [
        "AAPL"
      ],
      "registration_codes": [
        {
          "value": "17133723",
          "description": "Trade Register Number (NL)"
        }
      ],
      "industry_codes": [
        {
          "description": "ISIC Revision 4",
          "values": [
            {
              "code": "2816",
              "description": "Manufacture of lifting and handling equipment",
              "priority": 1
            }
          ]
        }
      ],
      "alias": [
        "Apple Inc."
      ],
      "website": "fujitsu.com",
      "revenue": {
        "yearly": {
          "value": 22405002516,
          "currency": "USD"
        }
      },
      "linkage": {
        "parent": null,
        "ultimate_parent": {
          "external_id": "41_LoE96n4OtUzOdQQSXg0Yr9p-_0fOu25u5QyR-la78PbQUNw",
          "name": "FUJITSU LIMITED"
        }
      }
    }
  ]
}

Error

Error - 400

Bad request

  • message*string

    Error message.

    Example: "Check the errors field for more details"
  • code*number (enum)

    Error code.

    Values: 400
  • reason*string (enum)

    Error reason.

    Values: "invalid"
  • errorsobject[]

    Possible error causes.

Response
{
  "message": "Check the errors field for more details",
  "code": 400,
  "reason": "invalid",
  "errors": [
    {
      "message": "string",
      "field": "size",
      "reason": "invalid_type"
    }
  ]
}

Error - 401

Unauthorized

  • message*string

    Error message.

    Example: "Authorization header is expected"
  • code*number (enum)

    Error code.

    Values: 401
  • reason*string (enum)

    Error reason.

    Values: "unauthorized"
  • errors*object[]
    Array length: [1, 1]
Response
{
  "message": "Authorization header is expected",
  "code": 401,
  "reason": "unauthorized",
  "errors": [
    {
      "message": "Required",
      "field": "headers.authorization",
      "reason": "invalid_type"
    }
  ]
}

Error - 429

Too many requests

  • message*string

    Error message.

    Example: "Global API rate limit reached. Please wait for a while and try again."
  • code*number (enum)

    Error code.

    Values: 429
  • reason*string (enum)

    Error reason.

    Values: "too_many_requests"
Response
{
  "message": "Global API rate limit reached. Please wait for a while and try again.",
  "code": 429,
  "reason": "too_many_requests"
}

Generic errors are not shown, see Errors for more details.