---
title: "List Entities"
url: "https://console.9fin.com/apis/entity-service/versions/31d9cce8-3ddc-42cd-b266-372482fbb0e1/operations/list_entities_v0_entity_get"
---

> Full API specification: https://console.9fin.com/apis/entity-service/versions/31d9cce8-3ddc-42cd-b266-372482fbb0e1.md

# List Entities

`GET` `/v0/entity`

Operation ID: `list_entities_v0_entity_get`

Returns a list of Entities. Allows for filtering and sorting by a variety of entity attributes.

## Query parameters

- `sort_by` (optional) - Comma-separated list of `field__asc` / `field__desc` tokens applied in order, e.g. `company_name__desc,price__asc`. Sortable fields: nf_id, roles, website, description, street_name, country_ref_name, industry_ref_code, cik, active_flag, alias, coverage_region, created_at, modified_at.
- `limit` (optional) - Maximum number of rows to return.
- `cursor` (optional) - Opaque keyset-pagination cursor from a prior page.
- `nf_id__eq` (optional) - Filter where nf_id equal value.
- `nf_id__neq` (optional) - Filter where nf_id not_equal value.
- `nf_id__contains` (optional) - Filter where nf_id contains value.
- `nf_id__in` (optional) - Filter where nf_id in value.
- `roles__contains` (optional) - Filter where the roles array contains this value.
- `website__eq` (optional) - Filter where website equal value.
- `website__neq` (optional) - Filter where website not_equal value.
- `website__contains` (optional) - Filter where website contains value.
- `website__in` (optional) - Filter where website in value.
- `description__eq` (optional) - Filter where description equal value.
- `description__neq` (optional) - Filter where description not_equal value.
- `description__contains` (optional) - Filter where description contains value.
- `description__in` (optional) - Filter where description in value.
- `street_name__eq` (optional) - Filter where street_name equal value.
- `street_name__neq` (optional) - Filter where street_name not_equal value.
- `street_name__contains` (optional) - Filter where street_name contains value.
- `street_name__in` (optional) - Filter where street_name in value.
- `country_ref_name__eq` (optional) - Filter where country_ref_name equal value.
- `country_ref_name__neq` (optional) - Filter where country_ref_name not_equal value.
- `country_ref_name__contains` (optional) - Filter where country_ref_name contains value.
- `country_ref_name__in` (optional) - Filter where country_ref_name in value.
- `industry_ref_code__eq` (optional) - Filter where industry_ref_code equal value.
- `industry_ref_code__neq` (optional) - Filter where industry_ref_code not_equal value.
- `industry_ref_code__contains` (optional) - Filter where industry_ref_code contains value.
- `industry_ref_code__in` (optional) - Filter where industry_ref_code in value.
- `cik__eq` (optional) - Filter where cik equal value.
- `cik__neq` (optional) - Filter where cik not_equal value.
- `cik__gt` (optional) - Filter where cik greater value.
- `cik__gte` (optional) - Filter where cik greater_or_equal value.
- `cik__lt` (optional) - Filter where cik less value.
- `cik__lte` (optional) - Filter where cik less_or_equal value.
- `cik__in` (optional) - Filter where cik in value.
- `active_flag__eq` (optional) - Filter where active_flag equal value.
- `active_flag__neq` (optional) - Filter where active_flag not_equal value.
- `alias__contains` (optional) - Filter where the alias array contains this value.
- `coverage_region__contains` (optional) - Filter where the coverage_region array contains this value.
- `created_at__eq` (optional) - Filter where created_at equal value.
- `created_at__neq` (optional) - Filter where created_at not_equal value.
- `created_at__gt` (optional) - Filter where created_at greater value.
- `created_at__gte` (optional) - Filter where created_at greater_or_equal value.
- `created_at__lt` (optional) - Filter where created_at less value.
- `created_at__lte` (optional) - Filter where created_at less_or_equal value.
- `created_at__in` (optional) - Filter where created_at in value.
- `modified_at__eq` (optional) - Filter where modified_at equal value.
- `modified_at__neq` (optional) - Filter where modified_at not_equal value.
- `modified_at__gt` (optional) - Filter where modified_at greater value.
- `modified_at__gte` (optional) - Filter where modified_at greater_or_equal value.
- `modified_at__lt` (optional) - Filter where modified_at less value.
- `modified_at__lte` (optional) - Filter where modified_at less_or_equal value.
- `modified_at__in` (optional) - Filter where modified_at in value.

## Responses

- `200` - Successful Response
- `400` - Bad request (e.g. invalid cursor).
- `422` - Request validation failed (e.g. unknown query parameter).
- `500` - Unexpected server error.
- `503` - Service unavailable (e.g. database down).

## OpenAPI definition

```yaml
openapi: 3.1.0
info:
  title: 9fin Entity API
  version: 0.5.0
servers:
  - description: Production environment
    url: https://api.9fin.com
paths:
  /v0/entity:
    get:
      description: |-
        Returns a list of Entities.
        Allows for filtering and sorting by a variety of entity attributes.
      operationId: list_entities_v0_entity_get
      parameters:
        - description: "Comma-separated list of `field__asc` / `field__desc` tokens
            applied in order, e.g. `company_name__desc,price__asc`. Sortable
            fields: nf_id, roles, website, description, street_name,
            country_ref_name, industry_ref_code, cik, active_flag, alias,
            coverage_region, created_at, modified_at."
          in: query
          name: sort_by
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: "Comma-separated list of `field__asc` / `field__desc` tokens
              applied in order, e.g. `company_name__desc,price__asc`. Sortable
              fields: nf_id, roles, website, description, street_name,
              country_ref_name, industry_ref_code, cik, active_flag, alias,
              coverage_region, created_at, modified_at."
            title: Sort By
        - description: Maximum number of rows to return.
          in: query
          name: limit
          required: false
          schema:
            anyOf:
              - maximum: 100
                minimum: 1
                type: integer
              - type: "null"
            default: 20
            description: Maximum number of rows to return.
            title: Limit
        - description: Opaque keyset-pagination cursor from a prior page.
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Opaque keyset-pagination cursor from a prior page.
            title: Cursor
        - description: Filter where nf_id equal value.
          in: query
          name: nf_id__eq
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where nf_id equal value.
            title: Nf Id  Eq
        - description: Filter where nf_id not_equal value.
          in: query
          name: nf_id__neq
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where nf_id not_equal value.
            title: Nf Id  Neq
        - description: Filter where nf_id contains value.
          in: query
          name: nf_id__contains
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where nf_id contains value.
            title: Nf Id  Contains
        - description: Filter where nf_id in value.
          in: query
          name: nf_id__in
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where nf_id in value.
            title: Nf Id  In
        - description: Filter where the roles array contains this value.
          in: query
          name: roles__contains
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where the roles array contains this value.
            title: Roles  Contains
        - description: Filter where website equal value.
          in: query
          name: website__eq
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where website equal value.
            title: Website  Eq
        - description: Filter where website not_equal value.
          in: query
          name: website__neq
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where website not_equal value.
            title: Website  Neq
        - description: Filter where website contains value.
          in: query
          name: website__contains
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where website contains value.
            title: Website  Contains
        - description: Filter where website in value.
          in: query
          name: website__in
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where website in value.
            title: Website  In
        - description: Filter where description equal value.
          in: query
          name: description__eq
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where description equal value.
            title: Description  Eq
        - description: Filter where description not_equal value.
          in: query
          name: description__neq
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where description not_equal value.
            title: Description  Neq
        - description: Filter where description contains value.
          in: query
          name: description__contains
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where description contains value.
            title: Description  Contains
        - description: Filter where description in value.
          in: query
          name: description__in
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where description in value.
            title: Description  In
        - description: Filter where street_name equal value.
          in: query
          name: street_name__eq
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where street_name equal value.
            title: Street Name  Eq
        - description: Filter where street_name not_equal value.
          in: query
          name: street_name__neq
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where street_name not_equal value.
            title: Street Name  Neq
        - description: Filter where street_name contains value.
          in: query
          name: street_name__contains
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where street_name contains value.
            title: Street Name  Contains
        - description: Filter where street_name in value.
          in: query
          name: street_name__in
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where street_name in value.
            title: Street Name  In
        - description: Filter where country_ref_name equal value.
          in: query
          name: country_ref_name__eq
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where country_ref_name equal value.
            title: Country Ref Name  Eq
        - description: Filter where country_ref_name not_equal value.
          in: query
          name: country_ref_name__neq
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where country_ref_name not_equal value.
            title: Country Ref Name  Neq
        - description: Filter where country_ref_name contains value.
          in: query
          name: country_ref_name__contains
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where country_ref_name contains value.
            title: Country Ref Name  Contains
        - description: Filter where country_ref_name in value.
          in: query
          name: country_ref_name__in
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where country_ref_name in value.
            title: Country Ref Name  In
        - description: Filter where industry_ref_code equal value.
          in: query
          name: industry_ref_code__eq
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where industry_ref_code equal value.
            title: Industry Ref Code  Eq
        - description: Filter where industry_ref_code not_equal value.
          in: query
          name: industry_ref_code__neq
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where industry_ref_code not_equal value.
            title: Industry Ref Code  Neq
        - description: Filter where industry_ref_code contains value.
          in: query
          name: industry_ref_code__contains
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where industry_ref_code contains value.
            title: Industry Ref Code  Contains
        - description: Filter where industry_ref_code in value.
          in: query
          name: industry_ref_code__in
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where industry_ref_code in value.
            title: Industry Ref Code  In
        - description: Filter where cik equal value.
          in: query
          name: cik__eq
          required: false
          schema:
            anyOf:
              - type: integer
              - type: "null"
            default: null
            description: Filter where cik equal value.
            title: Cik  Eq
        - description: Filter where cik not_equal value.
          in: query
          name: cik__neq
          required: false
          schema:
            anyOf:
              - type: integer
              - type: "null"
            default: null
            description: Filter where cik not_equal value.
            title: Cik  Neq
        - description: Filter where cik greater value.
          in: query
          name: cik__gt
          required: false
          schema:
            anyOf:
              - type: integer
              - type: "null"
            default: null
            description: Filter where cik greater value.
            title: Cik  Gt
        - description: Filter where cik greater_or_equal value.
          in: query
          name: cik__gte
          required: false
          schema:
            anyOf:
              - type: integer
              - type: "null"
            default: null
            description: Filter where cik greater_or_equal value.
            title: Cik  Gte
        - description: Filter where cik less value.
          in: query
          name: cik__lt
          required: false
          schema:
            anyOf:
              - type: integer
              - type: "null"
            default: null
            description: Filter where cik less value.
            title: Cik  Lt
        - description: Filter where cik less_or_equal value.
          in: query
          name: cik__lte
          required: false
          schema:
            anyOf:
              - type: integer
              - type: "null"
            default: null
            description: Filter where cik less_or_equal value.
            title: Cik  Lte
        - description: Filter where cik in value.
          in: query
          name: cik__in
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where cik in value.
            title: Cik  In
        - description: Filter where active_flag equal value.
          in: query
          name: active_flag__eq
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: "null"
            default: null
            description: Filter where active_flag equal value.
            title: Active Flag  Eq
        - description: Filter where active_flag not_equal value.
          in: query
          name: active_flag__neq
          required: false
          schema:
            anyOf:
              - type: boolean
              - type: "null"
            default: null
            description: Filter where active_flag not_equal value.
            title: Active Flag  Neq
        - description: Filter where the alias array contains this value.
          in: query
          name: alias__contains
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where the alias array contains this value.
            title: Alias  Contains
        - description: Filter where the coverage_region array contains this value.
          in: query
          name: coverage_region__contains
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where the coverage_region array contains this value.
            title: Coverage Region  Contains
        - description: Filter where created_at equal value.
          in: query
          name: created_at__eq
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: "null"
            default: null
            description: Filter where created_at equal value.
            title: Created At  Eq
        - description: Filter where created_at not_equal value.
          in: query
          name: created_at__neq
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: "null"
            default: null
            description: Filter where created_at not_equal value.
            title: Created At  Neq
        - description: Filter where created_at greater value.
          in: query
          name: created_at__gt
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: "null"
            default: null
            description: Filter where created_at greater value.
            title: Created At  Gt
        - description: Filter where created_at greater_or_equal value.
          in: query
          name: created_at__gte
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: "null"
            default: null
            description: Filter where created_at greater_or_equal value.
            title: Created At  Gte
        - description: Filter where created_at less value.
          in: query
          name: created_at__lt
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: "null"
            default: null
            description: Filter where created_at less value.
            title: Created At  Lt
        - description: Filter where created_at less_or_equal value.
          in: query
          name: created_at__lte
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: "null"
            default: null
            description: Filter where created_at less_or_equal value.
            title: Created At  Lte
        - description: Filter where created_at in value.
          in: query
          name: created_at__in
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where created_at in value.
            title: Created At  In
        - description: Filter where modified_at equal value.
          in: query
          name: modified_at__eq
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: "null"
            default: null
            description: Filter where modified_at equal value.
            title: Modified At  Eq
        - description: Filter where modified_at not_equal value.
          in: query
          name: modified_at__neq
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: "null"
            default: null
            description: Filter where modified_at not_equal value.
            title: Modified At  Neq
        - description: Filter where modified_at greater value.
          in: query
          name: modified_at__gt
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: "null"
            default: null
            description: Filter where modified_at greater value.
            title: Modified At  Gt
        - description: Filter where modified_at greater_or_equal value.
          in: query
          name: modified_at__gte
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: "null"
            default: null
            description: Filter where modified_at greater_or_equal value.
            title: Modified At  Gte
        - description: Filter where modified_at less value.
          in: query
          name: modified_at__lt
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: "null"
            default: null
            description: Filter where modified_at less value.
            title: Modified At  Lt
        - description: Filter where modified_at less_or_equal value.
          in: query
          name: modified_at__lte
          required: false
          schema:
            anyOf:
              - format: date-time
                type: string
              - type: "null"
            default: null
            description: Filter where modified_at less_or_equal value.
            title: Modified At  Lte
        - description: Filter where modified_at in value.
          in: query
          name: modified_at__in
          required: false
          schema:
            anyOf:
              - type: string
              - type: "null"
            default: null
            description: Filter where modified_at in value.
            title: Modified At  In
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EntityListResponse"
          description: Successful Response
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Bad request (e.g. invalid cursor).
        "422":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Request validation failed (e.g. unknown query parameter).
        "500":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/InternalServerErrorResponse"
          description: Unexpected server error.
        "503":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Service unavailable (e.g. database down).
      security:
        - HTTPBearer: []
      summary: List Entities
      tags:
        - entity
security:
  - HTTPBearer: []
components:
  schemas:
    EntityListResponse:
      description: Public-facing page of entities; `next_cursor` is None on the last page.
      properties:
        items:
          items:
            $ref: "#/components/schemas/EntityResponse"
          title: Items
          type: array
        next_cursor:
          anyOf:
            - type: string
            - type: "null"
          title: Next Cursor
      required:
        - items
        - next_cursor
      title: EntityListResponse
      type: object
    ErrorResponse:
      description: Client-facing error envelope.
      examples:
        - error_code: invalid_cursor
          message: The supplied cursor could not be decoded.
          trace_id: 202bde256c7d446f9623efdc96286c5d
        - error_code: service_unavailable
          message: Database is not available
          trace_id: c2416d52c6d14c8e831aad792407442c
        - details:
            - field: limit
              message: Input should be less than or equal to 100
          error_code: validation_error
          message: Request validation failed
          trace_id: 5cc0f4dd4a0a4b7fa0b3b0f2b4f9a1c7
      properties:
        details:
          anyOf:
            - items:
                $ref: "#/components/schemas/ErrorDetail"
              type: array
            - type: "null"
          title: Details
        error_code:
          title: Error Code
          type: string
        message:
          title: Message
          type: string
        trace_id:
          anyOf:
            - type: string
            - type: "null"
          title: Trace Id
      required:
        - error_code
        - message
      title: ErrorResponse
      type: object
    InternalServerErrorResponse:
      properties:
        error_code:
          examples:
            - internal_server_error
          title: Error Code
          type: string
        message:
          examples:
            - An unexpected error occurred.
          title: Message
          type: string
        trace_id:
          anyOf:
            - type: string
            - type: "null"
          examples:
            - e7dfd20231374d308f04655eb0538be4
          title: Trace Id
      required:
        - error_code
        - message
        - trace_id
      title: InternalServerErrorResponse
      type: object
    EntityResponse:
      description: Public-facing subset of an entity.
      properties:
        active_flag:
          anyOf:
            - type: boolean
            - type: "null"
          title: Active Flag
        alias:
          anyOf:
            - items:
                type: string
              type: array
            - type: "null"
          title: Alias
        cik:
          anyOf:
            - type: integer
            - type: "null"
          title: Cik
        country_ref_name:
          anyOf:
            - type: string
            - type: "null"
          title: Country Ref Name
        coverage_region:
          anyOf:
            - items:
                type: string
              type: array
            - type: "null"
          title: Coverage Region
        created_at:
          format: date-time
          title: Created At
          type: string
        description:
          anyOf:
            - type: string
            - type: "null"
          title: Description
        industry_ref_code:
          anyOf:
            - type: string
            - type: "null"
          title: Industry Ref Code
        modified_at:
          format: date-time
          title: Modified At
          type: string
        nf_id:
          title: Nf Id
          type: string
        roles:
          items:
            type: string
          title: Roles
          type: array
        street_name:
          anyOf:
            - type: string
            - type: "null"
          title: Street Name
        website:
          anyOf:
            - type: string
            - type: "null"
          title: Website
      required:
        - nf_id
        - roles
        - website
        - description
        - street_name
        - country_ref_name
        - industry_ref_code
        - cik
        - active_flag
        - alias
        - coverage_region
        - created_at
        - modified_at
      title: EntityResponse
      type: object
    ErrorDetail:
      description: One field-level problem within an error response.
      properties:
        field:
          examples:
            - limit
          title: Field
          type: string
        message:
          examples:
            - Input should be less than or equal to 100
          title: Message
          type: string
      required:
        - field
        - message
      title: ErrorDetail
      type: object
  securitySchemes:
    HTTPBearer:
      bearerFormat: JWT
      scheme: bearer
      type: http
```