> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gominerva.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Read a record

> Reads one working-set record or allowlist entry by `record_uid`. Requires an admin API key, the **Admin (tenant-wide)** key type. The `x-user-token` scheme is the Minerva dashboard session token.



## OpenAPI

````yaml /api-reference/admin-api.json get /custom-lists/v2/organizations/{orgId}/{listId}/records/{recordId}
openapi: 3.0.0
info:
  version: 1.0.0
  title: MinervaAI Admin API
  description: Admin endpoints for the Minerva application suite.
servers:
  - url: https://api.gominerva.com
    description: The production API server for Minerva.
security:
  - ApiKeyAuth: []
tags: []
paths:
  /custom-lists/v2/organizations/{orgId}/{listId}/records/{recordId}:
    get:
      tags:
        - Custom Lists
      summary: Read a record
      description: >-
        Reads one working-set record or allowlist entry by `record_uid`.
        Requires an admin API key, the **Admin (tenant-wide)** key type. The
        `x-user-token` scheme is the Minerva dashboard session token.
      parameters:
        - in: path
          name: orgId
          required: true
          schema:
            type: string
          description: >-
            The organization (tenant) id. Must equal the tenant of the admin
            key.
        - in: path
          name: listId
          required: true
          schema:
            type: string
          description: The custom list id.
        - in: path
          name: recordId
          required: true
          schema:
            type: string
          description: The record id (`id` of a record, not its `record_uid`).
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomListRecordResponse'
              examples:
                allowlist-entry:
                  summary: An allowlist entry with a captured record.
                  value:
                    data:
                      record_uid: al_be8ed741b581485c4d5668ee
                      status: active
                      name: NatWest Bank
                      aliases:
                        - NatWest
                        - National Westminster Bank
                      entity_type: organization
                      countries:
                        - GB
                      scope: known_records
                      covers:
                        - category: sanctions
                          source: OFAC SDN
                          record_name: Natwest Logistics LLC
                          added_by:
                            type: user
                            id: u_8d1e
                            name: A. Analyst
                          added_at: '2026-11-14T10:02:00Z'
                          record_ref:
                            fingerprint: >-
                              sha256:9341f26c078565780b5157f527395fb0bb82fc7f45e36a44aa871c579d5c97da
                            record_aliases:
                              - NWL LLC
                              - Natwest Logistics
                      match_rules: null
                      reason: Payee is NatWest Bank, the UK clearing bank
                      expires_at: '2027-11-14T00:00:00Z'
                      added_by:
                        type: user
                        id: u_8d1e
                        name: A. Analyst
                      added_at: '2026-11-14T10:02:00Z'
                      custom_fields: {}
                      working_set_revision: 42
                screening-record:
                  summary: The record with the replacement fields.
                  value:
                    data:
                      id: 8e7f6a5b-4c5d-4e2f-9a8b-aca9d8e7f6a5
                      tenant_id: 123e4567-e89b-12d3-a456-426614174000
                      list_id: 3f2a1b0c-9d8e-4f7a-8b6c-5d4e3f2a1b0c
                      record_uid: cl-0001
                      status: active
                      entity_type: organization
                      name: Acme Trading Ltd
                      aliases:
                        - Acme Trading Limited
                        - Acme Trading
                      countries:
                        - GB
                      reason: Debanked after relationship review
                      notes: Do not onboard without a compliance sign-off
                      custom_fields:
                        source: manual
                      record_hash: ''
                      created_at: '2026-11-05T01:18:55.867Z'
                      updated_at: '2026-11-05T02:15:09.334Z'
        '403':
          description: >-
            No credentials were sent; the API key was revoked, has expired, or
            its application is deactivated (`API-key authentication was
            denied.`); the key is not an admin application key (**Workspace
            scoped** and **Tenant scoped** keys are refused); it belongs to
            another organization; or its creator is no longer an owner or admin.
            For a user token, the user is not a member, or is not an owner or
            admin on a write. If the tenant is not entitled to custom lists, the
            body is a JSON `CustomListError` with `error: not_enabled` (`Custom
            lists are not enabled for this tenant.`); every other 403 is plain
            text. Branch on `Content-Type`.
          content:
            text/plain:
              schema:
                type: string
                example: 'Missing Authorization: Api-Key or x-api-key header.'
            application/json:
              schema:
                $ref: '#/components/schemas/CustomListError'
              examples:
                not-enabled:
                  summary: Tenant not entitled.
                  value:
                    error: not_enabled
                    message: Custom lists are not enabled for this tenant.
        '404':
          description: >-
            Custom list management is not enabled (`Custom list management is
            not enabled.`); the list, record, upload, job or workspace is not in
            this organization; or the application API key (`mrva-…`) is unknown
            (`API-key authentication was denied.`).
          content:
            text/plain:
              schema:
                type: string
                example: Custom list management is not enabled.
        '503':
          description: >-
            The authentication service is temporarily unavailable
            (`Authentication service is unavailable.`). Nothing was changed;
            retry with backoff.
          content:
            text/plain:
              schema:
                type: string
                example: Authentication service is unavailable.
      security:
        - AdminApiKeyAuth: []
        - UserTokenAuth: []
components:
  schemas:
    CustomListRecordResponse:
      type: object
      description: >-
        `{ data: CustomListRecord }` for a screening list, or `{ data:
        AllowlistEntry }` for an allowlist. On an allowlist write, `data` also
        carries `working_set_revision`, `warnings` and, when published,
        `published_version_id`.
      properties:
        data:
          oneOf:
            - $ref: '#/components/schemas/CustomListRecord'
            - $ref: '#/components/schemas/AllowlistEntry'
      required:
        - data
    CustomListError:
      type: object
      properties:
        error:
          type: string
          description: >-
            Machine-readable code, e.g. `validation_failed`, `limit_exceeded`,
            `conflict`, `not_enabled`, `upload_capacity_exceeded`,
            `upload_request_timeout`. Allowlist codes:
            `allowlist_field_not_allowed`, `purpose_immutable`,
            `record_uid_not_allowed`, `allowlist_reserved_field`,
            `allowlist_identity_immutable`, `allowlist_scope_not_allowed`,
            `allowlist_match_rules_not_allowed`,
            `allowlist_expiry_out_of_range`,
            `allowlist_subject_is_listed_party`, `resolve_requires_live_entry`,
            `allowlist_not_enabled`, `not_found`, `allowlist_entry_exists`,
            `allowlist_similar_entry_exists`, `allowlist_entry_cap_exceeded`,
            `not_an_allowlist`, `record_not_on_match`, `no_uncovered_records`,
            `country_unresolved`. Branch on `error`; `message` is human-readable
            and may change.
        message:
          type: string
        limit:
          type: string
          description: >-
            For `limit_exceeded`: the entitlement limit, e.g.
            `maxRecordsPerList`.
        max:
          type: integer
          description: 'For `limit_exceeded`: the configured maximum.'
        retryable:
          type: boolean
        data:
          type: object
          additionalProperties: true
          description: >-
            Extra detail for some allowlist codes: `{record_uid, status}` for
            `allowlist_entry_exists`, `{record_uid, name}` for
            `allowlist_similar_entry_exists`, and `{max_expires_at}` for
            `allowlist_expiry_out_of_range`.
      additionalProperties: true
    CustomListRecord:
      type: object
      properties:
        id:
          type: string
        tenant_id:
          type: string
        list_id:
          type: string
        record_uid:
          type: string
        status:
          type: string
          enum:
            - active
            - archived
        entity_type:
          type: string
          enum:
            - individual
            - organization
            - unknown
        name:
          type: string
        aliases:
          type: array
          items:
            type: string
        countries:
          type: array
          items:
            type: string
        date_of_birth:
          type: string
        date_of_incorporation:
          type: string
        reason:
          type: string
        notes:
          type: string
        custom_fields:
          type: object
          additionalProperties:
            type: string
        record_hash:
          type: string
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - tenant_id
        - list_id
        - record_uid
        - status
        - entity_type
        - name
        - aliases
        - countries
        - custom_fields
        - record_hash
        - created_at
        - updated_at
    AllowlistEntry:
      type: object
      description: >-
        An allowlist entry. Returned in `data` by the record endpoints when the
        list's `purpose` is `allowlist`.
      properties:
        id:
          type: string
          description: Minerva's ID for the record.
        list_id:
          type: string
        record_uid:
          type: string
          description: >-
            Derived by Minerva from the customer's identity (name, entity type,
            dates, countries and identifiers). Keep it to address the entry
            later. Changing any of those fields on `PATCH` returns `400` with
            `error: allowlist_identity_immutable`: archive the entry and create
            a new one instead.
          example: al_be8ed741b581485c4d5668ee
        status:
          type: string
          enum:
            - active
            - archived
        name:
          type: string
          description: >-
            The customer's name: who you know them to be, not the watchlist
            record's name. Required.
          example: NatWest Bank
        aliases:
          type: array
          items:
            type: string
          description: >-
            Other spellings of the customer's name. A screened name is accepted
            when it matches `name` or any alias under the match rules.
          example:
            - NatWest
            - National Westminster Bank
        entity_type:
          type: string
          enum:
            - individual
            - organization
          nullable: true
          description: '`null` when the entry was saved without a type.'
        date_of_birth:
          type: string
          nullable: true
          description: >-
            `YYYY-MM-DD`. When set, a screened subject with a different date of
            birth is not accepted.
        date_of_incorporation:
          type: string
          nullable: true
          description: >-
            `YYYY-MM-DD`. When set, a screened subject with a different date is
            not accepted.
        countries:
          type: array
          items:
            type: string
          description: >-
            ISO 3166-1 alpha-2 codes. When set, a screened subject from another
            country is not accepted.
          example:
            - GB
        identifiers:
          $ref: '#/components/schemas/AllowlistIdentifiers'
        customer_ids:
          type: array
          items:
            type: string
          description: >-
            Your customer IDs for this entry. Returned here; never echoed in
            screening annotations.
        scope:
          type: string
          enum:
            - known_records
            - source
            - category
          description: >-
            Which matches the entry can mark. `known_records` (default): only
            the records in `covers`. `source`: any record from the sources in
            `sources`. `category`: any record in the feeds in `categories`. The
            workspace's `allowlist.feedPolicy` decides which scopes each feed
            allows; Sanctions always allows `known_records` only.
          example: known_records
        covers:
          type: array
          description: >-
            Required and non-empty when `scope` is `known_records`; rejected
            otherwise.
          items:
            $ref: '#/components/schemas/AllowlistCover'
        sources:
          type: array
          items:
            type: string
          description: >-
            Required when `scope` is `source`; rejected otherwise. Not allowed
            for Sanctions sources.
        categories:
          type: array
          items:
            type: string
            enum:
              - pep
              - news
              - criminal
              - legal
          description: >-
            Required when `scope` is `category`; rejected otherwise. `sanctions`
            and `internal` are never allowed.
        match_rules:
          $ref: '#/components/schemas/AllowlistMatchRules'
        reason:
          type: string
          description: >-
            Why this customer is not the listed party. Required; shown to
            analysts on every match the entry marks.
          example: Payee is NatWest Bank, the UK clearing bank
        expires_at:
          type: string
          format: date-time
          description: >-
            When the entry stops marking matches. A match screened at or after
            this time alerts with `allowlist.status: entry_expired`.
        review_by:
          type: string
          nullable: true
          description: Optional date to review the entry before it expires.
        custom_fields:
          type: object
          additionalProperties:
            type: string
          description: >-
            Your own string fields. The reserved names `record_ref`,
            `fingerprint`, `record_key` and any `_added_*` key return `400` with
            `error: allowlist_reserved_field`.
        added_by:
          $ref: '#/components/schemas/AllowlistActor'
        added_at:
          type: string
          format: date-time
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        working_set_revision:
          type: integer
          description: 'Write responses only: the working-set revision after this write.'
        published_version_id:
          type: string
          description: >-
            Write responses only, and only when `publish` was `true`: the
            version the write was published in.
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/AllowlistWarning'
          description: Write responses only. Empty when there is nothing to warn about.
      required:
        - record_uid
        - status
        - name
        - scope
        - reason
        - expires_at
        - added_by
        - added_at
    AllowlistIdentifiers:
      type: object
      description: >-
        Optional identifiers. When set, a screened subject that carries a
        different value is not accepted (`matched_on.comparison[].result:
        different`).
      properties:
        company_number:
          type: string
          nullable: true
        national_id:
          type: string
          nullable: true
    AllowlistCover:
      allOf:
        - $ref: '#/components/schemas/AllowlistCoverInput'
        - type: object
          properties:
            record_ref:
              type: object
              readOnly: true
              description: >-
                Set by Minerva, never accepted on input. Present once the record
                has been captured, for example by adding the customer from a
                match. `fingerprint` identifies the record content the entry was
                approved against: if the record later changes, the match alerts
                again with `allowlist.status: record_changed`.
              properties:
                fingerprint:
                  type: string
                  example: >-
                    sha256:9341f26c078565780b5157f527395fb0bb82fc7f45e36a44aa871c579d5c97da
                record_aliases:
                  type: array
                  items:
                    type: string
                  example:
                    - NWL LLC
                    - Natwest Logistics
            added_by:
              $ref: '#/components/schemas/AllowlistActor'
            added_at:
              type: string
              format: date-time
    AllowlistMatchRules:
      type: object
      nullable: true
      description: >-
        An optional per-entry override of how closely a screened name must match
        the entry. `null` uses the workspace's `allowlist.matchRules.default`.
        Minerva never applies an override looser than the workspace allows: on
        Sanctions it is capped at the workspace level, and
        `matched_on.match_rules.source` on a match tells you which level
        applied.
      properties:
        level:
          type: string
          enum:
            - exact
            - standard
            - tolerant
      required:
        - level
      example:
        level: exact
    AllowlistActor:
      type: object
      description: >-
        Who added an entry or a cover. `type` is `application` for a change made
        with an admin application key, otherwise `user`.
      properties:
        type:
          type: string
          enum:
            - user
            - application
        id:
          type: string
        name:
          type: string
      required:
        - type
        - id
      example:
        type: user
        id: u_8d1e
        name: A. Analyst
    AllowlistWarning:
      type: object
      description: >-
        A non-blocking warning on a successful write.
        `allowlist_subject_is_listed_party`: the entry's name or an alias equals
        the name of a covered non-Sanctions record (on Sanctions this is a
        `400`). `allowlist_mode_off`: the workspace's allowlist mode is `off`,
        so the list has no effect yet.
      properties:
        code:
          type: string
          enum:
            - allowlist_subject_is_listed_party
            - allowlist_mode_off
        record_uid:
          type: string
        message:
          type: string
      required:
        - code
    AllowlistCoverInput:
      type: object
      description: >-
        One watchlist record the entry covers when `scope` is `known_records`.
        Copy `category`, `source` and `record_name` from the potential match.
      properties:
        category:
          type: string
          enum:
            - sanctions
            - pep
            - news
            - criminal
            - legal
          description: The feed of the record. `internal` is never allowed.
        source:
          type: string
          description: >-
            The source list, as it appears in `checklist.hits_info[].source`,
            e.g. `OFAC SDN`.
          example: OFAC SDN
        record_name:
          type: string
          description: The record's name on that source.
          example: Natwest Logistics LLC
      required:
        - category
        - source
        - record_name
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Admin API key for authentication. Manage API keys in the Minerva
        dashboard under Administration > Developers.
    AdminApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        An admin application key: `Authorization: Api-Key <token>` (or legacy
        `x-api-key`). Only tenant owners and admins can create one. Standard
        keys are refused with 403 on workspace management and tenant
        configuration routes.
    UserTokenAuth:
      type: apiKey
      in: header
      name: x-user-token
      description: Firebase user token for authentication

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.