openapi: 3.1.0
info:
  title: USCIS Case Status FOIA Requests API
  description: 'The USCIS Case Status API provides case status information to USCIS customers and their authorized representatives who require regular programmatic access to immigration case status information. Accepts a 13-character USCIS receipt number and returns the current status, form type, submission date, and historical case timeline in both English and Spanish. Accessed via the USCIS Torch API Program at developer.uscis.gov. Rate limits apply: 5 transactions per second, 1,000 requests per day.'
  version: '1.0'
  contact:
    name: USCIS Developer Support
    url: https://developer.uscis.gov/
  termsOfService: https://developer.uscis.gov/
servers:
- url: https://api-int.uscis.gov/case-status
  description: USCIS Sandbox/Integration Environment
tags:
- name: FOIA Requests
  description: Submit and manage FOIA and Privacy Act requests for Alien File records
paths:
  /requests:
    post:
      operationId: submitFoiaRequest
      summary: Submit FOIA or Privacy Act Request
      description: Create a new Freedom of Information Act (FOIA) or Privacy Act (PA) request for Alien File material. The request can be submitted about or on behalf of the subject of record. A unique Request Number is returned upon successful creation, which can be used to track the request status.
      tags:
      - FOIA Requests
      security:
      - OAuth2:
        - write:foia-requests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FoiaRequestBody'
            example:
              requestType: FOIA
              subjectFirstName: Jane
              subjectLastName: Doe
              subjectDateOfBirth: '1980-06-15'
              subjectCountryOfBirth: Mexico
              subjectAlienNumber: A123456789
              requesterName: Jane Doe
              requesterEmail: jane.doe@example.com
              requesterType: self
              descriptionOfRecords: Requesting complete Alien File including all immigration applications, approvals, and correspondence
              deliveryMethod: email
      responses:
        '201':
          description: FOIA request successfully submitted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoiaRequestCreatedResponse'
              example:
                requestNumber: USCIS-2024-001234
                status: Received
                submittedDate: '2024-01-15'
                estimatedCompletionDate: '2024-07-15'
                message: Your FOIA request has been received and assigned number USCIS-2024-001234
        '400':
          description: Bad request - invalid request body or missing required fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - invalid or expired OAuth 2.0 access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /requests/{requestNumber}:
    get:
      operationId: getFoiaRequestStatus
      summary: Get FOIA Request Status
      description: Check the current status of a submitted FOIA or Privacy Act request using the Request Number returned when the request was created. Returns the current processing status and any available updates.
      tags:
      - FOIA Requests
      security:
      - OAuth2:
        - read:foia-requests
      parameters:
      - name: requestNumber
        in: path
        required: true
        description: 'The FOIA request number returned when the request was submitted. Format: USCIS-YYYY-NNNNNN'
        schema:
          type: string
          pattern: ^USCIS-\d{4}-\d{6}$
        example: USCIS-2024-001234
      responses:
        '200':
          description: FOIA request status retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FoiaRequestStatusResponse'
              example:
                requestNumber: USCIS-2024-001234
                status: In Process
                requestType: FOIA
                submittedDate: '2024-01-15'
                lastUpdated: '2024-03-01'
                estimatedCompletionDate: '2024-07-15'
                subjectName: Jane Doe
                notes: Request is currently being processed by the National Records Center
        '401':
          description: Unauthorized - invalid or expired access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Request number not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      type: object
      description: Error response
      properties:
        error:
          type: string
          description: Error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          items:
            type: string
          description: Additional error details
    FoiaRequestStatusResponse:
      type: object
      description: Current status of a submitted FOIA request
      properties:
        requestNumber:
          type: string
          description: The FOIA request number
          example: USCIS-2024-001234
        status:
          type: string
          description: Current processing status
          enum:
          - Received
          - In Process
          - Awaiting Clarification
          - Records Located
          - Review in Progress
          - Response Sent
          - Closed
          - Appealed
          example: In Process
        requestType:
          type: string
          description: Type of request (FOIA or PrivacyAct)
        submittedDate:
          type: string
          format: date
          description: Date the request was submitted
        lastUpdated:
          type: string
          format: date
          description: Date of the most recent status update
        estimatedCompletionDate:
          type: string
          format: date
          description: Estimated completion date
        subjectName:
          type: string
          description: Name of the subject of the Alien File
        notes:
          type: string
          description: Additional processing notes or status details
    FoiaRequestCreatedResponse:
      type: object
      description: Response returned when a FOIA request is successfully submitted
      properties:
        requestNumber:
          type: string
          description: Unique identifier for the FOIA request
          example: USCIS-2024-001234
        status:
          type: string
          description: Initial status of the request
          example: Received
        submittedDate:
          type: string
          format: date
          description: Date the request was submitted
        estimatedCompletionDate:
          type: string
          format: date
          description: Estimated date for request completion
        message:
          type: string
          description: Confirmation message
    FoiaRequestBody:
      type: object
      description: Body for submitting a new FOIA or Privacy Act request
      required:
      - requestType
      - subjectFirstName
      - subjectLastName
      - requesterName
      - requesterEmail
      - requesterType
      - descriptionOfRecords
      properties:
        requestType:
          type: string
          description: Type of records request
          enum:
          - FOIA
          - PrivacyAct
        subjectFirstName:
          type: string
          description: First name of the subject of the Alien File
          example: Jane
        subjectLastName:
          type: string
          description: Last name of the subject of the Alien File
          example: Doe
        subjectMiddleName:
          type: string
          description: Middle name of the subject
        subjectDateOfBirth:
          type: string
          format: date
          description: Date of birth of the subject
          example: '1980-06-15'
        subjectCountryOfBirth:
          type: string
          description: Country of birth of the subject
          example: Mexico
        subjectAlienNumber:
          type: string
          description: USCIS Alien Registration Number (A-Number), if known
          pattern: ^A\d{8,9}$
          example: A123456789
        subjectReceiptNumber:
          type: string
          description: USCIS receipt number for related case, if known
        requesterName:
          type: string
          description: Full name of the person submitting the request
        requesterEmail:
          type: string
          format: email
          description: Email address for response delivery
        requesterType:
          type: string
          description: Relationship of requester to subject
          enum:
          - self
          - attorney
          - accredited_representative
          - family_member
          - other
        descriptionOfRecords:
          type: string
          description: Description of the records being requested
        deliveryMethod:
          type: string
          description: Preferred method for receiving records
          enum:
          - email
          - usps
          - portal
          default: email
        feeWaiverRequest:
          type: boolean
          description: Whether the requester is requesting a fee waiver
          default: false
        expeditedProcessingRequest:
          type: boolean
          description: Whether the requester is requesting expedited processing
          default: false
        expeditedProcessingJustification:
          type: string
          description: Justification for expedited processing, if requested
  securitySchemes:
    OAuth2:
      type: oauth2
      description: OAuth 2.0 Client Credentials flow. Obtain an access token from the USCIS token endpoint using your client_id and client_secret registered at developer.uscis.gov. Tokens expire after 1,800 seconds (30 minutes).
      flows:
        clientCredentials:
          tokenUrl: https://api-int.uscis.gov/oauth/accesstoken
          scopes:
            read:case-status: Read immigration case status information
externalDocs:
  description: USCIS Case Status API Documentation
  url: https://developer.uscis.gov/api/case-status