> ## 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. # Search for matchlist entries > Retrieve all matching entries for the search criteria. ## OpenAPI ````yaml /specs/fc-core-bundled_generated.yaml post /v2/search/matchlists 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/search/matchlists: parameters: - $ref: '#/components/parameters/X-Frankie-CustomerID' - $ref: '#/components/parameters/X-Frankie-CustomerChildID' - $ref: '#/components/parameters/X-Frankie-RequestID' - $ref: '#/components/parameters/X-Frankie-Channel' post: tags: - Matchlists summary: Search for matchlist entries description: Retrieve all matching entries for the search criteria. operationId: searchMatchlists parameters: - $ref: '#/components/parameters/limit' requestBody: content: application/json: schema: $ref: '#/components/schemas/Search-Matchlists-Request' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/Search-Matchlists-Matches-Response' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Error' '422': description: Unprocessable content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: Service Unavailable content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: 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-RequestID: name: X-Frankie-RequestID in: header description: GUID identifier for request required: true schema: type: string example: 82988375-1F9C-40C7-8543-ECCA0D94CC7C 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. 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: Search-Matchlists-Request: type: object description: Request to search for entries one or more matchlists required: - search properties: search: $ref: '#/components/schemas/Matchlists-Search-Criteria' filter: $ref: '#/components/schemas/Matchlists-Search-Filter' Search-Matchlists-Matches-Response: type: object description: >- All matches for a matchlist search. The entries contain the matchlist ID reference for looking up the matchlist details in matchlists. If there are no matches, empty lists are returned. Results will be ordered by descending entry match confidence for fuzzy searches, and otehrwise by matchlist and entry ID. required: - requestId - matchlists - entries - meta properties: requestId: $ref: '#/components/schemas/Request-ID' matchlists: type: object description: > List of matchlists with at least one matches entry in the entries list. Keyed on the matchlist ID which is also present in entries. additionalProperties: $ref: '#/components/schemas/Matchlist-Base' entries: type: array description: >- The list of matches that match the search criteria. Includes associated match strengths if the search was fuzzy. If no matches were found, the list will be empty. items: $ref: '#/components/schemas/Matchlists-Search-Matched-Entry' meta: type: object description: >- Meta information about the request and response that will be returned during a search operation required: - total - limit - count properties: total: type: integer description: >- The Total number of items that have been found for the search criteria limit: type: integer description: The current limit applied for this response count: type: integer description: The number of items that were returned in this response 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' Matchlists-Search-Criteria: type: object description: Specification of the matchlist entry attributes to search for. required: - attributes properties: type: $ref: '#/components/schemas/Search-Type' attributes: $ref: '#/components/schemas/Matchlist-Entry-Attributes' Matchlists-Search-Filter: type: object description: >- Specification of the matchlists to be searched. By default, only the default matchlist is searched. properties: listScope: type: string description: >- The lists to search in. If not provided, the search will be performed only in the default list. - DEFAULT: Search in the default list. - ALL: Search in all lists. - CUSTOM: Search in the lists provided in the searchLists parameter. default: DEFAULT enum: - DEFAULT - ALL - CUSTOM searchLists: type: array description: The IDs of matchlists to search in. Required if listScope is CUSTOM. items: type: string format: uuid description: The ID of the matchlist to search in. Request-ID: type: string example: 01HN9XHZN6MGXM9JXG50K59Q85 description: The unique request identifier for the API call made. Matchlist-Base: type: object description: Basic details about a matchlist, excluding metadata. properties: matchlistId: $ref: '#/components/schemas/Matchlist-ID' name: type: string description: Unique name identifying the matchlist. description: type: string description: Description of the matchlist. isDefault: description: Flag indicating whether this matchlist is the default list. type: boolean action: $ref: '#/components/schemas/Matchlist-Action' riskScore: type: number description: >- Risk score to assign if there is a match, unless overridden by risk configuration. Matchlists-Search-Matched-Entry: type: object description: An entry that matched the matchlist search criteria. required: - matchlistId - entry - attributes properties: matchlistId: type: string format: uuid description: Unique identifier of the matchlist to which this entry belongs. entry: $ref: '#/components/schemas/Matchlist-Entry-Base-With-Audit' attributes: type: array description: >- All attributes of the matchlist entry. At least one attribute will match to some extent. minItems: 1 items: $ref: '#/components/schemas/Matchlists-Search-Matched-Attribute' confidence: $ref: '#/components/schemas/Search-Confidence' Error-Base: type: object properties: errorCode: type: string errorMsg: type: string details: type: array items: $ref: '#/components/schemas/Issue' Search-Type: type: string description: |- Specifies the type of search to perform. - "EXACT": Returns only results that exactly match the search term. - "FUZZY": Returns results that are similar to the search term. enum: - EXACT - FUZZY Matchlist-Entry-Attributes: type: array description: All attributes associated with a matchlist entry. minItems: 1 items: $ref: '#/components/schemas/Matchlist-Entry-Attribute' Matchlist-ID: type: string format: uuid description: >- Matchlists are assigned an auto-generated UUID to ensure global uniqueness, represented as matchlistId. The matchlistId allows for precise modification when required. To create or modify a matchlist entry, set the matchlistId of the matchlist you wish to update in a matchlist entry request. example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 readOnly: true Matchlist-Action: type: string description: >- Default action recommended for a match. The action can be one of the following: - `BLOCK`: Recommended action is to block the entity. - `ALERT`: Recommended action is to create an alert for the entity. - `ALLOW`: Recommended action is to allow the entity. - `REVIEW`: Recommended action is to review the entity. - `NONE`: No action; only use the `riskFactor` if any. enum: - BLOCK - ALERT - ALLOW - REVIEW - NONE Matchlist-Entry-Base-With-Audit: type: object description: Basic details about a matchlist entry, including audit metadata. allOf: - $ref: '#/components/schemas/Matchlist-Entry-Base' - type: object properties: 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`. Matchlists-Search-Matched-Attribute: type: object description: An entry attribute that matched the matchlist search criteria. required: - attribute properties: attribute: $ref: '#/components/schemas/Matchlist-Entry-Attribute' confidence: $ref: '#/components/schemas/Search-Confidence' Search-Confidence: type: number format: float minimum: 0 maximum: 1 description: > Confidence level of the search result, represented as a number between 0 and 1. A higher value indicates greater confidence in the accuracy of the search result. 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: 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 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-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 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}$ securitySchemes: Api-Key: type: apiKey in: header name: api_key description: '' ````