> ## Documentation Index > Fetch the complete documentation index at: https://docs.frankieone.com/llms.txt > Use this file to discover all available pages before exploring further. # Get a list of matchlist entries > The query parameter `entityId` can be used to filter the entries by entity ID. The entity UUID must be in lower case. The query parameter `reference` can be used to filter the entries by reference. The query parameter `batchName` can be used to filter the entries by batch name. The query parameter `states` can be used to filter the entries by state. If set, the response will include only entries with the specified states. By default only `ACTIVE` entries are returned if the matchlist is `ACTIVE`. If the matchlist is `ARCHIVED` only `EXPIRED` entries will be returned. Possible values are: `ACTIVE`, `EXPIRED`, and `DELETED`. Multiple values can be provided as a comma-separated list. For example, `DELETED,EXPIRED`. The query parameter `sortFields` (`createdAt`, `updatedAt` or `state`) can be set to one or more fields for sorting. The default is to use just `createdAt`. The query parameter `sort` can set the sort order to ascending (`asc`) or descending (`desc`). The default is ascending. The query parameters `limit` (default 10) and `page` (default 1) can be used to control paging of the returned entries. The values given must be positive. If no matching entries are found, or the page is too large, then the entries array will be empty, but the result code is still 200. In addition to the entries, the response will also include the basic details of the matchlist, including its state. This is important, since if a matchlist is `ARCHIVED`, all previously `ACTIVE` entries will be `EXPIRED`, and will only be seen in the response if the `states` includes `EXPIRED`. So the entries array will be blank for `ARCHIVED` matchlists if `states` is not given. ## OpenAPI ````yaml /specs/fc-core-bundled_generated.yaml get /v2/matchlists/{matchlistName}/entries openapi: 3.0.3 info: title: Core V2 API version: 2.0.0 description: >- This is the APIs for V2 Core. It allows you to do common operations, such as read audit entries or get workflow lists. contact: name: FrankieOne url: https://www.frankieone.com/ email: help@frankieone.com servers: - url: https://api.uat.frankie.one description: UAT Environment API Base URL - url: https://api.frankie.one description: Production API Base URL security: - Api-Key: [] tags: - name: Audit description: Manage audit entries - name: Customers description: Manage customer accounts - name: Users description: Manage users provisioned in child customer accounts - name: Request description: Retrieve background request results - name: Reports description: Generate and manage reports - name: Results description: Manage process results including redaction - name: Workflow Definitions description: Create and update workflow definitions - name: Status description: All valid customers will get a successful response. - name: Workflows description: Manage Workflows and Workflow Definitions - name: Tags description: Query tags and tag mappings on objects paths: /v2/matchlists/{matchlistName}/entries: parameters: - $ref: '#/components/parameters/matchlistName' get: tags: - Matchlists summary: Get a list of matchlist entries description: >- The query parameter `entityId` can be used to filter the entries by entity ID. The entity UUID must be in lower case. The query parameter `reference` can be used to filter the entries by reference. The query parameter `batchName` can be used to filter the entries by batch name. The query parameter `states` can be used to filter the entries by state. If set, the response will include only entries with the specified states. By default only `ACTIVE` entries are returned if the matchlist is `ACTIVE`. If the matchlist is `ARCHIVED` only `EXPIRED` entries will be returned. Possible values are: `ACTIVE`, `EXPIRED`, and `DELETED`. Multiple values can be provided as a comma-separated list. For example, `DELETED,EXPIRED`. The query parameter `sortFields` (`createdAt`, `updatedAt` or `state`) can be set to one or more fields for sorting. The default is to use just `createdAt`. The query parameter `sort` can set the sort order to ascending (`asc`) or descending (`desc`). The default is ascending. The query parameters `limit` (default 10) and `page` (default 1) can be used to control paging of the returned entries. The values given must be positive. If no matching entries are found, or the page is too large, then the entries array will be empty, but the result code is still 200. In addition to the entries, the response will also include the basic details of the matchlist, including its state. This is important, since if a matchlist is `ARCHIVED`, all previously `ACTIVE` entries will be `EXPIRED`, and will only be seen in the response if the `states` includes `EXPIRED`. So the entries array will be blank for `ARCHIVED` matchlists if `states` is not given. operationId: getMatchlistEntries parameters: - $ref: '#/components/parameters/Api-Key' - $ref: '#/components/parameters/X-Frankie-CustomerID' - $ref: '#/components/parameters/X-Frankie-CustomerChildID' - $ref: '#/components/parameters/X-Frankie-Channel' - $ref: '#/components/parameters/X-Frankie-Username' - $ref: '#/components/parameters/query_entry_states' - $ref: '#/components/parameters/query_batch_name' - $ref: '#/components/parameters/query_reference' - $ref: '#/components/parameters/query_entity_id' - $ref: '#/components/parameters/query_entry_id' - $ref: '#/components/parameters/sort' - $ref: '#/components/parameters/matchlist_sort_fields' - $ref: '#/components/parameters/page' - $ref: '#/components/parameters/limit' responses: '200': description: OK content: application/json: schema: type: object properties: requestId: $ref: '#/components/schemas/Request-ID' entries: type: array items: $ref: '#/components/schemas/Matchlist-Entry' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid EntityId: value: errorCode: API-0400, errorMsg: 'Multiple Errors: See Issues list' details: - issue: 'entityId in path must be of type uuid: "test"' issueLocation: VALIDATE-entityId requestId: 01HM5XJ7VASZ3EJMB1VQGTBFJ4 '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' examples: Invalid authentication: value: errorCode: AUTH-0002, errorMsg: Unauthorized details: - issue: Invalid Authentication provided. Access denied. issueLocation: request requestId: 00000000S6MNG7624K2TDXT1E3 No Api-Key: value: errorCode: AUTH-0401 errorMsg: Unauthorized details: - issue: No api key provided. Access denied. issueLocation: request requestId: 00000001S6MNG7624K2TDXT1E3 '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: Bad Gateway content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/Error' security: - Api-Key: [] - jwt: - kyc:api components: parameters: matchlistName: name: matchlistName in: path schema: type: string description: The name of the matchlist. required: true Api-Key: name: api_key in: header schema: type: string example: 245c765b124a098d09ef8765.... description: Your API key provided by FrankieOne required: true X-Frankie-CustomerID: name: X-Frankie-CustomerID in: header required: true schema: type: string example: 12345678-1234-1234-1234-123456789012 description: Your Customer ID provided by FrankieOne X-Frankie-CustomerChildID: name: X-Frankie-CustomerChildID in: header required: false schema: type: string example: 87654321-4321-4321-4321-210987654321 description: Your Customer Child ID provided by FrankieOne X-Frankie-Channel: name: X-Frankie-Channel in: header required: false schema: type: string description: >- Open string that can be used to define the "channel" the request comes in from. It can potentially be used in routing and risk calculations upon request. Default values that can be used are: api portal smartui Any alphanumeric string is supported though. Anything over 64 characters will be truncated. X-Frankie-Username: name: X-Frankie-Username in: header description: Username provided by API caller required: false schema: type: string example: fred.flintstone@frankieone.com query_entry_states: name: states in: query style: form explode: false schema: description: List of states to include in the response. type: array items: $ref: '#/components/schemas/Matchlist-Entry-State' description: >- If set, the response will include only entries with the specified states. By default, only `ACTIVE` entries are returned. Possible values are: `ACTIVE`, `EXPIRED`, and `DELETED`. Multiple values can be provided as a comma-separated list. For example, `DELETED,EXPIRED`. query_batch_name: name: batchName in: query schema: description: Batch name of entries to include in the response. type: string example: blocklist.csv description: >- If set, the response will include only entries from the specified batch. By default, all entries will be returned. query_reference: name: reference in: query schema: description: Reference of entries to include in the response. type: string example: CERT-BAD-ACTOR-1234-5678 description: >- If set, the response will include only entries with the specified reference. By default, all entries will be returned. query_entity_id: name: entityId in: query schema: type: string format: uuid example: 12345678-1234-1234-1234-123456789012 description: >- If set, the response will include only entries created with the specified entityId. By default, all entries will be returned. query_entry_id: name: entryId in: query schema: description: Entry ID of entries to include in the response. type: string format: uuid example: 12345678-1234-1234-1234-123456789987 description: >- If set, the response will include only the entry with the specified id. By default, all entries will be returned. sort: in: query name: sort schema: type: string enum: - asc - desc description: Order of the sort fields will be sorted upon matchlist_sort_fields: name: sortFields in: query style: form explode: false example: state schema: type: array description: List of sort fields items: type: string description: One sort field enum: - updatedAt - createdAt - state description: >- The list of sort fields that will be used in the query. The order of the sort fields will determine the order in which the items are sorted. If state is added the sort order will always be `ACTIVE`, `EXPIRED`, `DELETED`. page: in: query name: page example: 2 schema: type: integer description: The page number that you want to retrieve for the list query limit: in: query name: limit schema: type: integer minimum: 1 default: 20 example: 20 description: Limit the number of items that will be returned as part of the request schemas: Request-ID: type: string example: 01HN9XHZN6MGXM9JXG50K59Q85 description: The unique request identifier for the API call made. Matchlist-Entry: type: object description: Represents a single entry in a matchlist. allOf: - $ref: '#/components/schemas/Matchlist-Entry-Base' - type: object description: >- Additional entry details that are only visible to the matchlist owner. title: Matchlist Entry required: - attributes properties: attributes: $ref: '#/components/schemas/Matchlist-Entry-Attributes' state: $ref: '#/components/schemas/Matchlist-Entry-State' batchName: type: string description: Optional batch name to identify the source of this entry. example: blocklist.csv createdBy: type: string readOnly: true description: >- The user who created the matchlist entry. This is set to the value in the `X-Frankie-Username` header. createdAt: type: string format: date-time readOnly: true description: The date and time when the matchlist entry was created. updatedBy: type: string readOnly: true description: >- The user who last updated the matchlist entry. This is set to the value in the `X-Frankie-Username` header. On creation, this is the same as `createdBy`. updatedAt: type: string format: date-time readOnly: true description: >- The date and time when the matchlist entry was last updated. On creation, this is the same as `createdAt`. Error: type: object x-examples: '400': requestId: 0123456789ABCDEFGHIJKLMNOP errorCode: API-0400 errorMsg: Parsing credentials from "" failed, because invalid. httpStatusCode: 400 '401': requestId: 0123456789ABCDEFGHIJKLMNOP errorCode: API-0401 errorMsg: Unauthenticated due to invalid credentials. httpStatusCode: 401 '409': requestId: 0123456789ABCDEFGHIJKLMNOP errorCode: API-0409 errorMsg: Conflict. httpStatusCode: 409 allOf: - $ref: '#/components/schemas/Error-Base' - type: object properties: requestId: $ref: '#/components/schemas/Request-ID' Matchlist-Entry-State: type: string description: |- The state of the matchlist entry. - `ACTIVE`: The matchlist entry is active and can be used for matching. - `EXPIRED`: The matchlist entry has expired. It is visible and retrievable, but cannot be used for matching. - `DELETED`: The matchlist entry has been marked as deleted, rendering it unusable. To modify an entry's state, use `Matchlist-Entry-State-Writeable`. default: ACTIVE readOnly: true enum: - ACTIVE - EXPIRED - DELETED Matchlist-Entry-Base: type: object description: Basic details about a matchlist entry, excluding metadata. properties: entryId: type: string format: uuid readOnly: true description: Unique identifier for the matchlist entry. entityId: type: string example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 description: >- The entity ID from which the attributes of this entry are derived. This is optional and can be used to link the matchlist entry to an entity. entityType: $ref: '#/components/schemas/Entity-Type' description: >- The type of entity from which the attributes of this entry are derived. This is optional and can be used to link the matchlist entry to an entity. reference: type: string description: Optional reference describing the context of this entry. example: CERT-BAD-ACTOR-1234-5678 reasons: description: >- The reasons for the matchlist entry. These codes will be translated to configured description strings. type: array items: $ref: '#/components/schemas/Matchlist-Entry-Reason-Code' Matchlist-Entry-Attributes: type: array description: All attributes associated with a matchlist entry. minItems: 1 items: $ref: '#/components/schemas/Matchlist-Entry-Attribute' Error-Base: type: object properties: errorCode: type: string errorMsg: type: string details: type: array items: $ref: '#/components/schemas/Issue' Entity-Type: type: string enum: - INDIVIDUAL - ORGANIZATION - UNKNOWN description: >- The type of entity within Frankie. This can be "INDIVIDUAL", "ORGANIZATION", or "UNKNOWN". readOnly: true x-oapi-codegen-extra-tags: audit: keep Matchlist-Entry-Reason-Code: type: string description: >- The reason code for the matchlist entry. This code will be translated to a configured description string. Supported codes are 1 to 24 characters long, consisting only of uppercase letters (A-Z), digits (0-9), underscores (_), or hyphens (-), with no spaces or special characters. pattern: ^[A-Z0-9_-]{1,24}$ Matchlist-Entry-Attribute: type: object description: Represents a single attribute of a matchlist entry. required: - type - value properties: type: $ref: '#/components/schemas/Matchlist-Entry-Attribute-Type' value: description: >- The value of the attribute, e.g., last name "Smith" if the type is IND_FAMILY_NAME. type: string Issue: type: object properties: issue: type: string description: Description of the issue. issueLocation: type: string description: The location or context where the issue was identified. issueType: type: string description: The type or category of the issue. Matchlist-Entry-Attribute-Type: type: string description: >- Entity attributes eligible for screening. A matchlist entry may not contain both `ORG_*` and `IND_*` attributes, and they must match the `ENTITY_TYPE` if it is provided. enum: - ENTITY_TYPE - EMAIL_ADDRESS - EMAIL_DOMAIN - PHONE_NUMBER - ADDR_STREET_NUMBER - ADDR_STREET_NAME - ADDR_STREET_TYPE - ADDR_NEIGHBORHOOD - ADDR_LOCALITY - ADDR_DISTRICT - ADDR_SUBDIVISION - ADDR_COUNTRY - ADDR_POSTAL_CODE - ADDR_UNSTRUCTURED_LONG_FORM - DOC_CLASS - DOC_TYPE - DOC_SUBTYPE - DOC_PRIMARY_IDENTIFIER - DOC_SECONDARY_IDENTIFIER - IND_DISPLAY_NAME - IND_GIVEN_NAME - IND_FAMILY_NAME - IND_MIDDLE_NAME - IND_DATE_OF_BIRTH - IND_NATIONALITY - ORG_REGISTERED_SUBDIVISION - ORG_REGISTERED_COUNTRY - ORG_REGISTRATION_NUMBER - ORG_REGISTRATION_NUMBER_TYPE - ORG_NAME securitySchemes: Api-Key: type: apiKey in: header name: api_key description: '' jwt: type: http scheme: bearer bearerFormat: JWT ````