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

# List the scopes on a recall for your product

> The confirmed scopes (deactivated ones included, marked ``is_active`` false) and the pending regulator-fed suggestions for one open recall on one product you own. 404 when the recall is not open or does not affect that product. Any role on the organization may read it.



## OpenAPI

````yaml /openapi/openapi-compliance.json get /compliance/api/v1/organizations/{organization_id}/recalls/{recall_id}/products/{gtin}/scopes
openapi: 3.1.0
info:
  title: Compliance API
  version: 1.0.0
  description: >
    Product safety and compliance data: recalls, hazards, and remedies; and an
    organization's FSMA 204 settings and record-retention minimums.


    ## Authentication


    All endpoints require an API key passed via the `X-API-Key` HTTP header,
    unless otherwise noted.


    ```

    X-API-Key: csb_<body>_<checksum>

    ```


    Generate API keys in **Settings > API Keys** in your dashboard, or via the
    Account API.

    Session-based (cookie) authentication is also accepted for browser-based
    access.


    ## Rate Limits


    | Tier        | Requests / minute | Requests / day |

    |-------------|-------------------|----------------|

    | Default     | 300               | 10,000         |

    | Custom      | Contact us        | Contact us     |


    Those windows are per key. Your plan also caps each organization per hour,
    across every key,

    login and session acting for it: 100 requests on Free (or while a
    subscription is lapsed),

    10,000 on Business. While a subscription is lapsed, any method other than
    `GET`, `HEAD` and

    `OPTIONS` returns `403`.


    Rate-limit headers are included on every response so callers can
    self-throttle without

    hitting our 429s ("informed governor"):


    - `RateLimit-Policy` — every active window, e.g. `300;w=60, 10000;w=86400`

    - `RateLimit-Limit` — quota for the **most-restrictive** currently-active
    window

    - `RateLimit-Remaining` — requests left in that window

    - `RateLimit-Reset` — seconds until that window resets (relative; clock-skew
    safe)


    Legacy `X-RateLimit-*` aliases are also emitted for back-compat.
    `X-RateLimit-Reset`

    keeps the absolute Unix-timestamp shape to avoid breaking existing
    consumers.


    When rate-limited, you receive `429 Too Many Requests` with a
    `retry_after_seconds` field

    in the error envelope and a `Retry-After` header.


    ## Pagination


    List endpoints return paginated results in this envelope:


    ```json

    {
      "data": [...],
      "pagination": {
        "page": 1,
        "page_size": 25,
        "total_count": 342,
        "total_pages": 14,
        "has_next": true,
        "has_previous": false
      }
    }

    ```


    Use `?page=2&page_size=50` query parameters. Maximum page size is 100.


    ## Error Responses


    All errors conform to [RFC 9457 Problem
    Details](https://www.rfc-editor.org/rfc/rfc9457)

    with `Content-Type: application/problem+json`:


    ```json

    {
      "type": "https://closient.com/docs/errors/not_found",
      "title": "Not Found",
      "status": 404,
      "detail": "The requested resource was not found.",
      "error_code": "not_found",
      "retryable": false,
      "timestamp": "2026-03-31T12:00:00+00:00"
    }

    ```


    Common error codes: `unauthorized` (401), `forbidden` (403), `not_found`
    (404),

    `validation_error` (422), `rate_limited` (429), `internal_error` (500).


    ## Versioning and Deprecation


    Every response from an operation in this document carries
    `Closient-API-Version` (its `info.version`).

    An operation marked `deprecated` answers with `Deprecation: @<Unix seconds>`

    ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745)), `Sunset: <HTTP-date>`
    once a

    retirement date is set ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)),
    and

    `Link` entries for `rel="deprecation"`, `rel="sunset"` and
    `rel="successor-version"`.

    After its sunset it answers `410 Gone` naming the replacement. Policy:

    https://docs.closient.com/api-versioning
  termsOfService: https://www.closient.com/terms/
servers:
  - url: https://www.closient.com
security: []
tags:
  - name: Compliance
    description: Product recall and safety queries.
  - name: FSMA configuration
    description: >-
      An organization's FSMA 204 designated contact, lot-code settings and
      retention minimums.
  - name: FSMA 204 exemptions and harvest areas
    description: >-
      The § 1.1305 exemptions an organization declares and the harvest areas its
      farms record.
  - name: EPCIS capture configuration
    description: >-
      An organization's EPCIS capture keys, serial-number pools and public-page
      visibility.
  - name: FSMA recordkeeping
    description: >-
      An organization's FSMA 204 trading partners, reference documents,
      traceability plan versions and mock FDA audits.
externalDocs:
  description: Closient Documentation
  url: https://docs.closient.com
paths:
  /compliance/api/v1/organizations/{organization_id}/recalls/{recall_id}/products/{gtin}/scopes:
    get:
      tags:
        - Recall review
      summary: List the scopes on a recall for your product
      description: >-
        The confirmed scopes (deactivated ones included, marked ``is_active``
        false) and the pending regulator-fed suggestions for one open recall on
        one product you own. 404 when the recall is not open or does not affect
        that product. Any role on the organization may read it.
      operationId: list_recall_scopes_for_product
      parameters:
        - in: path
          name: organization_id
          schema:
            description: Identifier of the organization.
            format: shortuuid
            maxLength: 22
            minLength: 22
            pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
            title: Organization Id
            type: string
          required: true
          description: Identifier of the organization.
        - in: path
          name: recall_id
          schema:
            description: Identifier of the recall.
            format: shortuuid
            maxLength: 22
            minLength: 22
            pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
            title: Recall Id
            type: string
          required: true
          description: Identifier of the recall.
        - in: path
          name: gtin
          schema:
            description: GTIN of your affected product.
            format: gtin
            maxLength: 14
            minLength: 8
            pattern: ^[0-9]{8}$|^[0-9]{12,14}$
            title: Gtin
            type: string
          required: true
          description: GTIN of your affected product.
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecallScopesOut'
        '400':
          description: Bad Request
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '401':
          description: Unauthorized
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '405':
          description: Method Not Allowed
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '422':
          description: Unprocessable Content
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
        '429':
          description: Too Many Requests
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorOut'
      security:
        - APIKeyHeaderAuth: []
        - OAuthTokenAuth: []
        - CookieGatedSessionAuth: []
components:
  schemas:
    RecallScopesOut:
      description: Every scope on one (recall, product) pair.
      examples:
        - enhanced: true
          gtin: '09520123456788'
          recall_id: m1n2o3p4q5r6s7t8u9v0wX
          scopes: []
          suggested_scopes: []
      properties:
        recall_id:
          description: Identifier of the recall.
          format: shortuuid
          maxLength: 22
          minLength: 22
          pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
          title: Recall Id
          type: string
        gtin:
          description: GTIN of your product.
          title: Gtin
          type: string
        enhanced:
          description: >-
            Whether the product is on enhanced resolution (authoring requires
            it).
          title: Enhanced
          type: boolean
        scopes:
          description: >-
            Confirmed scopes, active ones first. Deactivated scopes are
            included, with is_active false.
          items:
            $ref: '#/components/schemas/RecallScopeReviewOut'
          title: Scopes
          type: array
        suggested_scopes:
          description: Regulator-fed suggestions still awaiting confirm or dismiss.
          items:
            $ref: '#/components/schemas/RecallScopeReviewOut'
          title: Suggested Scopes
          type: array
      required:
        - recall_id
        - gtin
        - enhanced
        - scopes
        - suggested_scopes
      title: RecallScopesOut
      type: object
    ErrorOut:
      description: |-
        RFC 9457 Problem Details response.

        All API errors are returned in this format with Content-Type:
        application/problem+json.
      examples:
        - detail: The requested resource was not found.
          error_code: not_found
          retryable: false
          status: 404
          timestamp: '2026-03-31T12:00:00+00:00'
          title: Not Found
          type: https://closient.com/docs/errors/not_found
        - detail: Validation error.
          details:
            - loc:
                - body
                - name
              msg: Field required
              type: missing
          error_code: validation_error
          retryable: false
          status: 422
          timestamp: '2026-03-31T12:00:00+00:00'
          title: Validation Error
          type: https://closient.com/docs/errors/validation_error
        - detail: Rate limit exceeded. Please try again later.
          error_code: rate_limited
          retry_after: 31
          retryable: true
          status: 429
          timestamp: '2026-03-31T12:00:00+00:00'
          title: Rate Limited
          type: https://closient.com/docs/errors/rate_limited
      properties:
        type:
          description: URI reference identifying the error type.
          title: Type
          type: string
        title:
          description: Short human-readable summary of the error.
          title: Title
          type: string
        status:
          description: HTTP status code.
          title: Status
          type: integer
        detail:
          description: Human-readable explanation of this specific occurrence.
          title: Detail
          type: string
        error_code:
          description: Machine-readable error code (e.g. not_found, unauthorized).
          title: Error Code
          type: string
        retryable:
          default: false
          description: Whether retrying the same request can succeed.
          title: Retryable
          type: boolean
        timestamp:
          description: ISO 8601 timestamp of when the error occurred.
          title: Timestamp
          type: string
        retry_after:
          anyOf:
            - type: integer
            - type: 'null'
          description: Seconds to wait before retrying (when applicable).
          title: Retry After
        owner_action_required:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Whether the error requires account owner intervention.
          title: Owner Action Required
        details:
          description: Additional context (validation errors, etc.).
          title: Details
      required:
        - type
        - title
        - status
        - detail
        - error_code
        - timestamp
      title: ErrorOut
      type: object
    RecallScopeReviewOut:
      description: A scope on a recall for one of your products, confirmed or suggested.
      examples:
        - date_ai: ''
          id: s1c2o3p4e5i6d7s8h9o0rt
          is_active: true
          kind: LOT_LIST
          note: ''
          status: CONFIRMED
          values:
            - L2405A
            - L2405B
      properties:
        id:
          description: >-
            URL-safe 22-character shortuuid encoding of the row's UUID primary
            key. Stable across the row's lifetime; suitable for sharing in URLs,
            log lines, and external SDK clients. Accepted on input as either the
            shortuuid form or the canonical UUID form
            (``xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx``).
          format: shortuuid
          maxLength: 22
          minLength: 22
          pattern: ^[23456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{22}$
          title: Id
          type: string
        kind:
          description: >-
            ``DATE_WINDOW``, ``LOT_LIST``, ``SERIAL_SET`` or
            ``PRODUCTION_SITE``.
          title: Kind
          type: string
        status:
          description: >-
            ``CONFIRMED`` scopes narrow the live recall verdict. ``SUGGESTED``
            is a regulator-fed draft that narrows nothing until you confirm it.
          title: Status
          type: string
        is_active:
          description: False once deactivated or dismissed; kept for audit, never deleted.
          title: Is Active
          type: boolean
        values:
          description: Lot, serial or production-site GLN values; empty for a date window.
          items:
            type: string
          title: Values
          type: array
        date_ai:
          description: Printed-date AI (15 or 17) of a date window; empty otherwise.
          title: Date Ai
          type: string
        pack_date_start:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: Inclusive start of a date window.
          title: Pack Date Start
        pack_date_end:
          anyOf:
            - format: date
              type: string
            - type: 'null'
          description: Inclusive end of a date window.
          title: Pack Date End
        note:
          description: Free-text note on the scope.
          title: Note
          type: string
        confidence_score:
          anyOf:
            - type: number
            - type: 'null'
          description: >-
            Extraction confidence from 0.0 to 1.0 for a suggestion; null for a
            scope you authored.
          title: Confidence Score
      required:
        - id
        - kind
        - status
        - is_active
        - values
        - date_ai
        - note
      title: RecallScopeReviewOut
      type: object
  securitySchemes:
    APIKeyHeaderAuth:
      type: apiKey
      in: header
      name: X-API-Key
    OAuthTokenAuth:
      type: http
      scheme: bearer
    CookieGatedSessionAuth:
      type: apiKey
      in: cookie
      name: sessionid

````

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