openapi: 3.1.0 info: title: Xpand API version: 2025-03 tags: - name: Users - name: Journeys - name: User Journeys - name: Custom Fields - name: References - name: Offers (Deprecated) 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/Responses.OfferLetterList' required: - data tags: - Offers (Deprecated) deprecated: true 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/Responses.OfferLetterCreate' required: - data tags: - Offers (Deprecated) requestBody: required: true content: application/json: schema: type: object properties: data: type: object properties: attributes: $ref: '#/components/schemas/Requests.OfferLetterUpsert' required: - attributes required: - data deprecated: true /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 (Deprecated) deprecated: true /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/Responses.UserList' 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/Responses.UserCreate' required: - data tags: - Users requestBody: required: true content: application/json: schema: type: object properties: data: type: object properties: attributes: $ref: '#/components/schemas/Requests.UserUpsert' 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/Responses.UserShow' 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/Responses.UserUpdate' required: - data tags: - Users requestBody: required: true content: application/json: schema: type: object properties: data: type: object properties: attributes: $ref: '#/components/schemas/Requests.UserUpsertUpdate' /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 transition_type: type: string description: Comma separated list of Transition 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/Responses.CustomFieldList' 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/Responses.CustomFieldCreate' '422': description: Client error content: application/json: schema: $ref: '#/components/schemas/Errors.ValidationError' tags: - Custom Fields requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Requests.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: $ref: '#/components/schemas/UUID' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Responses.CustomFieldShow' '404': description: The server cannot find the requested resource. content: application/json: schema: $ref: '#/components/schemas/Errors.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: $ref: '#/components/schemas/UUID' 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. Once deactivated it cannot be used in the Create User Journey API parameters: - name: id in: path required: true schema: $ref: '#/components/schemas/UUID' 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 transition_type: type: string description: Comma separated list of transition 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/Responses.JourneyList' 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: $ref: '#/components/schemas/UUID' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Responses.JourneyShow' '404': description: The server cannot find the requested resource. content: application/json: schema: $ref: '#/components/schemas/Errors.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 transition_type: type: string description: Comma separated list of transition 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: type: object properties: key1: type: string key2: type: string 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/Responses.UserJourneyList' 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/Responses.UserJourneyCreate' '422': description: Client error content: application/json: schema: $ref: '#/components/schemas/Errors.ValidationError' tags: - User Journeys requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Requests.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: $ref: '#/components/schemas/UUID' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Responses.UserJourneyShow' '404': description: The server cannot find the requested resource. content: application/json: schema: $ref: '#/components/schemas/Errors.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: $ref: '#/components/schemas/UUID' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Responses.UserJourneyUpdate' '404': description: The server cannot find the requested resource. content: application/json: schema: $ref: '#/components/schemas/Errors.NotFoundError' '422': description: Client error content: application/json: schema: $ref: '#/components/schemas/Errors.ValidationError' tags: - User Journeys requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/Requests.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: $ref: '#/components/schemas/UUID' 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/Errors.NotFoundError' '422': description: Client error content: application/json: schema: $ref: '#/components/schemas/Errors.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: Base64: type: string format: Base64 examples: - WW91J3JlIGEgY3VyaW91cyBmZWxsb3cgOy0p Date: type: string format: YYYY-MM-DD examples: - '2026-01-01' DateTime: type: string format: iso8601 examples: - '2026-02-01T01:02:03Z' Email: type: string format: email examples: - testing@example.com Enums.JourneyPublishingState: type: string enum: - unpublished - published - draft examples: - published Enums.JourneyTransitionType: type: string enum: - pre_offer - offer - post_offer - onboarding - offboarding examples: - pre_offer Enums.UserJourneyState: type: string enum: - draft - needs_attention - pending_approval - approved - rejected - rescinded - user_pending - submitted - declined - completed examples: - approved Errors.NotFoundError: type: object required: - code - message properties: code: type: string enum: - NOT_FOUND message: type: string Errors.ValidationError: type: object required: - code - message - details properties: code: type: string enum: - VALIDATION_ERROR message: type: string details: type: array items: type: string Models.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: $ref: '#/components/schemas/Date' end_date: $ref: '#/components/schemas/Date' Models.Attachment: type: object properties: file_name: type: string examples: - abc.pdf file_content_base64: $ref: '#/components/schemas/Base64' 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) Models.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: $ref: '#/components/schemas/Date' expiry_date: $ref: '#/components/schemas/Date' attachments: type: array items: $ref: '#/components/schemas/Models.Attachment' Models.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: $ref: '#/components/schemas/Date' grade: type: string examples: - A name_while_attending: type: string examples: - Jon Doe start_date: $ref: '#/components/schemas/Date' end_date: $ref: '#/components/schemas/Date' address: $ref: '#/components/schemas/Models.Address' attachments: type: array items: $ref: '#/components/schemas/Models.Attachment' Models.OfficeLocation: type: object required: - id - city - country properties: id: $ref: '#/components/schemas/UUID' external_ids: type: object properties: workday: type: string examples: - LOCATION-3-69 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 Models.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 Models.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: $ref: '#/components/schemas/Email' hr_name: type: string examples: - HR 1 hr_phone: type: string examples: - '+14044578777' hr_email: $ref: '#/components/schemas/Email' start_date: $ref: '#/components/schemas/Date' end_date: $ref: '#/components/schemas/Date' address: $ref: '#/components/schemas/Models.Address' attachments: type: array items: $ref: '#/components/schemas/Models.Attachment' Requests.CustomFieldCreate: type: object required: - transition_type - name - key - data_type - mandatory - allowed_values - list_of_values_map_id - created_at - allowed_rule_set_types - allowed_placeholder_type properties: transition_type: $ref: '#/components/schemas/Enums.JourneyTransitionType' 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 Requests.OfferLetterUpsert: type: object required: - user_id - offer_id - job_application_id - office_location_id - start_date properties: user_id: $ref: '#/components/schemas/UUID' 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: allOf: - $ref: '#/components/schemas/Date' description: Start date of the new hire 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: allOf: - $ref: '#/components/schemas/Date' description: End date of the new hire induction_date: allOf: - $ref: '#/components/schemas/Date' description: Induction Date expiration_date: allOf: - $ref: '#/components/schemas/Date' description: Expiration date of an offer 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: allOf: - $ref: '#/components/schemas/Date' description: Date by when action to be taken on offer 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/Models.Document' Requests.UserJourneyCreate: type: object properties: transition_type: $ref: '#/components/schemas/Enums.JourneyTransitionType' user_id: anyOf: - $ref: '#/components/schemas/UUID' - type: object properties: workday: type: string examples: - LOCATION-3-69 state: $ref: '#/components/schemas/Enums.UserJourneyState' expiration_date: $ref: '#/components/schemas/Date' office_location_id: anyOf: - $ref: '#/components/schemas/UUID' - type: object properties: workday: type: string examples: - LOCATION-3-69 custom_fields: type: object unevaluatedProperties: type: string examples: - key1: Hello key2: World documents: type: array items: 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 attachments: type: array items: type: object properties: file_name: type: string examples: - abc.pdf file_content_base64: $ref: '#/components/schemas/Base64' Requests.UserJourneyUpdate: type: object properties: state: $ref: '#/components/schemas/Enums.UserJourneyState' expiration_date: $ref: '#/components/schemas/Date' office_location_id: anyOf: - $ref: '#/components/schemas/UUID' - type: object properties: workday: type: string examples: - LOCATION-3-69 custom_fields: type: object unevaluatedProperties: type: string examples: - key1: Hello key2: World documents: type: array items: 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 attachments: type: array items: type: object properties: file_name: type: string examples: - abc.pdf file_content_base64: $ref: '#/components/schemas/Base64' Requests.UserUpsert: 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]+$' 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]+$' 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: allOf: - $ref: '#/components/schemas/Date' description: 'Format: YYYY-MM-DD. Can be present, or future dates only.' 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/Models.Document' educations: type: array items: $ref: '#/components/schemas/Models.Education' work_experiences: type: array items: $ref: '#/components/schemas/Models.WorkExperience' addresses: type: array items: $ref: '#/components/schemas/Models.Address' phone_numbers: type: array items: $ref: '#/components/schemas/Models.PhoneNumber' Requests.UserUpsertUpdate: 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]+$' 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]+$' 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: allOf: - $ref: '#/components/schemas/Date' description: 'Format: YYYY-MM-DD. Can be present, or future dates only.' 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/Models.Document' educations: type: array items: $ref: '#/components/schemas/Models.Education' work_experiences: type: array items: $ref: '#/components/schemas/Models.WorkExperience' addresses: type: array items: $ref: '#/components/schemas/Models.Address' phone_numbers: type: array items: $ref: '#/components/schemas/Models.PhoneNumber' Responses.CustomFieldCreate: type: object required: - id - transition_type - name - key - data_type - mandatory - allowed_values - list_of_values_map_id - created_at - allowed_rule_set_types - allowed_placeholder_type properties: id: $ref: '#/components/schemas/UUID' transition_type: $ref: '#/components/schemas/Enums.JourneyTransitionType' 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 Responses.CustomFieldList: type: object required: - id - transition_type - name - key - data_type - mandatory - allowed_values - list_of_values_map_id - created_at - allowed_rule_set_types - allowed_placeholder_type properties: id: $ref: '#/components/schemas/UUID' transition_type: $ref: '#/components/schemas/Enums.JourneyTransitionType' 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 Responses.CustomFieldShow: type: object required: - id - transition_type - name - key - data_type - mandatory - allowed_values - list_of_values_map_id - created_at - allowed_rule_set_types - allowed_placeholder_type properties: id: $ref: '#/components/schemas/UUID' transition_type: $ref: '#/components/schemas/Enums.JourneyTransitionType' 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 Responses.JourneyList: type: object required: - id - transition_type - publishing_state - title - created_at properties: id: $ref: '#/components/schemas/UUID' transition_type: $ref: '#/components/schemas/Enums.JourneyTransitionType' publishing_state: $ref: '#/components/schemas/Enums.JourneyPublishingState' title: type: string created_at: $ref: '#/components/schemas/DateTime' Responses.JourneyShow: type: object required: - id - transition_type - publishing_state - title - created_at properties: id: $ref: '#/components/schemas/UUID' transition_type: $ref: '#/components/schemas/Enums.JourneyTransitionType' publishing_state: $ref: '#/components/schemas/Enums.JourneyPublishingState' title: type: string created_at: $ref: '#/components/schemas/DateTime' Responses.OfferLetterCreate: type: object required: - id properties: id: $ref: '#/components/schemas/UUID' Responses.OfferLetterList: type: object required: - id - user_id - offer_id - job_application_id - office_location_id - start_date properties: id: $ref: '#/components/schemas/UUID' user_id: $ref: '#/components/schemas/UUID' 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: allOf: - $ref: '#/components/schemas/Date' description: Start date of the new hire 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: allOf: - $ref: '#/components/schemas/Date' description: End date of the new hire induction_date: allOf: - $ref: '#/components/schemas/Date' description: Induction Date expiration_date: allOf: - $ref: '#/components/schemas/Date' description: Expiration date of an offer 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: allOf: - $ref: '#/components/schemas/Date' description: Date by when action to be taken on offer 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/Models.Document' Responses.UserCreate: type: object required: - id properties: id: $ref: '#/components/schemas/UUID' Responses.UserJourneyCreate: type: object required: - id - journey_id - user_id - transition_type - state - created_at - expiration_date - office_location - custom_field_values properties: id: $ref: '#/components/schemas/UUID' journey_id: $ref: '#/components/schemas/UUID' user_id: $ref: '#/components/schemas/UUID' transition_type: $ref: '#/components/schemas/Enums.JourneyTransitionType' state: $ref: '#/components/schemas/Enums.UserJourneyState' created_at: $ref: '#/components/schemas/Date' expiration_date: $ref: '#/components/schemas/Date' office_location: anyOf: - $ref: '#/components/schemas/Models.OfficeLocation' - type: 'null' custom_field_values: type: array items: type: object 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' Responses.UserJourneyList: type: object required: - id - journey_id - user_id - transition_type - state - created_at - expiration_date - office_location - custom_field_values properties: id: $ref: '#/components/schemas/UUID' journey_id: $ref: '#/components/schemas/UUID' user_id: $ref: '#/components/schemas/UUID' transition_type: $ref: '#/components/schemas/Enums.JourneyTransitionType' state: $ref: '#/components/schemas/Enums.UserJourneyState' created_at: $ref: '#/components/schemas/Date' expiration_date: $ref: '#/components/schemas/Date' office_location: anyOf: - $ref: '#/components/schemas/Models.OfficeLocation' - type: 'null' custom_field_values: type: array items: type: object 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' Responses.UserJourneyShow: type: object required: - id - journey_id - user_id - transition_type - state - created_at - expiration_date - office_location - custom_field_values properties: id: $ref: '#/components/schemas/UUID' journey_id: $ref: '#/components/schemas/UUID' user_id: $ref: '#/components/schemas/UUID' transition_type: $ref: '#/components/schemas/Enums.JourneyTransitionType' state: $ref: '#/components/schemas/Enums.UserJourneyState' created_at: $ref: '#/components/schemas/Date' expiration_date: $ref: '#/components/schemas/Date' office_location: anyOf: - $ref: '#/components/schemas/Models.OfficeLocation' - type: 'null' custom_field_values: type: array items: type: object 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' Responses.UserJourneyUpdate: type: object required: - id - journey_id - user_id - transition_type - state - created_at - expiration_date - office_location - custom_field_values properties: id: $ref: '#/components/schemas/UUID' journey_id: $ref: '#/components/schemas/UUID' user_id: $ref: '#/components/schemas/UUID' transition_type: $ref: '#/components/schemas/Enums.JourneyTransitionType' state: $ref: '#/components/schemas/Enums.UserJourneyState' created_at: $ref: '#/components/schemas/Date' expiration_date: $ref: '#/components/schemas/Date' office_location: anyOf: - $ref: '#/components/schemas/Models.OfficeLocation' - type: 'null' custom_field_values: type: array items: type: object 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' Responses.UserList: type: object required: - id - first_name - last_name - email - start_date - external_ids - office_location_id - recruiter_ids properties: id: $ref: '#/components/schemas/UUID' first_name: type: string examples: - John last_name: type: string examples: - Doe email: $ref: '#/components/schemas/Email' start_date: $ref: '#/components/schemas/Date' 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/Models.Document' educations: type: array items: $ref: '#/components/schemas/Models.Education' work_experiences: type: array items: $ref: '#/components/schemas/Models.WorkExperience' addresses: type: array items: $ref: '#/components/schemas/Models.Address' phone_numbers: type: array items: $ref: '#/components/schemas/Models.PhoneNumber' Responses.UserShow: type: object required: - id - first_name - last_name - email - start_date - external_ids - office_location_id - recruiter_ids properties: id: $ref: '#/components/schemas/UUID' first_name: type: string examples: - John last_name: type: string examples: - Doe email: $ref: '#/components/schemas/Email' start_date: $ref: '#/components/schemas/Date' 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/Models.Document' educations: type: array items: $ref: '#/components/schemas/Models.Education' work_experiences: type: array items: $ref: '#/components/schemas/Models.WorkExperience' addresses: type: array items: $ref: '#/components/schemas/Models.Address' phone_numbers: type: array items: $ref: '#/components/schemas/Models.PhoneNumber' Responses.UserUpdate: type: object required: - id properties: id: $ref: '#/components/schemas/UUID' UUID: type: string format: uuid examples: - 69ae0e64b02bfe73a44ca479 securitySchemes: BearerAuth: type: http scheme: Bearer