openapi: 3.1.0
info:
  title: Xpand API
  version: 2025-03
tags:
  - name: Users
  - name: Offers
  - name: References
  - name: Custom Fields
  - name: Journeys
  - name: User Journeys
paths:
  /api/v1/job_profiles:
    get:
      operationId: References_job_profiles
      summary: Fetch Job Profiles
      description: Fetch a Job Profile
      parameters: []
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
      tags:
        - References
  /api/v1/offer_letters:
    get:
      operationId: Offers_list
      summary: Search Offer Letters
      description: Search Offer Letters - Offer Letters are the letters that are sent to candidates.
      parameters:
        - name: filters
          in: query
          required: false
          schema:
            type: object
            properties:
              ids:
                type: string
                description: Comma separated list of Xpand Offer IDs
                examples:
                  - 64891c74d5ee1bb16dfdafd8,64891e2ad5ee1bb16dfdafd9
              offer_ids:
                type: string
                description: Comma separated list of Client Offer IDs
                examples:
                  - 64891c74d5ee1bb16dfdafd8,64891e2ad5ee1bb16dfdafd9
              user_ids:
                type: string
                description: Comma separated list of Xpand User IDs
                examples:
                  - 64891c74d5ee1bb16dfdafd8,64891e2ad5ee1bb16dfdafd9
              statuses:
                type: array
                items:
                  type: string
                  enum:
                    - pending_initiation
                    - pending_approval
                    - admin_approved
                    - admin_rejected
                    - candidate_pending
                    - candidate_accepted
                    - candidate_declined
                    - rescinded
                    - voided
                description: Comma separated list of Offer Statuses
          explode: false
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/OfferLetterResponseFull'
                required:
                  - data
      tags:
        - Offers
    post:
      operationId: Offers_create
      summary: Create/Update Offer Letter
      description: Create/Update Offer Letter - Create or update an offer letter.
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/OfferLetterResponseSimple'
                required:
                  - data
      tags:
        - Offers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      $ref: '#/components/schemas/OfferLetterRequest'
                  required:
                    - attributes
              required:
                - data
  /api/v1/offer_letters/{id}:
    delete:
      operationId: Offers_delete
      summary: Rescind Offer Letter
      description: Rescind an offer letter.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
      tags:
        - Offers
  /api/v1/office_locations:
    get:
      operationId: References_office_locations
      summary: Fetch Office Locations
      description: Fetch Office Locations
      parameters: []
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
      tags:
        - References
  /api/v1/users:
    get:
      operationId: Users_list
      summary: Search Users
      description: Search Users - Users are the people who are part of the Xpand system.
      parameters:
        - name: filter
          in: query
          required: false
          schema:
            type: object
            properties:
              ids:
                type: string
                description: Comma separated list of Xpand User IDs
                examples:
                  - 64891c74d5ee1bb16dfdafd8,64891e2ad5ee1bb16dfdafd9
              emails:
                type: string
                description: Comma separated list of User Emails
                examples:
                  - john@example.com,jane@example.com
          explode: false
        - name: page
          in: query
          required: false
          schema:
            type: integer
            default: 1
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/UserResponseFull'
                required:
                  - data
      tags:
        - Users
    post:
      operationId: Users_create
      summary: Create User
      description: Create a User
      parameters: []
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UserResponseSimple'
                required:
                  - data
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                data:
                  type: object
                  properties:
                    attributes:
                      $ref: '#/components/schemas/UserRequest'
                  required:
                    - attributes
              required:
                - data
  /api/v1/users/{id}:
    get:
      operationId: Users_show
      summary: Fetch User
      description: Fetch a User
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UserResponseFull'
                required:
                  - data
      tags:
        - Users
    patch:
      operationId: Users_update
      summary: Update User
      description: Update a User
      parameters:
        - name: id
          in: path
          required: true
          schema:
            $ref: '#/components/schemas/uuid'
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UserResponseSimple'
                required:
                  - data
      tags:
        - Users
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserRequest'
  /api/v2/custom_fields:
    get:
      operationId: CustomFields_list
      summary: Search Custom Fields
      description: Lists custom fields that can be used in user journeys or forms. Custom fields help capture metadata unique to your organization.
      parameters:
        - name: filters
          in: query
          required: false
          schema:
            type: object
            properties:
              id:
                type: string
                description: Comma separated list of Custom Field IDs
                examples:
                  - 1234,123456
              sub_type:
                type: string
                description: Comma separated list of Journey Types
                examples:
                  - pre_offer, offer, post_offer, onboarding, offboarding
              data_type:
                type: string
                description: Comma separated list of Data Types
                examples:
                  - string, integer, big_decimal, array, hash, time, date, boolean
              active:
                type: string
                description: Comma separated list of Active
                examples:
                  - true, false
          explode: false
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          explode: false
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
          explode: false
        - name: order_by
          in: query
          required: false
          schema:
            type: string
            default: created_at
          explode: false
        - name: direction
          in: query
          required: false
          schema:
            type: string
            default: asc
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomField'
      tags:
        - Custom Fields
    post:
      operationId: CustomFields_create
      summary: Create Custom Field
      description: Creates a new custom field that can be used in user journeys or forms.
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomField'
        '422':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      tags:
        - Custom Fields
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomFieldCreate'
  /api/v2/custom_fields/{id}:
    get:
      operationId: CustomFields_show
      summary: Fetch Custom Field
      description: Fetch a Custom Field
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomField'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      tags:
        - Custom Fields
  /api/v2/custom_fields/{id}/activate:
    patch:
      operationId: CustomFields_activate
      summary: Activate Custom Field
      description: Activates a custom field.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
      tags:
        - Custom Fields
  /api/v2/custom_fields/{id}/deactivate:
    patch:
      operationId: CustomFields_deactivate
      summary: Deactivate Custom Field
      description: Deactivates a custom field. This will not delete the custom field, but will make it inactive.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
      tags:
        - Custom Fields
  /api/v2/journeys:
    get:
      operationId: Journeys_list
      summary: Search Journeys
      description: Search Journeys - Journeys are the templates that can be used to create user journeys.
      parameters:
        - name: filters
          in: query
          required: false
          schema:
            type: object
            properties:
              title:
                type: string
                description: Comma separated list of title
                examples:
                  - Offer, Next Offer
              journey_type:
                type: string
                description: Comma separated list of journey types
                examples:
                  - pre_offer, offer, post_offer, onboarding, offboarding
              published:
                type: boolean
                examples:
                  - true
          explode: false
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          explode: false
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
          explode: false
        - name: order_by
          in: query
          required: false
          schema:
            type: string
            default: created_at
          explode: false
        - name: direction
          in: query
          required: false
          schema:
            type: string
            default: asc
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Journey'
      tags:
        - Journeys
  /api/v2/journeys/{id}:
    get:
      operationId: Journeys_show
      summary: Fetch Journey
      description: Fetch a Journey
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Journey'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      tags:
        - Journeys
  /api/v2/user_journeys:
    get:
      operationId: UserJourneys_list
      summary: Search User Journeys
      description: Search User Journeys - User Journeys are the journeys that are assigned to a user.
      parameters:
        - name: filters
          in: query
          required: false
          schema:
            type: object
            properties:
              user_id:
                type: string
                description: Comma separated list of User IDs
                examples:
                  - 64891c74d5ee1bb16dfdafd8,64891e2ad5ee1bb16dfdafd9
              journey_id:
                type: string
                description: Comma separated list of Journey IDs
                examples:
                  - 64891c74d5ee1bb16dfdafd8,64891e2ad5ee1bb16dfdafd9
              office_location_id:
                type: string
                description: Comma separated list of Office Location IDs
                examples:
                  - 64891c74d5ee1bb16dfdafd8,64891e2ad5ee1bb16dfdafd9
              journey_type:
                type: string
                description: Comma separated list of journey types
                examples:
                  - pre_offer, offer, post_offer, onboarding, offboarding
              state:
                type: string
                description: Comma separated list of states
                examples:
                  - draft, needs_attention, pending_approval, approved, rejected, rescinded, user_pending, submitted, declined, completed
              custom_fields:
                $ref: '#/components/schemas/CustomFieldsValueObject'
          explode: false
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
          explode: false
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
          explode: false
        - name: order_by
          in: query
          required: false
          schema:
            type: string
            default: created_at
          explode: false
        - name: direction
          in: query
          required: false
          schema:
            type: string
            default: asc
          explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/UserJourney'
      tags:
        - User Journeys
    post:
      operationId: UserJourneys_create
      summary: Create User Journey
      description: Create a User Journey
      parameters: []
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserJourney'
        '422':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      tags:
        - User Journeys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserJourneyCreate'
  /api/v2/user_journeys/{id}:
    get:
      operationId: UserJourneys_show
      summary: Fetch User Journey
      description: Fetch a User Journey
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserJourney'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
      tags:
        - User Journeys
    patch:
      operationId: UserJourneys_update
      summary: Update User Journey
      description: Update a User Journey
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserJourney'
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      tags:
        - User Journeys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserJourneyUpdate'
  /api/v2/user_journeys/{id}/rescind:
    delete:
      operationId: UserJourneys_rescind
      summary: Rescind User Journey
      description: Rescind User Journey
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: 'There is no content to send for this request, but the headers may be useful. '
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
        '422':
          description: Client error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      tags:
        - User Journeys
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rescind_reason:
                  type: string
              required:
                - rescind_reason
security:
  - BearerAuth: []
components:
  schemas:
    Address:
      type: object
      required:
        - city
        - country
      properties:
        line_1:
          type: string
          examples:
            - 31 St, 34 West
        line_2:
          type: string
          examples:
            - 8th Avenue
        line_3:
          type: string
        city:
          type: string
          examples:
            - New York
        state:
          type: string
          examples:
            - New York
        postal_code:
          type: string
          examples:
            - '100018'
        country:
          type: string
          examples:
            - USA
        current:
          type: boolean
          examples:
            - true
        permanent:
          type: boolean
          examples:
            - true
        start_date:
          type: string
          format: date
          examples:
            - '2021-10-23'
        end_date:
          type: string
          format: date
          examples:
            - '2023-10-23'
    Attachment:
      type: object
      properties:
        file_name:
          type: string
          examples:
            - abc.pdf
        file_content_base64:
          type: string
          examples:
            - SGVsbG8gdGhlcmUgOi0pIEZpbmQgYW55dGhpbmcgZXhjaXRpbmc/
        responses:
          type: object
          properties:
            field_name_1:
              type: string
              examples:
                - abc
            field_name_2:
              type: string
              examples:
                - cba
          description: Responses provided in PDF form fields (only present when attachment is a PDF with form fields)
    CustomField:
      type: object
      required:
        - id
        - journey_type
        - name
        - key
        - data_type
        - mandatory
        - allowed_values
        - list_of_values_map_id
        - created_at
        - allowed_rule_set_types
        - allowed_placeholder_type
      properties:
        id:
          type: string
          examples:
            - '12345'
        journey_type:
          type: string
          examples:
            - offer
        name:
          type: string
          examples:
            - Start date
        key:
          type: string
          examples:
            - '1234'
        data_type:
          type: string
          examples:
            - Datetime
        mandatory:
          type: boolean
          examples:
            - false
        mapping:
          type: string
          examples:
            - salutation, nickname, title, university, current_location, employee_id, profile_photo_url, division, hire_type, company_code, relocation_type, job_profile_id
        validation_rule:
          type: string
          examples:
            - regexp, list_of_values_map, list, previous_date_time, future_date_time, workday_job_profile, workday_organization
        regexp_pattern:
          type: string
          description: Required if validation_rule is regexp
          examples:
            - ^[a-zA-Z0-9]+$
        allowed_values:
          type: array
          items:
            type: string
          description: Required if validation_rule is list
          examples:
            - - a
              - b
              - c
        list_of_values_map_id:
          type: string
          description: Required if validation_rule is list_of_values_map
          examples:
            - LegalEntityLOV - refer to References API for more details
        created_at:
          type: string
          examples:
            - '2025-01-01'
        deactivated:
          type: boolean
          examples:
            - false
        rule_settable:
          type: boolean
          description: Used in Assignment Rules
          examples:
            - false
        placeholderable:
          type: boolean
          description: Used in placeholders
          examples:
            - false
        allowed_rule_set_types:
          type: array
          items:
            type: string
          examples:
            - - journey
              - module
              - child_module
              - task
              - communication
              - report
        allowed_placeholder_type:
          type: array
          items:
            type: string
          examples:
            - - journey
              - communication
              - html_editor_task
        workday_organization_type:
          type: string
          description: Required if validation_rule is workday_organization
          examples:
            - Supervisory, Pay_Group, Cost_Center, Company, Cost_Center_Hierarchy, Location_Hierarchy, External_Payroll_Company, Company_Hierarchy
    CustomFieldCreate:
      type: object
      required:
        - journey_type
        - name
        - key
        - data_type
        - mandatory
        - allowed_values
        - list_of_values_map_id
        - created_at
        - allowed_rule_set_types
        - allowed_placeholder_type
      properties:
        journey_type:
          type: string
          examples:
            - offer
        name:
          type: string
          examples:
            - Start date
        key:
          type: string
          examples:
            - '1234'
        data_type:
          type: string
          examples:
            - Datetime
        mandatory:
          type: boolean
          examples:
            - false
        mapping:
          type: string
          examples:
            - salutation, nickname, title, university, current_location, employee_id, profile_photo_url, division, hire_type, company_code, relocation_type, job_profile_id
        validation_rule:
          type: string
          examples:
            - regexp, list_of_values_map, list, previous_date_time, future_date_time, workday_job_profile, workday_organization
        regexp_pattern:
          type: string
          description: Required if validation_rule is regexp
          examples:
            - ^[a-zA-Z0-9]+$
        allowed_values:
          type: array
          items:
            type: string
          description: Required if validation_rule is list
          examples:
            - - a
              - b
              - c
        list_of_values_map_id:
          type: string
          description: Required if validation_rule is list_of_values_map
          examples:
            - LegalEntityLOV - refer to References API for more details
        created_at:
          type: string
          examples:
            - '2025-01-01'
        deactivated:
          type: boolean
          examples:
            - false
        rule_settable:
          type: boolean
          description: Used in Assignment Rules
          examples:
            - false
        placeholderable:
          type: boolean
          description: Used in placeholders
          examples:
            - false
        allowed_rule_set_types:
          type: array
          items:
            type: string
          examples:
            - - journey
              - module
              - child_module
              - task
              - communication
              - report
        allowed_placeholder_type:
          type: array
          items:
            type: string
          examples:
            - - journey
              - communication
              - html_editor_task
        workday_organization_type:
          type: string
          description: Required if validation_rule is workday_organization
          examples:
            - Supervisory, Pay_Group, Cost_Center, Company, Cost_Center_Hierarchy, Location_Hierarchy, External_Payroll_Company, Company_Hierarchy
    CustomFieldsValueObject:
      type: object
      required:
        - id
        - value
        - name
        - key
      properties:
        id:
          type: string
          examples:
            - '1234'
        value:
          type: string
          examples:
            - custom field value
        name:
          type: string
          examples:
            - custom field name
        key:
          type: string
          examples:
            - '1234'
    Document:
      type: object
      properties:
        document_type:
          type: string
          examples:
            - offer_letter
        document_number:
          type: string
          examples:
            - '1234'
        document_title:
          type: string
          examples:
            - Offer Letter
        document_description:
          type: string
          examples:
            - Offer Letter to the Joe
        issuer:
          type: string
          examples:
            - Issuer
        issuer_city:
          type: string
          examples:
            - New York
        issuer_state:
          type: string
          examples:
            - New York
        issuer_country:
          type: string
          examples:
            - USA
        issued_date:
          type: string
          format: date
          examples:
            - '2021-10-23'
        expiry_date:
          type: string
          format: date
          examples:
            - '2023-10-23'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
    Education:
      type: object
      properties:
        school_name:
          type: string
          examples:
            - School Name
        degree:
          type: string
          examples:
            - Degree
        student_id:
          type: string
          examples:
            - '1001'
        time_type:
          type: string
          examples:
            - Full Time
        major:
          type: string
          examples:
            - Communications
        minor:
          type: string
          examples:
            - Publications
        gpa:
          type: number
          format: float
          examples:
            - 4
        specialization:
          type: string
          examples:
            - IT
        graduation_date:
          type: string
          format: date
          examples:
            - '2021-10-23'
        grade:
          type: string
          examples:
            - A
        name_while_attending:
          type: string
          examples:
            - Jon Doe
        start_date:
          type: string
          format: date
          examples:
            - '2021-10-23'
        end_date:
          type: string
          format: date
          examples:
            - '2023-10-23'
        address:
          $ref: '#/components/schemas/Address'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
    Journey:
      type: object
      required:
        - id
        - title
        - journey_type
        - publishing_state
        - created_at
      properties:
        id:
          type: string
          examples:
            - '12345'
        title:
          type: string
          examples:
            - Offer
        journey_type:
          type: string
          examples:
            - offer
        publishing_state:
          type: string
          examples:
            - unpublished, published, draft
        created_at:
          type: string
          examples:
            - 2025/01/01
    NotFoundError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - NOT_FOUND
        message:
          type: string
    OfferLetterRequest:
      type: object
      required:
        - user_id
        - offer_id
        - job_application_id
        - office_location_id
        - start_date
      properties:
        user_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          description: Unique ID of the user
          examples:
            - 64892208d5ee1bb16dfdafda
        offer_id:
          type: string
          description: Unique ID of the Offer
          examples:
            - O3112-333
        job_application_id:
          type: string
          description: Unique ID of the Job Application
          examples:
            - J-O3112
        office_location_id:
          type: object
          properties:
            workday:
              type: string
              examples:
                - LOCATION-3-69
          description: "JSON where key is name of external service, e.g. {'HRIS_ID': 'NEWYORK'. There must be an office location in Xpand with a matching employee id. See reference values here for existing office location external ids"
        start_date:
          type: string
          format: date
          description: Start date of the new hire
          examples:
            - '2023-10-23'
        legal_entity:
          type: string
          description: See reference values here for existing legal entity values.
          examples:
            - Xpand Limited
        job_title:
          type: string
          description: Job Title of the offer
          examples:
            - Steamboat Captain
        currency:
          type: string
          description: ISO 4217 Currency Code
          examples:
            - USD
        base_salary:
          type: integer
          description: Basic Salary
          examples:
            - 45000
        end_date:
          type: string
          format: date
          description: End date of the new hire
          examples:
            - '2023-10-23'
        induction_date:
          type: string
          format: date
          description: Induction Date
          examples:
            - '2023-10-23'
        expiration_date:
          type: string
          format: date
          description: Expiration date of an offer
          examples:
            - '2023-10-23'
        offer_dispositioned:
          type: string
          description: dispositioning the offer
          examples:
            - 'Y'
        campus:
          type: string
          examples:
            - 'Y'
        compensation:
          type: integer
          description: Total compensation of the offer (Base + Bonus + Allowes)
          examples:
            - 100000
        non_compete_duration:
          type: integer
          examples:
            - 0
        supplemental_non_compete_duration:
          type: integer
          examples:
            - 1
        flsa_status:
          type: string
          description: Exempt/Non-Exempt NY/CA wage forms
          examples:
            - Exempt
        respond_by_date:
          type: string
          format: date
          description: Date by when action to be taken on offer
          examples:
            - '2023-10-23'
        attorney_only:
          type: boolean
          examples:
            - true
        confidential:
          type: boolean
          examples:
            - true
        regulated:
          type: boolean
          examples:
            - true
        regulated_status:
          type: string
          examples:
            - Active
        smcr:
          type: boolean
          description: identify if someone is Senior Manager
          examples:
            - true
        job_profile_id:
          type: string
          examples:
            - Job Family
        business_unit_id:
          type: string
          examples:
            - Business Unit
        department_code:
          type: string
          examples:
            - Department Code
        position_type:
          type: string
          examples:
            - Position Type
        pay_rate:
          type: string
          examples:
            - Pay Rate
        job_level:
          type: string
          examples:
            - Level 1
        cost_center_id:
          type: string
          examples:
            - Cost Center
        time_type:
          type: string
          examples:
            - Full Time
        employee_type:
          type: string
          examples:
            - Regular
        job_code:
          type: string
          examples:
            - Engineer
        target_salary:
          type: integer
          examples:
            - 10000
        max_salary:
          type: integer
          examples:
            - 100000
        rsu:
          type: integer
          examples:
            - 5000
        annual_bonus_percent:
          type: integer
          examples:
            - 10
        signing_bonus_amount:
          type: integer
          examples:
            - 7000
        commission_amount:
          type: integer
          examples:
            - 3000
        car_allowance:
          type: integer
          examples:
            - 1000
        relocation:
          type: boolean
          examples:
            - true
        relocation_flex_allowance:
          type: integer
          examples:
            - 2000
        work_from_home:
          type: boolean
          examples:
            - false
        immigration:
          type: boolean
          examples:
            - false
        visa_sponsorship_notes:
          type: string
          examples:
            - Clear
        urgent:
          type: boolean
          examples:
            - false
        is_exempt:
          type: boolean
          examples:
            - false
        notes:
          type: string
          examples:
            - Ready to send the offer
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
    OfferLetterResponseFull:
      type: object
      required:
        - id
        - user_id
        - offer_id
        - job_application_id
        - office_location_id
        - start_date
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          examples:
            - 64891c74d5ee1bb16dfdafd8
        user_id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          description: Unique ID of the user
          examples:
            - 64892208d5ee1bb16dfdafda
        offer_id:
          type: string
          description: Unique ID of the Offer
          examples:
            - O3112-333
        job_application_id:
          type: string
          description: Unique ID of the Job Application
          examples:
            - J-O3112
        office_location_id:
          type: object
          properties:
            workday:
              type: string
              examples:
                - LOCATION-3-69
          description: "JSON where key is name of external service, e.g. {'HRIS_ID': 'NEWYORK'. There must be an office location in Xpand with a matching employee id. See reference values here for existing office location external ids"
        start_date:
          type: string
          format: date
          description: Start date of the new hire
          examples:
            - '2023-10-23'
        legal_entity:
          type: string
          description: See reference values here for existing legal entity values.
          examples:
            - Xpand Limited
        job_title:
          type: string
          description: Job Title of the offer
          examples:
            - Steamboat Captain
        currency:
          type: string
          description: ISO 4217 Currency Code
          examples:
            - USD
        base_salary:
          type: integer
          description: Basic Salary
          examples:
            - 45000
        end_date:
          type: string
          format: date
          description: End date of the new hire
          examples:
            - '2023-10-23'
        induction_date:
          type: string
          format: date
          description: Induction Date
          examples:
            - '2023-10-23'
        expiration_date:
          type: string
          format: date
          description: Expiration date of an offer
          examples:
            - '2023-10-23'
        offer_dispositioned:
          type: string
          description: dispositioning the offer
          examples:
            - 'Y'
        campus:
          type: string
          examples:
            - 'Y'
        compensation:
          type: integer
          description: Total compensation of the offer (Base + Bonus + Allowes)
          examples:
            - 100000
        non_compete_duration:
          type: integer
          examples:
            - 0
        supplemental_non_compete_duration:
          type: integer
          examples:
            - 1
        flsa_status:
          type: string
          description: Exempt/Non-Exempt NY/CA wage forms
          examples:
            - Exempt
        respond_by_date:
          type: string
          format: date
          description: Date by when action to be taken on offer
          examples:
            - '2023-10-23'
        attorney_only:
          type: boolean
          examples:
            - true
        confidential:
          type: boolean
          examples:
            - true
        regulated:
          type: boolean
          examples:
            - true
        regulated_status:
          type: string
          examples:
            - Active
        smcr:
          type: boolean
          description: identify if someone is Senior Manager
          examples:
            - true
        job_profile_id:
          type: string
          examples:
            - Job Family
        business_unit_id:
          type: string
          examples:
            - Business Unit
        department_code:
          type: string
          examples:
            - Department Code
        position_type:
          type: string
          examples:
            - Position Type
        pay_rate:
          type: string
          examples:
            - Pay Rate
        job_level:
          type: string
          examples:
            - Level 1
        cost_center_id:
          type: string
          examples:
            - Cost Center
        time_type:
          type: string
          examples:
            - Full Time
        employee_type:
          type: string
          examples:
            - Regular
        job_code:
          type: string
          examples:
            - Engineer
        target_salary:
          type: integer
          examples:
            - 10000
        max_salary:
          type: integer
          examples:
            - 100000
        rsu:
          type: integer
          examples:
            - 5000
        annual_bonus_percent:
          type: integer
          examples:
            - 10
        signing_bonus_amount:
          type: integer
          examples:
            - 7000
        commission_amount:
          type: integer
          examples:
            - 3000
        car_allowance:
          type: integer
          examples:
            - 1000
        relocation:
          type: boolean
          examples:
            - true
        relocation_flex_allowance:
          type: integer
          examples:
            - 2000
        work_from_home:
          type: boolean
          examples:
            - false
        immigration:
          type: boolean
          examples:
            - false
        visa_sponsorship_notes:
          type: string
          examples:
            - Clear
        urgent:
          type: boolean
          examples:
            - false
        is_exempt:
          type: boolean
          examples:
            - false
        notes:
          type: string
          examples:
            - Ready to send the offer
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
    OfferLetterResponseSimple:
      type: object
      required:
        - id
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          examples:
            - 64891c74d5ee1bb16dfdafd8
    OfficeLocationId:
      type: object
      required:
        - id
        - external_ids
      properties:
        workday:
          type: string
          examples:
            - LOCATION-3-69
        id:
          type: string
          examples:
            - LOCATION-3-69
        external_ids:
          type: object
          properties:
            hris_id:
              type: string
              examples:
                - 'E-1234'
        address1:
          type: string
          examples:
            - 123 Main St
        address2:
          type: string
          examples:
            - Suite 200
        address3:
          type: string
          examples:
            - Building B
        city:
          type: string
          examples:
            - New York
        state:
          type: string
          examples:
            - NY
        region:
          type: string
          examples:
            - Northeast
        country:
          type: string
          examples:
            - USA
        postal_code:
          type: string
          examples:
            - '10001'
        time_zone:
          type: string
          examples:
            - NZT
        latitude:
          type: number
          format: float
          examples:
            - 3.12332
        longitude:
          type: number
          format: float
          examples:
            - 3.12332
    PhoneNumber:
      type: object
      properties:
        number:
          type: string
          description: E.164 Format
          examples:
            - '+14044580998'
        type:
          type: string
          enum:
            - mobile
            - landline
            - unknown
          examples:
            - mobile
        primary:
          type: boolean
          examples:
            - true
    UserJourney:
      type: object
      required:
        - id
        - journey_id
      properties:
        id:
          type: string
          examples:
            - '123456898'
        journey_id:
          type: string
          examples:
            - '123456'
        journey_type:
          type: string
          examples:
            - pre_offer
        user_id:
          type: string
          examples:
            - '123456'
        state:
          allOf:
            - $ref: '#/components/schemas/UserJourneyState'
          examples:
            - approved
        created_at:
          type: string
          examples:
            - '2025-01-01'
        office_location:
          $ref: '#/components/schemas/OfficeLocationId'
        custom_field_values:
          allOf:
            - $ref: '#/components/schemas/CustomFieldsValueObject'
          description: Custom fields object for the user journey - we pass the key for any configured custom fields for this journey type.
    UserJourneyCreate:
      type: object
      required:
        - journey_id
      properties:
        journey_id:
          type: string
          examples:
            - '123456'
        journey_type:
          type: string
          examples:
            - pre_offer
        user_id:
          type: string
          examples:
            - '123456'
        state:
          allOf:
            - $ref: '#/components/schemas/UserJourneyState'
          examples:
            - approved
        created_at:
          type: string
          examples:
            - '2025-01-01'
        office_location_id:
          $ref: '#/components/schemas/OfficeLocationId'
        custom_fields:
          allOf:
            - $ref: '#/components/schemas/CustomFieldsValueObject'
          description: Custom fields object for the user journey - we pass the key for any configured custom fields for this journey type.
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
    UserJourneyQueryData:
      type: object
      properties:
        id:
          type: string
          examples:
            - '12345'
        user_id:
          type: string
          examples:
            - '1234'
        state:
          allOf:
            - $ref: '#/components/schemas/UserJourneyState'
          examples:
            - draft
        custom_fields:
          $ref: '#/components/schemas/CustomFieldsValueObject'
    UserJourneyState:
      type: string
      enum:
        - draft
        - needs_attention
        - pending_approval
        - approved
        - rejected
        - rescinded
        - user_pending
        - submitted
        - declined
        - completed
    UserJourneyUpdate:
      type: object
      required:
        - journey_id
      properties:
        journey_id:
          type: string
          examples:
            - '123456'
        state:
          allOf:
            - $ref: '#/components/schemas/UserJourneyState'
          examples:
            - approved
        created_at:
          type: string
          examples:
            - '2025-01-01'
        office_location_id:
          $ref: '#/components/schemas/OfficeLocationId'
        custom_fields:
          allOf:
            - $ref: '#/components/schemas/CustomFieldsValueObject'
          description: Custom fields object for the user journey - we pass the key for any configured custom fields for this journey type.
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
    UserRequest:
      type: object
      required:
        - email
        - first_name
        - last_name
        - start_date
        - employee_type
        - candidate_status
        - cost_center_id
        - external_ids
        - office_location_id
        - recruiter_ids
      properties:
        email:
          allOf:
            - $ref: '#/components/schemas/email'
          description: 'Must be a valid email address. Must be unique for each user. Non case-sensitive. Regex validation: ^(?!...)[a-zA-Z0-9][\w-.]@[A-Za-z\d-]+(.[A-Za-z\d-]+)*.[A-Za-z]+$'
          examples:
            - daniel@personal.com
        work_email:
          allOf:
            - $ref: '#/components/schemas/email'
          description: 'Must be a valid email address. Must be unique for each user. Non case-sensitive. Regex validation: ^(?!...)[a-zA-Z0-9][\w-.]@[A-Za-z\d-]+(.[A-Za-z\d-]+)*.[A-Za-z]+$'
          examples:
            - daniel@company.com
        first_name:
          type: string
          description: Must not contain numbers or any of the following special characters !@#$%^&*()
          examples:
            - Daniel
        last_name:
          type: string
          description: Must not contain numbers or any of the following special characters !@#$%^&*()
          examples:
            - Smith
        middle_name:
          type: string
          description: Must not contain numbers or any of the following special characters !@#$%^&*()
          examples:
            - Jones
        start_date:
          type: string
          format: date
          description: 'Format: YYYY-MM-DD. Can be present, or future dates only.'
          examples:
            - '2023-09-08'
        employee_type:
          type: string
          description: See reference values here for allowed employee type values.
          examples:
            - Regular
        candidate_status:
          type: string
          description: See reference values here for allowed candidate status values.
          examples:
            - offer_accepted
        legal_entity:
          type: string
          description: See reference values here for existing legal entity values.
          examples:
            - Xpand Limited
        cost_center_id:
          type: string
          description: See reference values here for existing cost center values.
          examples:
            - Cost Center
        relocation_type:
          type: string
          description: Allowes the relocation type values.
          examples:
            - global_relocation
        blocked:
          type: boolean
          description: Disable or enable a user account in Xpand.
          examples:
            - false
        reason_blocked:
          type: string
          description: A brief description of why the user why the user account is being disabled in Xpand
          examples:
            - Inactive in ATS System
        external_ids:
          type: object
          properties:
            ats_id:
              type: string
              examples:
                - A-1234
            hris_id:
              type: string
              examples:
                - 'E-1234'
          description: This is the collection of unique id of the Applicant Tracking System (ATS) and employee id of the Human Resource Information Systems (HRIS)
        office_location_id:
          type: object
          properties:
            workday:
              type: string
              examples:
                - LOCATION-3-69
          description: "JSON where key is name of external service, e.g. {'HRIS_ID': 'NEWYORK'. There must be an office location in Xpand with a matching employee id. See reference values here for existing office location external ids"
        recruiter_ids:
          type: object
          properties:
            recruiter:
              type: object
              properties:
                hris_id:
                  type: string
                  examples:
                    - R-1111
            recruiting_coordinator:
              type: object
              properties:
                hris_id:
                  type: string
                  examples:
                    - R-2222
            recruiting_manager:
              type: object
              properties:
                hris_id:
                  type: string
                  examples:
                    - R-3333
          description: "JSON where key is name of external service, e.g. {:recruiter=>{'HRIS_SYS'=>'12345'}, recruiting_manager=>{'HRIS_SYS'=>'56789'}} (There must be a recruiter in Xpand or HRIS_SYS(Ex: workday) with a matching employee id)"
        manager_ids:
          type: object
          properties:
            hris_id:
              type: array
              items:
                type: string
              examples:
                - - M-1111
                  - M-2222
          description: "JSON where key is name of external service, e.g. {'HRIS_SYS': ['123456', '45678']} (There must be a manager in Xpand or HRIS with a matching employee id)"
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
        educations:
          type: array
          items:
            $ref: '#/components/schemas/Education'
        work_experiences:
          type: array
          items:
            $ref: '#/components/schemas/WorkExperience'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
    UserRequestUpdate:
      type: object
      properties:
        email:
          allOf:
            - $ref: '#/components/schemas/email'
          description: 'Must be a valid email address. Must be unique for each user. Non case-sensitive. Regex validation: ^(?!...)[a-zA-Z0-9][\w-.]@[A-Za-z\d-]+(.[A-Za-z\d-]+)*.[A-Za-z]+$'
          examples:
            - daniel@personal.com
        work_email:
          allOf:
            - $ref: '#/components/schemas/email'
          description: 'Must be a valid email address. Must be unique for each user. Non case-sensitive. Regex validation: ^(?!...)[a-zA-Z0-9][\w-.]@[A-Za-z\d-]+(.[A-Za-z\d-]+)*.[A-Za-z]+$'
          examples:
            - daniel@company.com
        first_name:
          type: string
          description: Must not contain numbers or any of the following special characters !@#$%^&*()
          examples:
            - Daniel
        last_name:
          type: string
          description: Must not contain numbers or any of the following special characters !@#$%^&*()
          examples:
            - Smith
        middle_name:
          type: string
          description: Must not contain numbers or any of the following special characters !@#$%^&*()
          examples:
            - Jones
        start_date:
          type: string
          format: date
          description: 'Format: YYYY-MM-DD. Can be present, or future dates only.'
          examples:
            - '2023-09-08'
        employee_type:
          type: string
          description: See reference values here for allowed employee type values.
          examples:
            - Regular
        candidate_status:
          type: string
          description: See reference values here for allowed candidate status values.
          examples:
            - offer_accepted
        legal_entity:
          type: string
          description: See reference values here for existing legal entity values.
          examples:
            - Xpand Limited
        cost_center_id:
          type: string
          description: See reference values here for existing cost center values.
          examples:
            - Cost Center
        relocation_type:
          type: string
          description: Allowes the relocation type values.
          examples:
            - global_relocation
        blocked:
          type: boolean
          description: Disable or enable a user account in Xpand.
          examples:
            - false
        reason_blocked:
          type: string
          description: A brief description of why the user why the user account is being disabled in Xpand
          examples:
            - Inactive in ATS System
        external_ids:
          type: object
          properties:
            ats_id:
              type: string
              examples:
                - A-1234
            hris_id:
              type: string
              examples:
                - 'E-1234'
          description: This is the collection of unique id of the Applicant Tracking System (ATS) and employee id of the Human Resource Information Systems (HRIS)
        office_location_id:
          type: object
          properties:
            workday:
              type: string
              examples:
                - LOCATION-3-69
          description: "JSON where key is name of external service, e.g. {'HRIS_ID': 'NEWYORK'. There must be an office location in Xpand with a matching employee id. See reference values here for existing office location external ids"
        recruiter_ids:
          type: object
          properties:
            recruiter:
              type: object
              properties:
                hris_id:
                  type: string
                  examples:
                    - R-1111
            recruiting_coordinator:
              type: object
              properties:
                hris_id:
                  type: string
                  examples:
                    - R-2222
            recruiting_manager:
              type: object
              properties:
                hris_id:
                  type: string
                  examples:
                    - R-3333
          description: "JSON where key is name of external service, e.g. {:recruiter=>{'HRIS_SYS'=>'12345'}, recruiting_manager=>{'HRIS_SYS'=>'56789'}} (There must be a recruiter in Xpand or HRIS_SYS(Ex: workday) with a matching employee id)"
        manager_ids:
          type: object
          properties:
            hris_id:
              type: array
              items:
                type: string
              examples:
                - - M-1111
                  - M-2222
          description: "JSON where key is name of external service, e.g. {'HRIS_SYS': ['123456', '45678']} (There must be a manager in Xpand or HRIS with a matching employee id)"
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
        educations:
          type: array
          items:
            $ref: '#/components/schemas/Education'
        work_experiences:
          type: array
          items:
            $ref: '#/components/schemas/WorkExperience'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
    UserResponseFull:
      type: object
      required:
        - id
        - first_name
        - last_name
        - email
        - start_date
        - external_ids
        - office_location_id
        - recruiter_ids
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          examples:
            - 64891c74d5ee1bb16dfdafd8
        first_name:
          type: string
          examples:
            - John
        last_name:
          type: string
          examples:
            - Doe
        email:
          allOf:
            - $ref: '#/components/schemas/email'
          examples:
            - john@example.com
        start_date:
          type: string
          format: date
          examples:
            - '2023-10-23'
        external_ids:
          type: object
          properties:
            ats_id:
              type: string
              examples:
                - A-1234
            hris_id:
              type: string
              examples:
                - 'E-1234'
        office_location_id:
          type: object
          properties:
            workday:
              type: string
              examples:
                - LOCATION-3-69
        recruiter_ids:
          type: object
          properties:
            recruiter:
              type: object
              properties:
                hris_id:
                  type: string
                  examples:
                    - R-1111
            recruiting_coordinator:
              type: object
              properties:
                hris_id:
                  type: string
                  examples:
                    - R-2222
            recruiting_manager:
              type: object
              properties:
                hris_id:
                  type: string
                  examples:
                    - R-3333
        manager_ids:
          type: object
          properties:
            hris_id:
              type: array
              items:
                type: string
              examples:
                - - M-1111
                  - M-2222
        documents:
          type: array
          items:
            $ref: '#/components/schemas/Document'
        educations:
          type: array
          items:
            $ref: '#/components/schemas/Education'
        work_experiences:
          type: array
          items:
            $ref: '#/components/schemas/WorkExperience'
        addresses:
          type: array
          items:
            $ref: '#/components/schemas/Address'
        phone_numbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
    UserResponseSimple:
      type: object
      required:
        - id
      properties:
        id:
          allOf:
            - $ref: '#/components/schemas/uuid'
          examples:
            - 64891c74d5ee1bb16dfdafd8
    ValidationError:
      type: object
      required:
        - code
        - message
        - details
      properties:
        code:
          type: string
          enum:
            - VALIDATION_ERROR
        message:
          type: string
        details:
          type: array
          items:
            type: string
    WorkExperience:
      type: object
      properties:
        employer:
          type: string
          examples:
            - Employer
        employee_id:
          type: string
          examples:
            - 'E1234'
        current:
          type: boolean
          examples:
            - true
        job_title:
          type: string
          examples:
            - Engineer
        department:
          type: string
          examples:
            - Department
        employment_type:
          type: string
          examples:
            - Regular
        reason_for_leaving:
          type: string
          examples:
            - Change in technology
        salary:
          type: integer
          examples:
            - 10000
        manager_name:
          type: string
          examples:
            - Manager 1
        manager_phone:
          type: string
          examples:
            - '+14044578776'
        manager_email:
          allOf:
            - $ref: '#/components/schemas/email'
          examples:
            - manager@xpand.io
        hr_name:
          type: string
          examples:
            - HR 1
        hr_phone:
          type: string
          examples:
            - '+14044578777'
        hr_email:
          allOf:
            - $ref: '#/components/schemas/email'
          examples:
            - hr@xpand.io
        start_date:
          type: string
          format: date
          examples:
            - '2021-10-23'
        end_date:
          type: string
          format: date
          examples:
            - '2023-10-23'
        address:
          $ref: '#/components/schemas/Address'
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
    email:
      type: string
      format: email
    uuid:
      type: string
      format: uuid
  securitySchemes:
    BearerAuth:
      type: http
      scheme: Bearer