Salesforce UI API

openapi: 3.1.0
info:
  title: Salesforce UI 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/
externalDocs:
  description: Salesforce UI API Documentation
  url: https://developer.salesforce.com/docs/atlas.en-us.uiapi.meta/uiapi/
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'
tags:
- name: List Views
  description: Retrieve list view data and metadata for use in UI components
- name: Lookups
  description: Lookup field search endpoints
- name: Object Info
  description: Retrieve object metadata including fields, layouts, and picklists
- name: Picklists
  description: Dependent and independent picklist value endpoints
- name: Records
  description: Retrieve record data with field labels and UI-formatting metadata
security:
- oauthBearerToken: []
paths:
  /records/{recordId}:
    get:
      operationId: getRecord
      summary: Salesforce Get a Record
      description: >-
        Returns data for a record including field values, formatted for display
        in the Lightning UI. Supports specifying which fields to return using
        the fields or layoutTypes parameter. Returns record metadata alongside
        data, including field labels, editability, and required status.
      tags:
      - Records
      parameters:
      - $ref: '#/components/parameters/RecordId'
      - name: fields
        in: query
        description: Comma-separated list of field API names to return (e.g., Account.Name,Account.Type)
        schema:
          type: string
        example: example_value
      - name: layoutTypes
        in: query
        description: >-
          Layout types to use for determining which fields to return
          (Full, Compact)
        schema:
          type: string
          enum:
          - Full
          - Compact
        example: Full
      - name: modes
        in: query
        description: View mode(s) for the layout (View, Edit, Create)
        schema:
          type: string
        example: example_value
      - name: optionalFields
        in: query
        description: Fields to include if accessible, without error if inaccessible
        schema:
          type: string
        example: example_value
      responses:
        '200':
          description: Record data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordRepresentation'
              examples:
                Getrecord200Example:
                  summary: Default getRecord 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    apiName: example_value
                    childRelationships: example_value
                    eTag: example_value
                    fields: example_value
                    recordTypeId: '500123'
                    recordTypeInfo:
                      available: true
                      defaultRecordTypeMapping: true
                      master: true
                      name: Example Title
                      recordTypeId: '500123'
                    systemModstamp: '2026-01-15T10:30:00Z'
                    lastModifiedById: '500123'
                    lastModifiedDate: '2026-01-15T10:30:00Z'
                    createdById: '500123'
                    createdDate: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateRecord
      summary: Salesforce Update a Record
      description: >-
        Updates fields on a Salesforce record. Only the fields included in the
        request body are updated. Returns the updated record representation.
      tags:
      - Records
      parameters:
      - $ref: '#/components/parameters/RecordId'
      - name: If-Modified-Since
        in: header
        description: Conditional update based on record modification timestamp
        schema:
          type: string
        example: example_value
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordInput'
            examples:
              UpdaterecordRequestExample:
                summary: Default updateRecord request
                x-microcks-default: true
                value:
                  apiName: example_value
                  fields: example_value
      responses:
        '200':
          description: Record updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordRepresentation'
              examples:
                Updaterecord200Example:
                  summary: Default updateRecord 200 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    apiName: example_value
                    childRelationships: example_value
                    eTag: example_value
                    fields: example_value
                    recordTypeId: '500123'
                    recordTypeInfo:
                      available: true
                      defaultRecordTypeMapping: true
                      master: true
                      name: Example Title
                      recordTypeId: '500123'
                    systemModstamp: '2026-01-15T10:30:00Z'
                    lastModifiedById: '500123'
                    lastModifiedDate: '2026-01-15T10:30:00Z'
                    createdById: '500123'
                    createdDate: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteRecord
      summary: Salesforce Delete a Record
      description: Deletes a Salesforce record by its ID.
      tags:
      - Records
      parameters:
      - $ref: '#/components/parameters/RecordId'
      responses:
        '204':
          description: Record deleted successfully
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /records:
    post:
      operationId: createRecord
      summary: Salesforce Create a Record
      description: >-
        Creates a new Salesforce record of the specified object type. The
        apiName of the object is included in the request body.
      tags:
      - Records
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecordInput'
            examples:
              CreaterecordRequestExample:
                summary: Default createRecord request
                x-microcks-default: true
                value:
                  apiName: example_value
                  fields: example_value
      responses:
        '201':
          description: Record created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecordRepresentation'
              examples:
                Createrecord201Example:
                  summary: Default createRecord 201 response
                  x-microcks-default: true
                  value:
                    id: abc123
                    apiName: example_value
                    childRelationships: example_value
                    eTag: example_value
                    fields: example_value
                    recordTypeId: '500123'
                    recordTypeInfo:
                      available: true
                      defaultRecordTypeMapping: true
                      master: true
                      name: Example Title
                      recordTypeId: '500123'
                    systemModstamp: '2026-01-15T10:30:00Z'
                    lastModifiedById: '500123'
                    lastModifiedDate: '2026-01-15T10:30:00Z'
                    createdById: '500123'
                    createdDate: '2026-01-15T10:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /object-info/{objectApiName}:
    get:
      operationId: getObjectInfo
      summary: Salesforce Get Object Metadata
      description: >-
        Returns metadata about a Salesforce object including its fields,
        their types, labels, whether they are required or read-only, their
        reference targets, and the object's CRUD permissions. Used by
        Lightning components to build dynamic forms.
      tags:
      - Object Info
      parameters:
      - $ref: '#/components/parameters/ObjectApiName'
      responses:
        '200':
          description: Object metadata retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectInfoRepresentation'
              examples:
                Getobjectinfo200Example:
                  summary: Default getObjectInfo 200 response
                  x-microcks-default: true
                  value:
                    apiName: example_value
                    label: Example Title
                    labelPlural: example_value
                    keyPrefix: example_value
                    createable: true
                    updateable: true
                    deleteable: true
                    queryable: true
                    fields: example_value
                    recordTypeInfos: example_value
                    themeInfo:
                      color: example_value
                      iconUrl: https://www.example.com
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /object-info/{objectApiName}/picklist-values/{recordTypeId}:
    get:
      operationId: getPicklistValues
      summary: Salesforce Get Picklist Values for a Record Type
      description: >-
        Returns picklist values for all picklist fields on an object for a
        given record type. Values include labels, valid values, and
        dependencies between picklist fields.
      tags:
      - Picklists
      parameters:
      - $ref: '#/components/parameters/ObjectApiName'
      - name: recordTypeId
        in: path
        required: true
        description: The record type ID or the string '012000000000000AAA' for the master record type
        schema:
          type: string
        example: '500123'
      responses:
        '200':
          description: Picklist values retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PicklistValuesCollection'
              examples:
                Getpicklistvalues200Example:
                  summary: Default getPicklistValues 200 response
                  x-microcks-default: true
                  value:
                    picklistFieldValues: example_value
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /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
  /lookups/{objectApiName}/{fieldApiName}:
    get:
      operationId: getLookupRecords
      summary: Salesforce Search Lookup Field Records
      description: >-
        Returns matching records for a lookup field search. Used to populate
        the typeahead list in Lightning lookup components.
      tags:
      - Lookups
      parameters:
      - $ref: '#/components/parameters/ObjectApiName'
      - name: fieldApiName
        in: path
        required: true
        description: The API name of the lookup field
        schema:
          type: string
        example: example_value
      - name: searchTerm
        in: query
        required: true
        description: The search text to match against lookup records
        schema:
          type: string
        example: example_value
      - name: dependentFieldBindings
        in: query
        description: JSON-encoded field value pairs for dependent picklist filtering
        schema:
          type: string
        example: example_value
      - $ref: '#/components/parameters/PageSize'
      responses:
        '200':
          description: Lookup results retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupRecordsCollection'
              examples:
                Getlookuprecords200Example:
                  summary: Default getLookupRecords 200 response
                  x-microcks-default: true
                  value:
                    count: 42
                    lookupResults:
                    - displayValue: example_value
                      id: abc123
                      name: Example Title
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    oauthBearerToken:
      type: http
      scheme: bearer
      description: Salesforce OAuth 2.0 Bearer Token
  parameters:
    RecordId:
      name: recordId
      in: path
      required: true
      description: The 18-character Salesforce record ID
      schema:
        type: string
        pattern: '^[a-zA-Z0-9]{18}$'
    ObjectApiName:
      name: objectApiName
      in: path
      required: true
      description: The API name of the Salesforce object (e.g., Account, Contact, MyObject__c)
      schema:
        type: string
    PageSize:
      name: pageSize
      in: query
      description: Number of records per page
      schema:
        type: integer
        minimum: 1
        maximum: 2000
        default: 50
    PageToken:
      name: pageToken
      in: query
      description: Token for retrieving the next page of results
      schema:
        type: string
  responses:
    BadRequest:
      description: Bad request. Invalid parameters or request body.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized. Session has expired or is invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden. Insufficient permissions for this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Not found. The requested resource does not exist.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    RecordRepresentation:
      type: object
      description: A Salesforce record with field values and UI metadata
      properties:
        id:
          type: string
          description: The 18-character Salesforce record ID
          example: abc123
        apiName:
          type: string
          description: The API name of the object type
          example: example_value
        childRelationships:
          type: object
          description: Child relationship data indexed by relationship name
          additionalProperties: true
          example: example_value
        eTag:
          type: string
          description: ETag for optimistic concurrency control
          example: example_value
        fields:
          type: object
          description: Field values indexed by field API name
          additionalProperties:
            $ref: '#/components/schemas/FieldValueRepresentation'
          example: example_value
        recordTypeId:
          type: string
          description: The record type ID
          example: '500123'
        recordTypeInfo:
          type: object
          description: Record type metadata
          properties:
            available:
              type: boolean
            defaultRecordTypeMapping:
              type: boolean
            master:
              type: boolean
            name:
              type: string
            recordTypeId:
              type: string
          example: example_value
        systemModstamp:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        lastModifiedById:
          type: string
          example: '500123'
        lastModifiedDate:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
        createdById:
          type: string
          example: '500123'
        createdDate:
          type: string
          format: date-time
          example: '2026-01-15T10:30:00Z'
    FieldValueRepresentation:
      type: object
      description: A field value with display metadata
      properties:
        displayValue:
          description: Human-readable formatted display value (for dates, picklists, lookups)
          nullable: true
          oneOf:
          - type: string
          - type: 'null'
          example: example_value
        value:
          description: Raw field value
          nullable: true
          example: example_value
    RecordInput:
      type: object
      description: Input for creating or updating a record
      required:
      - apiName
      - fields
      properties:
        apiName:
          type: string
          description: The API name of the object type
          example: example_value
        fields:
          type: object
          description: Field values to set, indexed by field API name
          additionalProperties:
            description: Field value (string, number, boolean, or null to clear)
          example: example_value
    ObjectInfoRepresentation:
      type: object
      description: Metadata about a Salesforce object
      properties:
        apiName:
          type: string
          example: example_value
        label:
          type: string
          example: Example Title
        labelPlural:
          type: string
          example: example_value
        keyPrefix:
          type: string
          example: example_value
        createable:
          type: boolean
          example: true
        updateable:
          type: boolean
          example: true
        deleteable:
          type: boolean
          example: true
        queryable:
          type: boolean
          example: true
        fields:
          type: object
          description: Field metadata indexed by field API name
          additionalProperties:
            $ref: '#/components/schemas/FieldRepresentation'
          example: example_value
        recordTypeInfos:
          type: object
          additionalProperties: true
          example: example_value
        themeInfo:
          type: object
          properties:
            color:
              type: string
            iconUrl:
              type: string
          example: example_value
    FieldRepresentation:
      type: object
      description: Metadata for a single field
      properties:
        apiName:
          type: string
          example: example_value
        label:
          type: string
          example: Example Title
        dataType:
          type: string
          enum:
          - Address
          - Boolean
          - Currency
          - Date
          - DateTime
          - Double
          - Email
          - Id
          - Integer
          - Long
          - MultiPicklist
          - Percent
          - Phone
          - Picklist
          - Reference
          - String
          - TextArea
          - Time
          - Url
          example: Address
        required:
          type: boolean
          example: true
        updateable:
          type: boolean
          example: true
        createable:
          type: boolean
          example: true
        nillable:
          type: boolean
          example: true
        referenceToInfos:
          type: array
          items:
            type: object
            properties:
              apiName:
                type: string
              nameFields:
                type: array
                items:
                  type: string
          example: []
    PicklistValuesCollection:
      type: object
      description: Collection of picklist values for all picklist fields on an object
      properties:
        picklistFieldValues:
          type: object
          additionalProperties:
            type: object
            properties:
              controllerValues:
                type: object
                additionalProperties:
                  type: integer
              defaultValue:
                nullable: true
              url:
                type: string
              values:
                type: array
                items:
                  $ref: '#/components/schemas/PicklistValue'
          example: example_value
    PicklistValue:
      type: object
      description: A single picklist option
      properties:
        attributes:
          nullable: true
          example: example_value
        label:
          type: string
          example: Example Title
        validFor:
          type: array
          items:
            type: integer
          example: []
        value:
          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: []
    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
    LookupRecordsCollection:
      type: object
      description: Collection of records matching a lookup search
      properties:
        count:
          type: integer
          example: 42
        lookupResults:
          type: array
          items:
            type: object
            properties:
              displayValue:
                type: string
              id:
                type: string
              name:
                type: string
          example: []
    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