User Interface API

openapi: 3.1.0
info:
  title: Salesforce Experience Cloud Salesforce User Interface API
  description: >-
    Access record data, layouts, list views, and navigation items for building
    custom user interfaces. Powers Lightning web components in Experience Cloud
    sites with metadata-driven UI rendering. Returns both data and metadata
    in a single response.
  version: 59.0.0
  contact:
    name: Salesforce Developer Support
    url: https://developer.salesforce.com/
  license:
    name: Salesforce Master Subscription Agreement
    url: https://www.salesforce.com/company/legal/sfdc-website-terms-of-service/
servers:
  - url: https://{instance}.salesforce.com/services/data/v59.0/ui-api
    description: Salesforce Instance
    variables:
      instance:
        default: yourInstance
        description: Your Salesforce instance name or custom domain
security:
  - oauth2: []
  - bearerAuth: []
tags:
  - name: Actions
    description: Available actions for records and objects
  - name: Favorites
    description: User favorites management
  - name: Layouts
    description: Page layout metadata
  - name: List Views
    description: List view data and metadata
  - name: Object Info
    description: Object metadata for UI rendering
  - name: Records
    description: Record data and UI operations
paths:
  /record-ui/{recordIds}:
    get:
      operationId: getRecordUi
      summary: Salesforce Experience Cloud Get Record UI
      description: >-
        Returns layout information, field data, and object metadata for one
        or more records. Provides everything needed to render a record detail
        page including layout sections, field values, and display properties.
      tags:
        - Records
      parameters:
        - name: recordIds
          in: path
          required: true
          description: >-
            One or more record IDs (comma-separated for multiple records,
            up to 200)
          schema:
            type: string
        - name: childRelationships
          in: query
          description: Comma-separated list of child relationship names to include
          schema:
            type: string
        - name: formFactor
          in: query
          description: Form factor for the layout
          schema:
            type: string
            enum:
              - Large
              - Medium
              - Small
        - name: layoutTypes
          in: query
          description: Comma-separated layout types to return
          schema:
            type: string
            enum:
              - Compact
              - Full
        - name: modes
          in: query
          description: Comma-separated modes for the layout
          schema:
            type: string
            enum:
              - Create
              - Edit
              - View
        - name: optionalFields
          in: query
          description: Comma-separated list of optional fields to include
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved record UI data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordUiRepresentation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /records/{recordId}:
    get:
      operationId: getRecord
      summary: Salesforce Experience Cloud Get a Record
      description: >-
        Returns field values and metadata for a specific record. Supports
        requesting specific fields or all fields from a layout. Returns
        both raw values and display-formatted values.
      tags:
        - Records
      parameters:
        - $ref: '#/components/parameters/RecordId'
        - name: fields
          in: query
          description: Comma-separated list of field API names to return
          schema:
            type: string
        - name: layoutTypes
          in: query
          description: Layout type whose fields to include
          schema:
            type: string
            enum:
              - Compact
              - Full
        - name: modes
          in: query
          description: Layout mode
          schema:
            type: string
            enum:
              - Create
              - Edit
              - View
        - name: optionalFields
          in: query
          description: Optional fields to include if accessible
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved the record
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordRepresentation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateRecord
      summary: Salesforce Experience Cloud Update a Record
      description: >-
        Updates the specified record with the provided field values. Returns
        the updated record representation including the new field values.
      tags:
        - Records
      parameters:
        - $ref: '#/components/parameters/RecordId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordInput'
      responses:
        '200':
          description: Record updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordRepresentation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteRecord
      summary: Salesforce Experience Cloud Delete a Record
      description: >-
        Deletes the specified record. The record is moved to the Recycle
        Bin.
      tags:
        - Records
      parameters:
        - $ref: '#/components/parameters/RecordId'
      responses:
        '204':
          description: Record deleted successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /records:
    post:
      operationId: createRecord
      summary: Salesforce Experience Cloud Create a Record
      description: >-
        Creates a new record of the specified sObject type. Returns the
        created record representation with all field values.
      tags:
        - Records
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordInput'
      responses:
        '201':
          description: Record created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordRepresentation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /layout/{objectApiName}:
    get:
      operationId: getRecordLayout
      summary: Salesforce Experience Cloud Get Record Layout
      description: >-
        Returns layout metadata for the specified object type including
        sections, fields, and their display properties. Used to render
        record forms dynamically.
      tags:
        - Layouts
      parameters:
        - $ref: '#/components/parameters/ObjectApiName'
        - name: formFactor
          in: query
          description: Form factor for the layout
          schema:
            type: string
            enum:
              - Large
              - Medium
              - Small
        - name: layoutType
          in: query
          description: Type of layout to retrieve
          schema:
            type: string
            enum:
              - Compact
              - Full
        - name: mode
          in: query
          description: Mode for the layout
          schema:
            type: string
            enum:
              - Create
              - Edit
              - View
        - name: recordTypeId
          in: query
          description: Record type ID for the layout
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved record layout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordLayoutRepresentation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /object-info/{objectApiName}:
    get:
      operationId: getObjectInfo
      summary: Salesforce Experience Cloud Get Object Info
      description: >-
        Returns metadata about the specified object including fields, record
        types, child relationships, and theme information. Provides the
        information needed for metadata-driven UI construction.
      tags:
        - Object Info
      parameters:
        - $ref: '#/components/parameters/ObjectApiName'
      responses:
        '200':
          description: Successfully retrieved object info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectInfoRepresentation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /list-ui/{listViewId}:
    get:
      operationId: getListViewData
      summary: Salesforce Experience Cloud Get List View Data
      description: >-
        Returns the records and metadata for a specific list view including
        columns, sorting, filtering, and the record data. Used to render
        list views in custom UIs.
      tags:
        - List Views
      parameters:
        - name: listViewId
          in: path
          required: true
          description: The ID of the list view
          schema:
            type: string
        - name: fields
          in: query
          description: Additional fields to include in list view records
          schema:
            type: string
        - name: optionalFields
          in: query
          description: Optional fields to include if accessible
          schema:
            type: string
        - name: pageSize
          in: query
          description: Number of records per page
          schema:
            type: integer
            default: 50
        - name: pageToken
          in: query
          description: Token for the next page of records
          schema:
            type: string
        - name: sortBy
          in: query
          description: Field API name to sort by
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved list view data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListViewRepresentation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /list-ui/{objectApiName}:
    get:
      operationId: getListViewsByObject
      summary: Salesforce Experience Cloud Get List Views for Object
      description: >-
        Returns all available list views for the specified object type.
        Includes list view ID, label, and developer name.
      tags:
        - List Views
      parameters:
        - $ref: '#/components/parameters/ObjectApiName'
        - name: pageSize
          in: query
          description: Number of list views per page
          schema:
            type: integer
            default: 20
        - name: pageToken
          in: query
          description: Token for the next page
          schema:
            type: string
        - name: q
          in: query
          description: Search term to filter list views by name
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved list views
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListViewSummaryCollection'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /actions/record/{recordId}:
    get:
      operationId: getRecordActions
      summary: Salesforce Experience Cloud Get Record Actions
      description: >-
        Returns the actions available for a specific record based on the
        current user's permissions and the record's state.
      tags:
        - Actions
      parameters:
        - $ref: '#/components/parameters/RecordId'
        - name: formFactor
          in: query
          description: Form factor for filtering actions
          schema:
            type: string
            enum:
              - Large
              - Medium
              - Small
        - name: sections
          in: query
          description: Comma-separated list of action sections
          schema:
            type: string
      responses:
        '200':
          description: Successfully retrieved record actions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordActionsRepresentation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /favorites:
    get:
      operationId: getFavorites
      summary: Salesforce Experience Cloud Get Favorites
      description: >-
        Returns the list of favorites for the context user, including
        records, list views, and other favorited items.
      tags:
        - Favorites
      responses:
        '200':
          description: Successfully retrieved favorites
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FavoritesRepresentation'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: addFavorite
      summary: Salesforce Experience Cloud Add a Favorite
      description: >-
        Adds a record, list view, or other item to the user's favorites.
      tags:
        - Favorites
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FavoriteInput'
      responses:
        '201':
          description: Favorite added successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Favorite'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /favorites/{favoriteId}:
    delete:
      operationId: removeFavorite
      summary: Salesforce Experience Cloud Remove a Favorite
      description: >-
        Removes the specified item from the user's favorites.
      tags:
        - Favorites
      parameters:
        - name: favoriteId
          in: path
          required: true
          description: The ID of the favorite to remove
          schema:
            type: string
      responses:
        '204':
          description: Favorite removed successfully
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  securitySchemes:
    oauth2:
      type: oauth2
      description: Salesforce OAuth 2.0 authentication
      flows:
        authorizationCode:
          authorizationUrl: https://login.salesforce.com/services/oauth2/authorize
          tokenUrl: https://login.salesforce.com/services/oauth2/token
          scopes:
            api: Access and manage your data
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: OAuth2
      description: Bearer token obtained through OAuth 2.0 flow
  parameters:
    RecordId:
      name: recordId
      in: path
      required: true
      description: The 18-character Salesforce record ID
      schema:
        type: string
    ObjectApiName:
      name: objectApiName
      in: path
      required: true
      description: The API name of the Salesforce object (e.g., Account, Contact)
      schema:
        type: string
  schemas:
    RecordUiRepresentation:
      type: object
      description: Complete UI representation for one or more records
      properties:
        layoutUserStates:
          type: object
          additionalProperties:
            type: object
        layouts:
          type: object
          description: Map of object API names to layout representations
          additionalProperties:
            type: object
        objectInfos:
          type: object
          description: Map of object API names to object info
          additionalProperties:
            $ref: '#/components/schemas/ObjectInfoRepresentation'
        records:
          type: object
          description: Map of record IDs to record representations
          additionalProperties:
            $ref: '#/components/schemas/RecordRepresentation'
    RecordRepresentation:
      type: object
      description: Representation of a record with field values
      properties:
        apiName:
          type: string
          description: API name of the sObject type
        childRelationships:
          type: object
          additionalProperties:
            type: object
        eTag:
          type: string
          description: Entity tag for optimistic concurrency
        fields:
          type: object
          description: Map of field API names to field values
          additionalProperties:
            $ref: '#/components/schemas/FieldValueRepresentation'
        id:
          type: string
          description: Record ID
        lastModifiedById:
          type: string
        lastModifiedDate:
          type: string
          format: date-time
        recordTypeId:
          type: string
        recordTypeInfo:
          type: object
          properties:
            available:
              type: boolean
            defaultRecordTypeMapping:
              type: boolean
            master:
              type: boolean
            name:
              type: string
            recordTypeId:
              type: string
        systemModstamp:
          type: string
          format: date-time
        weakEtag:
          type: integer
    RecordInput:
      type: object
      description: Input for creating or updating a record
      properties:
        apiName:
          type: string
          description: API name of the sObject type (required for create)
        fields:
          type: object
          description: Map of field API names to values
          additionalProperties: true
    FieldValueRepresentation:
      type: object
      description: Field value with display formatting
      properties:
        displayValue:
          type: string
          description: Formatted display value (locale-aware)
        value:
          description: Raw field value
    RecordLayoutRepresentation:
      type: object
      description: Layout metadata for an object
      properties:
        id:
          type: string
          description: Layout ID
        layoutType:
          type: string
          enum:
            - Compact
            - Full
        mode:
          type: string
          enum:
            - Create
            - Edit
            - View
        sections:
          type: array
          items:
            $ref: '#/components/schemas/LayoutSection'
    LayoutSection:
      type: object
      description: A section within a layout
      properties:
        collapsible:
          type: boolean
        columns:
          type: integer
        heading:
          type: string
        id:
          type: string
        layoutRows:
          type: array
          items:
            type: object
            properties:
              layoutItems:
                type: array
                items:
                  $ref: '#/components/schemas/LayoutItem'
        rows:
          type: integer
        useHeading:
          type: boolean
    LayoutItem:
      type: object
      description: A field item within a layout section
      properties:
        editableForNew:
          type: boolean
        editableForUpdate:
          type: boolean
        label:
          type: string
        layoutComponents:
          type: array
          items:
            type: object
            properties:
              apiName:
                type: string
              componentType:
                type: string
              label:
                type: string
        lookupIdApiName:
          type: string
        required:
          type: boolean
        sortable:
          type: boolean
    ObjectInfoRepresentation:
      type: object
      description: Object metadata for UI rendering
      properties:
        apiName:
          type: string
          description: API name of the object
        associateEntityType:
          type: string
        associateParentEntity:
          type: string
        childRelationships:
          type: array
          items:
            type: object
            properties:
              childObjectApiName:
                type: string
              fieldName:
                type: string
              junctionIdListNames:
                type: array
                items:
                  type: string
              junctionReferenceTo:
                type: array
                items:
                  type: string
              relationshipName:
                type: string
        createable:
          type: boolean
        custom:
          type: boolean
        defaultRecordTypeId:
          type: string
        deletable:
          type: boolean
        feedEnabled:
          type: boolean
        fields:
          type: object
          description: Map of field API names to field metadata
          additionalProperties:
            type: object
            properties:
              apiName:
                type: string
              compound:
                type: boolean
              compoundComponentName:
                type: string
              compoundFieldName:
                type: string
              controllerName:
                type: string
              controllingFields:
                type: array
                items:
                  type: string
              createable:
                type: boolean
              custom:
                type: boolean
              dataType:
                type: string
              extraTypeInfo:
                type: string
              filterable:
                type: boolean
              filteredLookupInfo:
                type: object
              highScaleNumber:
                type: boolean
              htmlFormatted:
                type: boolean
              inlineHelpText:
                type: string
              label:
                type: string
              length:
                type: integer
              nameField:
                type: boolean
              polymorphicForeignKey:
                type: boolean
              precision:
                type: integer
              reference:
                type: boolean
              referenceTargetField:
                type: string
              referenceToInfos:
                type: array
                items:
                  type: object
              relationshipName:
                type: string
              required:
                type: boolean
              scale:
                type: integer
              searchPrefilterable:
                type: boolean
              sortable:
                type: boolean
              unique:
                type: boolean
              updateable:
                type: boolean
        keyPrefix:
          type: string
        label:
          type: string
        labelPlural:
          type: string
        layoutable:
          type: boolean
        mruEnabled:
          type: boolean
        nameFields:
          type: array
          items:
            type: string
        queryable:
          type: boolean
        recordTypeInfos:
          type: object
          additionalProperties:
            type: object
            properties:
              available:
                type: boolean
              defaultRecordTypeMapping:
                type: boolean
              master:
                type: boolean
              name:
                type: string
              recordTypeId:
                type: string
        searchable:
          type: boolean
        themeInfo:
          type: object
          properties:
            color:
              type: string
            iconUrl:
              type: string
              format: uri
        updateable:
          type: boolean
    ListViewRepresentation:
      type: object
      description: List view data and metadata
      properties:
        count:
          type: integer
        currentPageToken:
          type: string
        currentPageUrl:
          type: string
          format: uri
        info:
          $ref: '#/components/schemas/ListViewInfo'
        nextPageToken:
          type: string
        nextPageUrl:
          type: string
          format: uri
        previousPageToken:
          type: string
        previousPageUrl:
          type: string
          format: uri
        records:
          type: array
          items:
            $ref: '#/components/schemas/RecordRepresentation'
    ListViewInfo:
      type: object
      description: Metadata about a list view
      properties:
        cloneable:
          type: boolean
        createable:
          type: boolean
        deletable:
          type: boolean
        displayColumns:
          type: array
          items:
            type: object
            properties:
              fieldApiName:
                type: string
              label:
                type: string
              sortable:
                type: boolean
        eTag:
          type: string
        filterLogicString:
          type: string
        filteredByInfo:
          type: array
          items:
            type: object
        id:
          type: string
        label:
          type: string
        listReference:
          type: object
          properties:
            id:
              type: string
            listViewApiName:
              type: string
            objectApiName:
              type: string
            type:
              type: string
        orderedByInfo:
          type: array
          items:
            type: object
            properties:
              fieldApiName:
                type: string
              isAscending:
                type: boolean
              label:
                type: string
        updateable:
          type: boolean
        visibility:
          type: string
          enum:
            - Private
            - Public
    ListViewSummaryCollection:
      type: object
      description: Collection of list view summaries
      properties:
        count:
          type: integer
        currentPageToken:
          type: string
        currentPageUrl:
          type: string
          format: uri
        lists:
          type: array
          items:
            type: object
            properties:
              apiName:
                type: string
              id:
                type: string
              label:
                type: string
              listUiUrl:
                type: string
                format: uri
        nextPageToken:
          type: string
        nextPageUrl:
          type: string
          format: uri
        objectApiName:
          type: string
    RecordActionsRepresentation:
      type: object
      description: Available actions for a record
      properties:
        actions:
          type: object
          additionalProperties:
            type: object
            properties:
              actions:
                type: array
                items:
                  type: object
                  properties:
                    actionListContext:
                      type: string
                    actionTarget:
                      type: string
                      format: uri
                    actionTargetType:
                      type: string
                    apiName:
                      type: string
                    externalAction:
                      type: boolean
                    iconUrl:
                      type: string
                      format: uri
                    id:
                      type: string
                    isMassAction:
                      type: boolean
                    label:
                      type: string
                    primary:
                      type: boolean
                    relatedListRecordId:
                      type: string
                    relatedSourceObject:
                      type: string
                    subtype:
                      type: string
                    targetObject:
                      type: string
                    targetUrl:
                      type: string
                    type:
                      type: string
    FavoritesRepresentation:
      type: object
      description: User's favorites
      properties:
        favorites:
          type: array
          items:
            $ref: '#/components/schemas/Favorite'
    Favorite:
      type: object
      description: A user favorite item
      properties:
        color:
          type: string
        iconUrl:
          type: string
          format: uri
        id:
          type: string
        name:
          type: string
        sortOrder:
          type: integer
        target:
          type: string
        targetType:
          type: string
          enum:
            - Record
            - ListView
            - Object
            - Dashboard
            - Report
    FavoriteInput:
      type: object
      description: Input for adding a favorite
      required:
        - name
        - target
        - targetType
      properties:
        name:
          type: string
          description: Name of the favorite
        sortOrder:
          type: integer
          description: Sort position
        target:
          type: string
          description: ID or reference of the item to favorite
        targetType:
          type: string
          description: Type of item being favorited
          enum:
            - Record
            - ListView
            - Object
    ErrorResponse:
      type: object
      description: Standard error response
      properties:
        errorCode:
          type: string
        message:
          type: string
  responses:
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Not found
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/ErrorResponse'