--- updatedAt: 2026-06-11T10:09:40.000Z agentTools: projectIndex: https://docs.oysterhr.com/v0.1/llms.txt --- # Submit onboarding form for review This API endpoint allows you to submit the onboarding form for review by Oyster Staff. # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Endpoints", "version": "v0.1" }, "components": { "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer" } }, "schemas": { "onboardingForm": { "type": "object", "properties": { "sections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string" }, "fields": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/textField" }, { "$ref": "#/components/schemas/dateField" }, { "$ref": "#/components/schemas/selectField" }, { "$ref": "#/components/schemas/countryField" }, { "$ref": "#/components/schemas/subdivisionField" }, { "$ref": "#/components/schemas/groupField" }, { "$ref": "#/components/schemas/bankAccountField" }, { "$ref": "#/components/schemas/documentField" } ] } } }, "required": [ "title", "fields" ] } }, "state": { "type": "string", "enum": [ "DRAFT", "UNSTARTED", "COMPLETED", "PENDING_REVIEW" ] } }, "required": [ "sections", "state" ] }, "textField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "TEXT" ] }, "value": { "oneOf": [ { "type": "string", "nullable": true } ] } }, "required": [ "label", "value" ] } ] }, "dateField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DATE" ] }, "value": { "oneOf": [ { "type": "string", "format": "date", "nullable": true } ] } }, "required": [ "label", "value" ] } ] }, "selectField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SELECT" ] }, "mode": { "type": "string", "enum": [ "RADIO", "DROPDOWN", "CHECKBOX" ] }, "select": { "type": "string", "enum": [ "ONE", "MULTI" ] }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "nullable": true }, "label": { "type": "string" } }, "required": [ "value", "label" ] } }, "value": { "oneOf": [ { "type": "string", "nullable": true }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "label", "mode", "select", "options", "value" ] } ] }, "countryField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "COUNTRY" ] }, "value": { "oneOf": [ { "type": "string", "nullable": true } ] } }, "required": [ "label", "value" ] } ] }, "subdivisionField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "SUBDIVISION" ] }, "value": { "oneOf": [ { "type": "string", "nullable": true } ] } }, "required": [ "label", "value" ] } ] }, "groupField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "GROUP" ] }, "title": { "oneOf": [ { "type": "string" } ] }, "fields": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/textField" }, { "$ref": "#/components/schemas/dateField" }, { "$ref": "#/components/schemas/countryField" }, { "$ref": "#/components/schemas/subdivisionField" }, { "$ref": "#/components/schemas/selectField" }, { "$ref": "#/components/schemas/groupField" }, { "$ref": "#/components/schemas/bankAccountField" }, { "$ref": "#/components/schemas/documentField" } ] } } }, "required": [ "title", "fields" ] } ] }, "bankAccountField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "BANK_ACCOUNT" ] }, "value": { "oneOf": [ { "type": "boolean", "nullable": true } ] } }, "required": [ "label", "value" ] } ] }, "documentField": { "allOf": [ { "$ref": "#/components/schemas/baseField" }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "DOCUMENT" ] }, "value": { "oneOf": [ { "type": "object", "nullable": true, "properties": { "id": { "type": "string" } }, "required": [ "id" ] } ] } }, "required": [ "label", "value" ] } ] }, "baseField": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string", "enum": [ "TEXT", "DATE", "COUNTRY", "SELECT", "GROUP", "BANK_ACCOUNT", "DOCUMENT", "SUBDIVISION" ] }, "category": { "type": "string", "nullable": true }, "required": { "type": "boolean" }, "enabled": { "oneOf": [ { "type": "boolean" }, { "type": "object", "additionalProperties": true } ] }, "label": { "type": "string" }, "assistiveText": { "type": "string" }, "assistiveTextPlain": { "type": "string" }, "templateDocuments": { "type": "array", "description": "Oyster template documents linked from the field's assistive text.", "items": { "type": "object", "properties": { "url": { "type": "string" }, "lastModifiedAt": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "url", "lastModifiedAt" ] } }, "validationMessage": { "type": "string" } }, "required": [ "id", "type", "required", "category", "enabled", "templateDocuments" ] }, "errors": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } }, "required": [ "errors" ] } } }, "paths": { "/v0.1/hiring/employments/{id}/onboarding/form/submit": { "post": { "summary": "Submit onboarding form for review", "tags": [ "Employments" ], "description": "This API endpoint allows you to submit the onboarding form for review by Oyster Staff.", "security": [ { "bearer_auth": [ "manage" ] } ], "parameters": [ { "name": "id", "in": "path", "description": "Employment ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Onboarding form marked as pending review", "content": { "application/json": { "examples": { "Onboarding form marked as pending review": { "value": { "data": { "sections": [ { "title": "A Generic Page", "fields": [ { "id": "text_field", "type": "TEXT", "label": "A Text Field", "category": "REQUIRED_INFO", "required": true, "enabled": true, "value": "Lorem the ipsum, dolor the sit", "templateDocuments": [], "assistiveText": "Lorem ipsum", "assistiveTextPlain": "Lorem ipsum" }, { "id": "optional_text_field", "type": "TEXT", "label": "An Optional Text Field", "category": "OPTIONAL_INFO", "required": false, "enabled": true, "value": null, "templateDocuments": [], "assistiveText": "You can leave this blank", "assistiveTextPlain": "You can leave this blank" }, { "id": "date_field", "type": "DATE", "label": "A Date Field", "category": "OPTIONAL_INFO", "required": false, "enabled": true, "value": "1986-01-31", "templateDocuments": [], "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "validationMessage": "Must be a valid date in YYYY-MM-DD format" } ] }, { "title": "A page with fields that have limited choices", "fields": [ { "id": "dropdown_field", "type": "SELECT", "label": "A Dropdown Field", "category": "REQUIRED_INFO", "required": true, "enabled": true, "value": "choice_1", "templateDocuments": [], "options": [ { "value": "choice_1", "label": "The first choice" }, { "value": "choice_2", "label": "The second choice" } ], "mode": "DROPDOWN", "select": "ONE" }, { "id": "radio_field", "type": "SELECT", "label": "A Radio Field", "category": "REQUIRED_INFO", "required": true, "enabled": true, "value": "choice_2", "templateDocuments": [], "options": [ { "value": "choice_1", "label": "The first choice" }, { "value": "choice_2", "label": "The second choice" } ], "mode": "RADIO", "select": "ONE" } ] }, { "title": "A page with file uploads", "fields": [ { "id": "file_upload_1", "type": "DOCUMENT", "label": "File Upload 1", "category": "EXTRA_INFO", "required": false, "enabled": true, "value": { "id": "Aa2fc3a8" }, "templateDocuments": [] } ] }, { "title": "A page with checkbox group", "fields": [ { "id": "checkbox_group_1", "type": "SELECT", "label": "Checkbox Group 1", "category": "EXTRA_INFO", "required": false, "enabled": true, "value": [ "choice_1", "choice_2" ], "templateDocuments": [], "options": [ { "value": "choice_1", "label": "The first choice" }, { "value": "choice_2", "label": "The second choice" } ], "mode": "CHECKBOX", "select": "MULTI" } ] }, { "title": "A page with field groups", "fields": [ { "id": "first_field_group", "type": "GROUP", "category": null, "required": false, "enabled": true, "templateDocuments": [], "assistiveText": "Where you currently live", "assistiveTextPlain": "Where you currently live", "title": "Field group with single field", "fields": [ { "id": "field_group_text_field", "type": "TEXT", "label": "A Text Field", "category": "EXTRA_INFO", "required": true, "enabled": true, "value": "Ut sciatis, meum animum", "templateDocuments": [] } ] }, { "id": "second_field_group", "type": "GROUP", "category": null, "required": false, "enabled": true, "templateDocuments": [], "title": "Field group with multiple fields", "fields": [ { "id": "field_group_text_field_2", "type": "TEXT", "label": "A Text Field in a Field Group without title", "category": "EXTRA_INFO", "required": false, "enabled": true, "value": "Radio Gaga, Radio Gugu", "templateDocuments": [] }, { "id": "field_group_text_field_3", "type": "TEXT", "label": "Another Text Field", "category": "EXTRA_INFO", "required": false, "enabled": true, "value": null, "templateDocuments": [] } ] } ] }, { "title": "A page with bank account", "fields": [ { "id": "bank_account_1", "type": "BANK_ACCOUNT", "label": "A bank account field", "category": "EXTRA_INFO", "required": true, "enabled": true, "value": true, "templateDocuments": [] } ] } ], "state": "PENDING_REVIEW" } } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/onboardingForm" } }, "required": [ "data" ] } } } }, "422": { "description": "Onboarding is not available for this employment", "content": { "application/json": { "examples": { "Unresolved clarification request issues": { "value": { "errors": [ { "message": "Cannot submit onboarding form for review with an unresolved clarification request issue.", "field": "text_field" } ] } }, "Onboarding form already completed": { "value": { "errors": [ { "message": "Onboarding is not available for this employment." } ] } }, "Onboarding is not available for this employment": { "value": { "errors": [ { "message": "Onboarding is not available for this employment." } ] } } }, "schema": { "$ref": "#/components/schemas/errors" } } } } } } } }, "servers": [ { "url": "https://api.oysterhr.com", "description": "Production server" }, { "url": "https://api-sandbox.oysterhr.com", "description": "Sandbox server" } ] } ```