Workday Extend Custom Object Definitions API

openapi: 3.1.0
info:
  title: Workday Extend Workday Custom Objects App Configurations Custom Object Definitions API
  description: APIs for defining and managing custom objects that extend Workday's data model to meet specific business needs. When new custom objects and business processes are built, a public REST API is automatically created for other developers and processes to use. Supports both single-instance and multi-instance custom objects attached to standard Workday business objects such as workers and organizations.
  version: v1
  contact:
    name: Workday Developer Support
    url: https://support.developer.workday.com/s/
  termsOfService: https://www.workday.com/en-us/legal.html
servers:
- url: https://{baseUrl}/api/customObjects/v1/{tenant}
  description: Workday Custom Objects API Server
  variables:
    baseUrl:
      default: api.workday.com
    tenant:
      default: tenant
security:
- OAuth2:
  - customObjects:manage
tags:
- name: Custom Object Definitions
  description: Operations for defining and managing custom object types including their schemas, attributes, and relationships to standard Workday objects.
paths:
  /customObjectDefinitions:
    get:
      operationId: listCustomObjectDefinitions
      summary: Workday Extend List custom object definitions
      description: Returns a collection of custom object type definitions configured in the tenant, including their schemas, field definitions, and parent object associations.
      tags:
      - Custom Object Definitions
      parameters:
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/offset'
      - $ref: '#/components/parameters/search'
      responses:
        '200':
          description: Successful response with custom object definitions
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    description: Total number of custom object definitions
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/CustomObjectDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      operationId: createCustomObjectDefinition
      summary: Workday Extend Create a custom object definition
      description: Creates a new custom object type definition with specified fields and attributes. The definition determines the schema for all instances of this custom object type.
      tags:
      - Custom Object Definitions
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomObjectDefinitionCreate'
      responses:
        '201':
          description: Custom object definition successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomObjectDefinition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /customObjectDefinitions/{definitionId}:
    get:
      operationId: getCustomObjectDefinition
      summary: Workday Extend Retrieve a custom object definition
      description: Returns the details of a specific custom object type definition including its full field schema, validation rules, and parent object associations.
      tags:
      - Custom Object Definitions
      parameters:
      - $ref: '#/components/parameters/definitionId'
      responses:
        '200':
          description: Successful response with definition details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomObjectDefinition'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateCustomObjectDefinition
      summary: Workday Extend Update a custom object definition
      description: Updates an existing custom object type definition. Changes to the schema may affect existing custom object instances.
      tags:
      - Custom Object Definitions
      parameters:
      - $ref: '#/components/parameters/definitionId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomObjectDefinitionUpdate'
      responses:
        '200':
          description: Definition successfully updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomObjectDefinition'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteCustomObjectDefinition
      summary: Workday Extend Delete a custom object definition
      description: Deletes a custom object type definition. All instances of this custom object type must be deleted before the definition can be removed.
      tags:
      - Custom Object Definitions
      parameters:
      - $ref: '#/components/parameters/definitionId'
      responses:
        '204':
          description: Definition successfully deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Invalid request parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  schemas:
    CustomObjectField:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the field
        name:
          type: string
          description: The API name of the field
        displayName:
          type: string
          description: The display label for the field
        dataType:
          type: string
          enum:
          - text
          - number
          - decimal
          - boolean
          - date
          - dateTime
          - currency
          - reference
          - richText
          description: The data type of the field
        isRequired:
          type: boolean
          description: Whether the field is required
        isReadOnly:
          type: boolean
          description: Whether the field is read-only
        maxLength:
          type: integer
          description: Maximum length for text fields
        precision:
          type: integer
          description: Decimal precision for numeric fields
        referenceObjectType:
          type: string
          description: The Workday object type for reference fields
        defaultValue:
          type: string
          description: Default value for the field
    CustomObjectDefinition:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the custom object definition
        descriptor:
          type: string
          description: Display name of the custom object type
        name:
          type: string
          description: The API name of the custom object type
        description:
          type: string
          description: Description of the custom object type
        instanceType:
          type: string
          enum:
          - single
          - multi
          description: Whether this is a single-instance or multi-instance custom object
        parentObjectType:
          type: string
          enum:
          - worker
          - organization
          - position
          - jobProfile
          description: The standard Workday object type this custom object extends
        fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomObjectField'
          description: The fields defined in this custom object
        isActive:
          type: boolean
          description: Whether the custom object definition is active
        createdOn:
          type: string
          format: date-time
          description: Timestamp when the definition was created
        lastModified:
          type: string
          format: date-time
          description: Timestamp when the definition was last modified
        href:
          type: string
          format: uri
    CustomObjectFieldCreate:
      type: object
      required:
      - name
      - dataType
      properties:
        name:
          type: string
          description: The API name of the field
          maxLength: 128
          pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
        displayName:
          type: string
          description: The display label for the field
        dataType:
          type: string
          enum:
          - text
          - number
          - decimal
          - boolean
          - date
          - dateTime
          - currency
          - reference
          - richText
        isRequired:
          type: boolean
          default: false
        maxLength:
          type: integer
          description: Maximum length for text fields
        referenceObjectType:
          type: string
          description: Required for reference type fields
        defaultValue:
          type: string
    CustomObjectDefinitionUpdate:
      type: object
      properties:
        description:
          type: string
          description: Updated description
        isActive:
          type: boolean
          description: Whether the definition is active
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error code identifying the type of error
        message:
          type: string
          description: Human-readable error message
    CustomObjectDefinitionCreate:
      type: object
      required:
      - name
      - instanceType
      - parentObjectType
      properties:
        name:
          type: string
          description: The API name for the custom object type
          maxLength: 128
          pattern: ^[a-zA-Z][a-zA-Z0-9_]*$
        description:
          type: string
          description: Description of the custom object type
        instanceType:
          type: string
          enum:
          - single
          - multi
          description: Whether instances are single or multi per parent object
        parentObjectType:
          type: string
          enum:
          - worker
          - organization
          - position
          - jobProfile
          description: The standard Workday object type to extend
        fields:
          type: array
          items:
            $ref: '#/components/schemas/CustomObjectFieldCreate'
          description: Initial fields for the custom object
  parameters:
    limit:
      name: limit
      in: query
      description: Maximum number of results to return
      schema:
        type: integer
        default: 20
        maximum: 100
    definitionId:
      name: definitionId
      in: path
      required: true
      description: The unique identifier of the custom object definition
      schema:
        type: string
    offset:
      name: offset
      in: query
      description: Number of results to skip for pagination
      schema:
        type: integer
        default: 0
    search:
      name: search
      in: query
      description: Search term to filter results
      schema:
        type: string
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://{baseUrl}/authorize
          tokenUrl: https://{baseUrl}/oauth2/{tenant}/token
          scopes:
            customObjects:manage: Manage custom object definitions and instances
            customObjects:read: Read custom object data
externalDocs:
  description: Workday Custom Objects Documentation
  url: https://doc.workday.com/extend/custom-objects/