Salesforce List Views API

openapi: 3.2.0
info:
  title: Salesforce UI List Views API
  description: The Salesforce UI API provides a comprehensive REST interface for building user interfaces that work with Salesforce metadata and data. It returns layout information, picklist values, list views, record data, and object metadata that Lightning components rely on. Unlike the general REST API, the UI API returns UI-ready data including display labels, field types, formatting hints, and page layout assignments.
  version: '59.0'
  contact:
    name: Salesforce Developer Support
    url: https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/
  termsOfService: https://www.salesforce.com/company/legal/agreements/
servers:
- url: https://{instanceName}.salesforce.com/services/data/v{version}/ui-api
  description: Salesforce org UI API base
  variables:
    instanceName:
      description: Salesforce org instance name or custom domain
      default: myorg
    version:
      description: Salesforce API version
      default: '59.0'
security:
- oauthBearerToken: []
tags:
- name: List Views
  description: Retrieve list view data and metadata for use in UI components
paths:
  /list-ui/{objectApiName}:
    get:
      operationId: getListsByObjectName
      summary: Salesforce Get List Views for an Object
      description: Returns metadata and data for all list views accessible to the current user for the specified object type.
      tags:
      - List Views
      parameters:
      - $ref: '#/components/parameters/ObjectApiName'
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: List views retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListViewCollection'
              examples:
                Getlistsbyobjectname200Example:
                  summary: Default getListsByObjectName 200 response
                  x-microcks-default: true
                  value:
                    count: 42
                    currentPageToken: CAUQAA
                    nextPageToken: CAUQAA
                    previousPageToken: CAUQAA
                    results:
                    - id: abc123
                      apiName: example_value
                      label: Example Title
                      url: https://www.example.com
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /list-ui/{objectApiName}/{listViewApiName}:
    get:
      operationId: getListView
      summary: Salesforce Get a Specific List View
      description: Returns the data and metadata for a specific list view.
      tags:
      - List Views
      parameters:
      - $ref: '#/components/parameters/ObjectApiName'
      - name: listViewApiName
        in: path
        required: true
        description: The API name of the list view (e.g., AllAccounts, RecentlyViewed)
        schema:
          type: string
        example: example_value
      - $ref: '#/components/parameters/PageSize'
      - $ref: '#/components/parameters/PageToken'
      responses:
        '200':
          description: List view data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListViewResult'
              examples:
                Getlistview200Example:
                  summary: Default getListView 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    label: Example Title
                    records:
                    - {}
                    sortBy: example_value
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  responses:
    NotFound:
      description: Not found. The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    ErrorResponse:
      type: object
      description: API error response
      properties:
        errorCode:
          type: string
          description: Machine-readable error code
          example: example_value
        message:
          type: string
          description: Human-readable error message
          example: example_value
    ListViewSummary:
      type: object
      description: Summary information about a list view
      properties:
        id:
          type: string
          example: abc123
        apiName:
          type: string
          example: example_value
        label:
          type: string
          example: Example Title
        url:
          type: string
          example: https://www.example.com
    ListViewResult:
      type: object
      description: Data and metadata for a list view
      properties:
        id:
          type: string
          example: abc123
        label:
          type: string
          example: Example Title
        records:
          type: array
          items:
            type: object
          example: []
        sortBy:
          type: string
          example: example_value
    ListViewCollection:
      type: object
      description: Collection of list views for an object
      properties:
        count:
          type: integer
          example: 42
        currentPageToken:
          type: string
          example: CAUQAA
        nextPageToken:
          type: string
          nullable: true
          example: CAUQAA
        previousPageToken:
          type: string
          nullable: true
          example: CAUQAA
        results:
          type: array
          items:
            $ref: '#/components/schemas/ListViewSummary'
          example: []
  parameters:
    PageSize:
      name: pageSize
      in: query
      description: Number of records per page
      schema:
        type: integer
        minimum: 1
        maximum: 2000
        default: 50
    ObjectApiName:
      name: objectApiName
      in: path
      required: true
      description: The API name of the Salesforce object (e.g., Account, Contact, MyObject__c)
      schema:
        type: string
    PageToken:
      name: pageToken
      in: query
      description: Token for retrieving the next page of results
      schema:
        type: string
  securitySchemes:
    oauthBearerToken:
      type: http
      scheme: bearer
      description: Salesforce OAuth 2.0 Bearer Token
externalDocs:
  description: Salesforce UI API Documentation
  url: https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/