openapi: 3.0.3
info:
  title: ImmigrationTimes.org API
  description: |
    Free, open API for US immigration processing time data. Covers 44 USCIS forms
    with daily historical data since March 2022, DOL PERM labor certification
    processing times, and State Department visa bulletin priority dates.

    All data is sourced from official US government agencies (USCIS, DOL, State Department)
    and updated daily.

    **No authentication required.** All endpoints are publicly accessible.

    **License:** Data is available under [CC-BY-4.0](https://creativecommons.org/licenses/by/4.0/).
    Please attribute ImmigrationTimes.org when using this data.
  version: "1.0.0"
  contact:
    name: ImmigrationTimes.org
    url: https://immigrationtimes.org
    email: support@immigrationtimes.org
  license:
    name: CC-BY-4.0
    url: https://creativecommons.org/licenses/by/4.0/

servers:
  - url: https://immigrationtimes.org
    description: Production

paths:
  /api/v1/forms.json:
    get:
      operationId: listForms
      summary: List all USCIS forms
      description: |
        Returns a list of all 44 tracked USCIS forms, including form descriptions,
        last updated dates, office counts, and links to per-form pages and API
        endpoints. Most forms carry current processing-time data; a few are tracked
        for historical continuity after USCIS stopped publishing times for them.
      tags:
        - USCIS Processing Times
      responses:
        "200":
          description: List of all tracked USCIS forms
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FormList"
              example:
                generated: "2026-04-02T09:26:47.676Z"
                forms:
                  - form: "I-485"
                    slug: "i-485"
                    description: "Application to Register Permanent Residence or Adjust Status"
                    last_updated: "2026-03-16"
                    offices: 97
                    url: "https://immigrationtimes.org/forms/i-485/"
                    api: "https://immigrationtimes.org/api/v1/i-485.json"
                  - form: "I-130"
                    slug: "i-130"
                    description: "Petition for Alien Relative"
                    last_updated: "2026-03-16"
                    offices: 8
                    url: "https://immigrationtimes.org/forms/i-130/"
                    api: "https://immigrationtimes.org/api/v1/i-130.json"

  /api/v1/{formSlug}.json:
    get:
      operationId: getFormData
      summary: Get processing time data for a specific form
      description: |
        Returns current processing time data for a specific USCIS form, including
        aggregate statistics and per-office breakdowns with subtypes. Data includes
        lower and upper processing time ranges in months, publication dates, and
        service request dates.
      tags:
        - USCIS Processing Times
      parameters:
        - $ref: "#/components/parameters/formSlug"
      responses:
        "200":
          description: Processing time data for the requested form
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FormData"
              example:
                form: "I-485"
                slug: "i-485"
                last_updated: "2026-03-16"
                processing_time:
                  avg_lower_months: 13.8
                  avg_upper_months: 28.8
                  min_months: 5
                  max_months: 51
                offices:
                  - office_code: "ABQ"
                    subtype: "131A-FAM"
                    subtype_info: "Family-Based adjustment applications"
                    lower_months: 11
                    upper_months: 20
                    publication_date: "2026-03-16"
                    service_request_date: "2024-08-16"
        "404":
          description: Form not found

  /api/v1/{formSlug}.csv:
    get:
      operationId: getFormCsv
      summary: Download processing time data as CSV
      description: |
        Returns the full historical processing time dataset for a specific USCIS form
        in CSV format. Includes all snapshots since March 2022, with columns for date,
        office code, form subtype, subtype description, min/max months, and form type.

        Note: the second column header was renamed `service_center` to `office_code`
        on 2026-06-13 to match the JSON surface and the schema (the column carries
        field-office codes for field-office forms, not only service centers). Values
        and column order are unchanged.
      tags:
        - USCIS Processing Times
      parameters:
        - $ref: "#/components/parameters/formSlug"
      responses:
        "200":
          description: CSV file with historical processing time data
          content:
            text/csv:
              schema:
                type: string
              example: |
                date,office_code,form_subtype,subtype_info,min_months,max_months,form_type
                2026-03-16,ABQ,131A-FAM,Family-Based adjustment applications,11,20,I-485
                2026-03-16,AGA,131A-FAM,Family-Based adjustment applications,10.5,21.5,I-485
        "404":
          description: Form not found

  /api/v1/perm.json:
    get:
      operationId: getPermData
      summary: Get DOL PERM processing times
      description: |
        Returns current and historical DOL PERM labor certification processing time data,
        including average processing days, analyst review queue dates, audit review queue
        dates, and reconsideration queue dates. Data is sourced from the DOL FLAG system.
      tags:
        - DOL PERM
      responses:
        "200":
          description: PERM processing time data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PermData"
              example:
                source: "DOL FLAG System"
                last_updated: "2026-03-30"
                current:
                  avg_processing_days: 503
                  avg_processing_month: "February 2026"
                  analyst_review_queue: "November 2024"
                  audit_review_queue: "June 2025"
                  reconsideration_queue: "September 2025"
                history:
                  - snapshot_date: "2026-03-30"
                    avg_processing_days: 503
                    avg_processing_month: "February 2026"
                    analyst_review_queue: "November 2024"
                    audit_review_queue: "June 2025"
                    reconsideration_queue: "September 2025"
                attribution: "ImmigrationTimes.org/perm/"

  /api/v1/perm.csv:
    get:
      operationId: getPermCsv
      summary: Download PERM data as CSV
      description: |
        Returns the full historical DOL PERM processing time dataset in CSV format.
        Includes all snapshots with columns for snapshot date, average processing days,
        processing month, and queue dates.
      tags:
        - DOL PERM
      responses:
        "200":
          description: CSV file with PERM processing time history
          content:
            text/csv:
              schema:
                type: string
              example: |
                snapshot_date,avg_processing_days,avg_processing_month,analyst_review_queue,audit_review_queue,reconsideration_queue
                2026-03-30,503,February 2026,November 2024,June 2025,September 2025

  /api/v1/visa-bulletin.json:
    get:
      operationId: getVisaBulletinData
      summary: Get visa bulletin priority dates
      description: |
        Returns historical State Department visa bulletin priority date data for all
        employment-based and family-based preference categories. Covers 15 categories
        across 5 countries (All Chargeability, China, India, Mexico, Philippines) with
        both filing date and final action date tables. Data spans from May 2023 to present.
      tags:
        - Visa Bulletin
      responses:
        "200":
          description: Visa bulletin priority date data
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/VisaBulletinData"
              example:
                generated: "2026-04-02T09:26:56.170Z"
                bulletin_count: 36
                date_range:
                  oldest: "2023-05-01"
                  newest: "2026-04-01"
                records:
                  - bulletin_date: "2026-04-01"
                    table_type: "filing_date"
                    preference: "EB-1"
                    country: "all"
                    priority_date: "C"
                  - bulletin_date: "2026-04-01"
                    table_type: "filing_date"
                    preference: "EB-1"
                    country: "china"
                    priority_date: "2023-12-01"

  /api/v1/visa-bulletin.csv:
    get:
      operationId: getVisaBulletinCsv
      summary: Download visa bulletin data as CSV
      description: |
        Returns the full historical visa bulletin priority date dataset in CSV format.
        Includes all bulletins with columns for bulletin date, table type (filing_date
        or final_action), preference category, country, and priority date.
      tags:
        - Visa Bulletin
      responses:
        "200":
          description: CSV file with visa bulletin priority date history
          content:
            text/csv:
              schema:
                type: string
              example: |
                bulletin_date,table_type,preference,country,priority_date
                2026-04-01,filing_date,EB-1,all,C
                2026-04-01,filing_date,EB-1,china,2023-12-01

components:
  parameters:
    formSlug:
      name: formSlug
      in: path
      required: true
      description: |
        URL slug for the form (lowercase, e.g. `i-485`, `n-400`, `i-129f`).
        See `/api/v1/forms.json` for the full list of valid slugs.
      schema:
        type: string
        pattern: "^[a-z]-[a-z0-9]+(-[a-z0-9]+)*$"
      examples:
        i485:
          value: "i-485"
          summary: "I-485 (Adjustment of Status)"
        i130:
          value: "i-130"
          summary: "I-130 (Petition for Alien Relative)"
        n400:
          value: "n-400"
          summary: "N-400 (Naturalization)"
        i765:
          value: "i-765"
          summary: "I-765 (Employment Authorization)"

  schemas:
    FormList:
      type: object
      required:
        - generated
        - forms
      properties:
        generated:
          type: string
          format: date-time
          description: Timestamp when this data was generated
        forms:
          type: array
          items:
            $ref: "#/components/schemas/FormSummary"

    FormSummary:
      type: object
      required:
        - form
        - slug
        - description
        - last_updated
        - offices
        - url
        - api
      properties:
        form:
          type: string
          description: USCIS form number (e.g. "I-485")
        slug:
          type: string
          description: URL slug (e.g. "i-485")
        description:
          type: string
          description: Official form name/description
        last_updated:
          type: string
          format: date
          description: Date of the most recent USCIS data publication
        offices:
          type: integer
          description: Number of USCIS offices/service centers reporting data for this form
        url:
          type: string
          format: uri
          description: URL of the form's page on ImmigrationTimes.org
        api:
          type: string
          format: uri
          description: URL of the form's JSON API endpoint

    FormData:
      type: object
      required:
        - form
        - slug
        - last_updated
        - status
        - processing_time
        - office_aggregates
        - offices
        - source
        - attribution
      properties:
        form:
          type: string
          description: USCIS form number
        slug:
          type: string
          description: URL slug
        last_updated:
          type: string
          format: date
          description: Date of the most recent USCIS data publication
        status:
          type: string
          enum:
            - ok
            - no_data_published
            - last_known_stale
          description: >-
            Data availability for this form. "ok" when USCIS currently publishes
            processing times for the form; "no_data_published" when the form is
            tracked for historical continuity but USCIS has never published current
            numeric times; "last_known_stale" when the current USCIS publication omits
            numeric times and the page shows the last prior numeric publication.
        processing_time:
          $ref: "#/components/schemas/ProcessingTimeSummary"
        office_aggregates:
          type: array
          description: >-
            Page-display office-level aggregates. These rows mirror the office/service-center
            comparison layer on form pages: when an office has subtypes with both lower
            and upper bounds, both endpoints are averaged over that same subtype population;
            when all lower bounds are omitted, the row is an upper-only average. Use this
            array to reconcile processing_time min/max with the public page/table range.
          items:
            $ref: "#/components/schemas/OfficeAggregate"
        offices:
          type: array
          description: >-
            Raw current USCIS office/subtype rows. These preserve source values verbatim
            and can include subtype upper bounds outside the page-display office aggregate
            range. For the public page/table summary layer, use office_aggregates.
          items:
            $ref: "#/components/schemas/OfficeProcessingTime"
        source:
          type: string
          description: Data source identifier (always "USCIS" for these endpoints)
        attribution:
          type: string
          description: Attribution path for this form's data (e.g. "ImmigrationTimes.org/forms/i-130/")

    ProcessingTimeSummary:
      type: object
      required:
        - avg_lower_months
        - avg_upper_months
        - min_months
        - max_months
      description: >-
        Aggregate processing-time statistics for the form. Each bound is computed
        only over the offices/subtypes that publish a non-null value for that bound,
        so the lower-bound and upper-bound statistics may be averaged or spanned over
        different populations. USCIS frequently omits one side of a range (for
        example, priority-date-gated categories publish an upper bound but no lower),
        and the lower and upper figures are never combined over a mixed denominator.
      properties:
        avg_lower_months:
          type: number
          format: float
          description: >-
            Average lower bound of processing time, averaged only over offices/subtypes
            that publish a non-null lower bound (months). May cover a different set than
            avg_upper_months.
        avg_upper_months:
          type: number
          format: float
          description: >-
            Average upper bound of processing time, averaged only over offices/subtypes
            that publish a non-null upper bound (months). May cover a different set than
            avg_lower_months.
        min_months:
          type: number
          format: float
          description: >-
            Lower bound of the form's overall processing-time range (months). For
            single-office forms, the minimum across subtypes that publish a lower bound;
            for multi-office forms, the minimum of the per-office aggregate ranges.
            Computed only over the non-null-lower population — a different set than
            max_months uses.
        max_months:
          type: number
          format: float
          description: >-
            Upper bound of the form's overall processing-time range (months). For
            single-office forms, the maximum across subtypes that publish an upper bound;
            for multi-office forms, the maximum of the per-office aggregate ranges.
            Computed only over the non-null-upper population — a different set than
            min_months uses.

    OfficeAggregate:
      type: object
      required:
        - office_code
        - office_name
        - lower_months
        - upper_months
        - aggregation_basis
        - source_rows
        - publication_date
      properties:
        office_code:
          type: string
          description: USCIS office or service center code (e.g. "NBC", "FOD")
        office_name:
          type: string
          description: Human-readable office or service center name
        lower_months:
          type: number
          format: float
          nullable: true
          description: Aggregated lower bound used by the public office comparison row
        upper_months:
          type: number
          format: float
          nullable: true
          description: Aggregated upper bound used by the public office comparison row
        aggregation_basis:
          type: string
          enum:
            - both_endpoint_average
            - upper_bound_average
            - no_current_upper_bound
          description: Method used to derive this office aggregate from raw USCIS subtype rows
        source_rows:
          type: integer
          description: Count of raw USCIS office/subtype rows represented by this aggregate
        publication_date:
          type: string
          format: date
          description: Date of the USCIS publication represented by this aggregate

    OfficeProcessingTime:
      type: object
      required:
        - office_code
        - subtype
        - lower_months
        - upper_months
        - publication_date
      properties:
        office_code:
          type: string
          description: USCIS office or service center code (e.g. "NBC", "VSC", "ABQ")
        subtype:
          type: string
          description: Form subtype code (e.g. "131A-FAM")
        subtype_info:
          type: string
          description: Human-readable description of the subtype
        lower_months:
          type: number
          format: float
          description: Lower bound of processing time range (months)
        upper_months:
          type: number
          format: float
          description: Upper bound of processing time range (months)
        publication_date:
          type: string
          format: date
          description: Date when USCIS published this data point
        service_request_date:
          type: string
          format: date
          description: Date of the oldest pending case being processed

    PermData:
      type: object
      required:
        - source
        - last_updated
        - current
        - history
        - attribution
      properties:
        source:
          type: string
          description: Data source identifier
          example: "DOL FLAG System"
        last_updated:
          type: string
          format: date
          description: Date of the most recent data snapshot
        current:
          $ref: "#/components/schemas/PermSnapshot"
        history:
          type: array
          description: Historical snapshots of PERM processing times
          items:
            $ref: "#/components/schemas/PermHistoryEntry"
        attribution:
          type: string
          description: Attribution URL

    PermSnapshot:
      type: object
      required:
        - avg_processing_days
        - avg_processing_month
      properties:
        avg_processing_days:
          type: integer
          description: Average processing time in calendar days
        avg_processing_month:
          type: string
          description: Month/year currently being processed (e.g. "February 2026")
        analyst_review_queue:
          type: string
          description: Month/year of cases in analyst review queue
        audit_review_queue:
          type: string
          description: Month/year of cases in audit review queue
        reconsideration_queue:
          type: string
          description: Month/year of cases in reconsideration queue

    PermHistoryEntry:
      type: object
      required:
        - snapshot_date
        - avg_processing_days
        - avg_processing_month
      properties:
        snapshot_date:
          type: string
          format: date
          description: Date this snapshot was captured
        avg_processing_days:
          type: integer
          description: Average processing time in calendar days
        avg_processing_month:
          type: string
          description: Month/year currently being processed
        analyst_review_queue:
          type: string
          description: Month/year of cases in analyst review queue
        audit_review_queue:
          type: string
          description: Month/year of cases in audit review queue
        reconsideration_queue:
          type: string
          description: Month/year of cases in reconsideration queue

    VisaBulletinData:
      type: object
      required:
        - generated
        - bulletin_count
        - date_range
        - records
      properties:
        generated:
          type: string
          format: date-time
          description: Timestamp when this data was generated
        bulletin_count:
          type: integer
          description: Number of monthly bulletins in the dataset
        date_range:
          type: object
          required:
            - oldest
            - newest
          properties:
            oldest:
              type: string
              format: date
              description: Date of the oldest bulletin in the dataset
            newest:
              type: string
              format: date
              description: Date of the newest bulletin in the dataset
        records:
          type: array
          description: Individual priority date records
          items:
            $ref: "#/components/schemas/VisaBulletinRecord"

    VisaBulletinRecord:
      type: object
      required:
        - bulletin_date
        - table_type
        - preference
        - country
        - priority_date
      properties:
        bulletin_date:
          type: string
          format: date
          description: Date of the visa bulletin (first of the month)
        table_type:
          type: string
          enum:
            - filing_date
            - final_action
          description: Whether this is a filing date or final action date chart
        preference:
          type: string
          description: Visa preference category (e.g. "EB-1", "EB-2", "F-1")
        country:
          type: string
          enum:
            - all
            - china
            - india
            - mexico
            - philippines
          description: Country of chargeability
        priority_date:
          type: string
          description: Priority date (ISO date string) or "C" for current, "U" for unavailable

tags:
  - name: USCIS Processing Times
    description: |
      Processing time data for 44 USCIS immigration forms, sourced from USCIS and updated daily.
      Historical data available since March 2022 covering 102 offices and service centers.
  - name: DOL PERM
    description: |
      Department of Labor PERM labor certification processing times, sourced from the DOL FLAG system.
      Includes average processing days and review queue positions.
  - name: Visa Bulletin
    description: |
      State Department visa bulletin priority dates for employment-based and family-based
      preference categories across 5 countries. Data covers filing dates and final action dates
      from May 2023 to present.
