openapi: 3.1.0 info: title: Refinitiv PermID Entity Search API description: >- RESTful API enabling search of entities by name, ticker, or RIC to return PermIDs, or use PermIDs to retrieve entity information. PermID is an open and free entity identification scheme that provides a unique identifier for organizations, instruments, and quotes across approximately 13 million organizations and 3 million equity quotes. version: '1.0.0' contact: name: LSEG Developer Support url: https://developers.lseg.com/en/support termsOfService: https://developers.lseg.com/en/terms-and-conditions externalDocs: description: PermID Entity Search API Documentation url: https://developers.lseg.com/en/api-catalog/open-perm-id/permid-entity-search/documentation servers: - url: https://api-eit.refinitiv.com/permid description: Production Server tags: - name: Entity Search description: >- Search for organizations, equity instruments, and equity quotes using various identifier types including name, ticker, RIC, LEI, and PermID. - name: Record Matching description: >- Match unstructured entity records to PermID identifiers for concordance and entity resolution. security: - apiKeyAuth: [] paths: /search: get: operationId: searchEntities summary: Search Entities by Query description: >- Searches for entities across organizations, equity instruments, and equity quotes. Supports searching by name, ticker, RIC, LEI, PermID, and other standard identifiers. Returns matching entities with their PermID identifiers and metadata. tags: - Entity Search parameters: - name: q in: query required: true description: >- The search query string. Can be a name, ticker, RIC, ISIN, LEI, or PermID. schema: type: string - name: entitytype in: query description: >- Filter results by entity type. schema: type: string enum: - organization - instrument - quote - name: num in: query description: >- Maximum number of results to return, default is 5. schema: type: integer default: 5 maximum: 100 - name: start in: query description: >- Starting index for pagination. schema: type: integer default: 1 responses: '200': description: Search results returned successfully content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Invalid query parameters '401': description: Invalid or missing API key '429': description: Rate limit exceeded /calais: post: operationId: tagContent summary: Tag Content with Entities description: >- Submits unstructured text content for natural language processing and entity extraction. Identifies and tags companies, people, deals, geographical locations, industries, and events within the text and maps recognized entities to Refinitiv PermIDs for unambiguous identification. tags: - Entity Search parameters: - name: x-ag-access-token in: header required: true description: >- The Open Calais API key for authentication. schema: type: string - name: Content-Type in: header required: true description: >- The content type of the input text. Supported values include text/plain, text/html, text/xml, and text/raw. schema: type: string enum: - text/plain - text/html - text/xml - text/raw - name: outputFormat in: header description: >- The desired output format for the tagging results. schema: type: string enum: - application/json - xml/rdf - text/n3 requestBody: required: true content: text/plain: schema: type: string description: >- The unstructured text content to analyze and tag. text/html: schema: type: string text/xml: schema: type: string responses: '200': description: Content tagged successfully content: application/json: schema: $ref: '#/components/schemas/TaggingResponse' '400': description: Invalid content or parameters '401': description: Invalid or missing API key '413': description: Content too large '429': description: Rate limit exceeded /match: post: operationId: matchRecords summary: Match Records to PermIDs description: >- Matches unstructured entity records to PermID identifiers. Accepts entity data such as organization name, address, and identifiers and returns the best matching PermID with confidence scores. tags: - Record Matching requestBody: required: true content: text/plain: schema: type: string description: >- CSV-formatted entity records with header row. Columns can include LocalID, Standard Identifier, Name, Country, Street, City, PostalCode, State, and Website. responses: '200': description: Records matched successfully content: text/plain: schema: type: string description: >- CSV-formatted matching results with matched PermIDs and confidence scores. '400': description: Invalid input format '401': description: Invalid or missing API key '429': description: Rate limit exceeded /lookup: get: operationId: lookupEntity summary: Look Up Entity by PermID description: >- Retrieves detailed information about a specific entity using its PermID identifier, returning structured data about the organization, instrument, or quote. tags: - Entity Search parameters: - name: q in: query required: true description: >- The PermID to look up. schema: type: string responses: '200': description: Entity details returned successfully content: application/json: schema: $ref: '#/components/schemas/EntityDetail' '400': description: Invalid PermID '401': description: Invalid or missing API key '404': description: Entity not found components: securitySchemes: apiKeyAuth: type: apiKey in: header name: x-ag-access-token description: >- Open PermID API key. Registered users receive an API key that is shared across PermID Entity Search, Record Matching, and Intelligent Tagging services. schemas: SearchResponse: type: object properties: result: type: object properties: organizations: type: object properties: total: type: integer description: >- Total number of matching organizations. entities: type: array items: $ref: '#/components/schemas/OrganizationEntity' instruments: type: object properties: total: type: integer description: >- Total number of matching instruments. entities: type: array items: $ref: '#/components/schemas/InstrumentEntity' quotes: type: object properties: total: type: integer description: >- Total number of matching quotes. entities: type: array items: $ref: '#/components/schemas/QuoteEntity' OrganizationEntity: type: object properties: organizationName: type: string description: >- The name of the organization. orgSubtype: type: string description: >- The subtype of the organization such as Company or Fund. hasHoldingClassification: type: string description: >- Whether the organization is public or private. primaryRIC: type: string description: >- The primary RIC associated with the organization. lei: type: string description: >- The Legal Entity Identifier. '@id': type: string format: uri description: >- The PermID URI for the organization. InstrumentEntity: type: object properties: hasName: type: string description: >- The name of the instrument. assetClass: type: string description: >- The asset class of the instrument. isIssuedBy: type: string description: >- The PermID of the issuing organization. '@id': type: string format: uri description: >- The PermID URI for the instrument. QuoteEntity: type: object properties: hasName: type: string description: >- The name of the quote. hasRIC: type: string description: >- The RIC code. hasMic: type: string description: >- The Market Identifier Code. isQuoteOf: type: string description: >- The PermID of the quoted instrument. '@id': type: string format: uri description: >- The PermID URI for the quote. TaggingResponse: type: object additionalProperties: type: object properties: _type: type: string description: >- The entity type such as Company, Person, City, or IndustryTerm. name: type: string description: >- The recognized entity name. _typeGroup: type: string description: >- The type group such as entities, topics, or relations. fopiPermId: type: string description: >- The associated PermID identifier. relevance: type: number description: >- The relevance score from 0 to 1. confidence: type: number description: >- The confidence score for the entity recognition. description: >- Map of extracted entities, topics, and relations keyed by unique identifiers, with each entry containing entity metadata and linked PermIDs. EntityDetail: type: object properties: '@id': type: string format: uri description: >- The PermID URI. organizationName: type: string description: >- The name of the organization. hasActivityStatus: type: string description: >- The activity status of the entity. isIncorporatedIn: type: string description: >- The country of incorporation. isDomiciledIn: type: string description: >- The country of domicile. hasURL: type: string format: uri description: >- The entity's website URL. hasPrimaryInstrument: type: string description: >- The PermID of the primary instrument.