> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # CreateSubmission # Package: forms # Namespace: FormSubmissionService # Method link: https://dev.wix.com/docs/api-reference/crm/forms/form-submissions/create-submission.md ## Permission Scopes: Manage Submissions: SCOPE.DC-FORMS.MANAGE-SUBMISSIONS ## Introduction > **Note:** The Form Submission API only works with the Wix Forms app. Call [GetAppInstance](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/get-app-instance.md) to confirm that the app named `wix_forms` is installed on the site.
Creates a new submission. --- ## REST API ### Schema ``` Method: createSubmission Description: > **Note:** The Form Submission API only works with the Wix Forms app. Call [GetAppInstance](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/get-app-instance.md) to confirm that the app named `wix_forms` is installed on the site.
Creates a new submission. URL: https://www.wixapis.com/v4/submissions Method: POST # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: submission, submission.formId Method parameters: param name: additionalMetadata | type: additionalMetadata | description: Optional metadata passed to SPI implementer, allowing clients to include additional business-specific data. param name: captchaToken | type: captchaToken | description: Captcha token. param name: submission | type: FormSubmission | description: Form submission that was created or retrieved. | required: true - name: formId | type: string | description: GUID of the form which the submission belongs to. | required: true - name: status | type: SubmissionStatus | description: Status of the submission. - enum: - PENDING: A submission is created, but has not yet been recorded in the Wix Forms collection. - CONFIRMED: A submission is recorded in the Wix Forms collection. - PAYMENT_WAITING: A form submission requiring payment is created. - PAYMENT_CANCELED: An order of a form submission is canceled. - name: submissions | type: Map | description: Submission values where `key` is the form field and `value` is the data submitted for the given field. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: createdDate | type: string | description: Date and time the form submission was created. - name: seen | type: boolean | description: Whether a site owner marked a submission as "seen". - name: extendedFields | type: ExtendedFields | description: Data extension object that holds users' and apps' fields. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: orderDetails | type: OrderDetails | description: Order details.
Note: This object is only applicable when submitting a form in the Wix Payments app. - name: contactId | type: string | description: Contact GUID of a site visitor who created the submission. - name: accessRestriction | type: string | description: Authorized viewer GUID. - name: tags | type: PublicTags | description: Tag GUIDs collections associated with the current entity. - name: tags | type: TagList | description: Tags that are exposed to anyone who has access to the labeled entity itself, including site members and visitors. - name: tagIds | type: array | description: List of tag GUIDs - name: appointmentDetails | type: AppointmentDetails | description: Appointment details. This object is only applicable when submitting a form that creates a booking appointment. - name: staffMemberId | type: string | description: GUID of the staff member assigned to the appointment. - name: staffMemberName | type: string | description: Name of the staff member assigned to the appointment. Return type: CreateSubmissionResponse - name: submission | type: FormSubmission | description: The created submission. - name: id | type: string | description: Submission GUID. - name: formId | type: string | description: GUID of the form which the submission belongs to. - name: namespace | type: string | description: The app which the form submissions belong to. For example, the namespace for the Wix Forms app is `wix.form_app.form`. Call `Get Submission` to retrieve the namespace. - name: status | type: SubmissionStatus | description: Status of the submission. - enum: - PENDING: A submission is created, but has not yet been recorded in the Wix Forms collection. - CONFIRMED: A submission is recorded in the Wix Forms collection. - PAYMENT_WAITING: A form submission requiring payment is created. - PAYMENT_CANCELED: An order of a form submission is canceled. - name: submissions | type: Map | description: Submission values where `key` is the form field and `value` is the data submitted for the given field. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: createdDate | type: string | description: Date and time the form submission was created. - name: updatedDate | type: string | description: Date and time the form submission was updated. - name: revision | type: string | description: Revision number, which increments by 1 each time the form submission is updated. To prevent conflicting changes, the existing revision must be used when updating a form submission. - name: submitter | type: Submitter | description: GUID of the visitor that submitted the form. - ONE-OF: - name: memberId | type: string | description: Member GUID. - name: visitorId | type: string | description: Visitor GUID. - name: applicationId | type: string | description: Application GUID. - name: userId | type: string | description: User GUID. - name: seen | type: boolean | description: Whether a site owner marked a submission as "seen". - name: extendedFields | type: ExtendedFields | description: Data extension object that holds users' and apps' fields. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: orderDetails | type: OrderDetails | description: Order details.
Note: This object is only applicable when submitting a form in the Wix Payments app. - name: orderId | type: string | description: GUID of the order related to submission (only applicable if a form has payments). - name: number | type: string | description: Order number. - name: currency | type: string | description: Currency. - name: itemSubtotal | type: string | description: Item subtotal. - name: checkoutId | type: string | description: GUID of the checkout related to submission (only applicable if a form has payments). - name: contactId | type: string | description: Contact GUID of a site visitor who created the submission. - name: accessRestriction | type: string | description: Authorized viewer GUID. - name: tags | type: PublicTags | description: Tag GUIDs collections associated with the current entity. - name: tags | type: TagList | description: Tags that are exposed to anyone who has access to the labeled entity itself, including site members and visitors. - name: tagIds | type: array | description: List of tag GUIDs - name: appointmentDetails | type: AppointmentDetails | description: Appointment details. This object is only applicable when submitting a form that creates a booking appointment. - name: staffMemberId | type: string | description: GUID of the staff member assigned to the appointment. - name: staffMemberName | type: string | description: Name of the staff member assigned to the appointment. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: SUBMISSION_VALIDATION | Description: Form submission contains validation errors. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: FORM_NOT_FOUND | Description: Couldn't find the form. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: SITE_IS_A_TEMPLATE | Description: Site is a template and can't accept form submissions. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: INVALID_CAPTCHA | Description: Captcha verification failed. HTTP Code: 503 | Status Code: UNAVAILABLE | Application Code: FORM_RETRIEVAL_ERROR | Description: Form retrieval failed due to a temporary service issue. ``` ### Examples ### CreateSubmission ```curl ~~~cURL curl -X POST \ 'http://www.wixapis.com/form-submission/v4/submissions' \ -H 'Content-Type: application/json' \ -H 'Authorization: ' \ -d '{ "submission": { "formId": "e62e3011-55cf-4de3-a497-e097b52d86b8", "submissions": { "first_name": "Adam", "last_name": "Fisher" } } }' ~~~ ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.forms.FormSubmissionService.createSubmission(submission, options) Description: > **Note:** The Form Submission API only works with the Wix Forms app. Call [GetAppInstance](https://dev.wix.com/docs/rest/api-reference/app-management/apps/app-instance/get-app-instance.md) to confirm that the app named `wix_forms` is installed on the site.
Creates a new submission. # Note: If the parameter `a.b` is listed under required parameters, `b` is only required if `a` is also present. Required parameters: submission, submission.formId Method parameters: param name: options | type: CreateSubmissionOptions none - name: captchaToken | type: string | description: Captcha token. - name: additionalMetadata | type: object | description: Optional metadata passed to SPI implementer, allowing clients to include additional business-specific data. param name: submission | type: FormSubmission | description: Form submission that was created or retrieved. | required: true - name: formId | type: string | description: GUID of the form which the submission belongs to. | required: true - name: status | type: SubmissionStatus | description: Status of the submission. - enum: - PENDING: A submission is created, but has not yet been recorded in the Wix Forms collection. - CONFIRMED: A submission is recorded in the Wix Forms collection. - PAYMENT_WAITING: A form submission requiring payment is created. - PAYMENT_CANCELED: An order of a form submission is canceled. - name: submissions | type: Map | description: Submission values where `key` is the form field and `value` is the data submitted for the given field. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: _createdDate | type: Date | description: Date and time the form submission was created. - name: seen | type: boolean | description: Whether a site owner marked a submission as "seen". - name: extendedFields | type: ExtendedFields | description: Data extension object that holds users' and apps' fields. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: orderDetails | type: OrderDetails | description: Order details.
Note: This object is only applicable when submitting a form in the Wix Payments app. - name: contactId | type: string | description: Contact GUID of a site visitor who created the submission. - name: accessRestriction | type: string | description: Authorized viewer GUID. - name: tags | type: PublicTags | description: Tag GUIDs collections associated with the current entity. - name: tags | type: TagList | description: Tags that are exposed to anyone who has access to the labeled entity itself, including site members and visitors. - name: tagIds | type: array | description: List of tag GUIDs - name: appointmentDetails | type: AppointmentDetails | description: Appointment details. This object is only applicable when submitting a form that creates a booking appointment. - name: staffMemberId | type: string | description: GUID of the staff member assigned to the appointment. - name: staffMemberName | type: string | description: Name of the staff member assigned to the appointment. Return type: PROMISE - name: _id | type: string | description: Submission GUID. - name: formId | type: string | description: GUID of the form which the submission belongs to. - name: namespace | type: string | description: The app which the form submissions belong to. For example, the namespace for the Wix Forms app is `wix.form_app.form`. Call `Get Submission` to retrieve the namespace. - name: status | type: SubmissionStatus | description: Status of the submission. - enum: - PENDING: A submission is created, but has not yet been recorded in the Wix Forms collection. - CONFIRMED: A submission is recorded in the Wix Forms collection. - PAYMENT_WAITING: A form submission requiring payment is created. - PAYMENT_CANCELED: An order of a form submission is canceled. - name: submissions | type: Map | description: Submission values where `key` is the form field and `value` is the data submitted for the given field. - ONE-OF: - name: nullValue | type: | description: - name: numberValue | type: number | description: - name: stringValue | type: string | description: - name: boolValue | type: boolean | description: - name: structValue | type: object | description: - name: listValue | type: ListValue | description: - name: values | type: array | description: - name: _createdDate | type: Date | description: Date and time the form submission was created. - name: _updatedDate | type: Date | description: Date and time the form submission was updated. - name: revision | type: string | description: Revision number, which increments by 1 each time the form submission is updated. To prevent conflicting changes, the existing revision must be used when updating a form submission. - name: submitter | type: Submitter | description: GUID of the visitor that submitted the form. - ONE-OF: - name: memberId | type: string | description: Member GUID. - name: visitorId | type: string | description: Visitor GUID. - name: applicationId | type: string | description: Application GUID. - name: userId | type: string | description: User GUID. - name: seen | type: boolean | description: Whether a site owner marked a submission as "seen". - name: extendedFields | type: ExtendedFields | description: Data extension object that holds users' and apps' fields. - name: namespaces | type: object | description: Extended field data. Each key corresponds to the namespace of the app that created the extended fields. The value of each key is structured according to the schema defined when the extended fields were configured. You can only access fields for which you have the appropriate permissions. Learn more about [extended fields](https://dev.wix.com/docs/rest/articles/getting-started/extended-fields.md). - name: orderDetails | type: OrderDetails | description: Order details.
Note: This object is only applicable when submitting a form in the Wix Payments app. - name: orderId | type: string | description: GUID of the order related to submission (only applicable if a form has payments). - name: number | type: string | description: Order number. - name: currency | type: string | description: Currency. - name: itemSubtotal | type: string | description: Item subtotal. - name: checkoutId | type: string | description: GUID of the checkout related to submission (only applicable if a form has payments). - name: contactId | type: string | description: Contact GUID of a site visitor who created the submission. - name: accessRestriction | type: string | description: Authorized viewer GUID. - name: tags | type: PublicTags | description: Tag GUIDs collections associated with the current entity. - name: tags | type: TagList | description: Tags that are exposed to anyone who has access to the labeled entity itself, including site members and visitors. - name: tagIds | type: array | description: List of tag GUIDs - name: appointmentDetails | type: AppointmentDetails | description: Appointment details. This object is only applicable when submitting a form that creates a booking appointment. - name: staffMemberId | type: string | description: GUID of the staff member assigned to the appointment. - name: staffMemberName | type: string | description: Name of the staff member assigned to the appointment. Possible Errors: HTTP Code: 400 | Status Code: INVALID_ARGUMENT | Application Code: SUBMISSION_VALIDATION | Description: Form submission contains validation errors. HTTP Code: 404 | Status Code: NOT_FOUND | Application Code: FORM_NOT_FOUND | Description: Couldn't find the form. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: SITE_IS_A_TEMPLATE | Description: Site is a template and can't accept form submissions. HTTP Code: 428 | Status Code: FAILED_PRECONDITION | Application Code: INVALID_CAPTCHA | Description: Captcha verification failed. HTTP Code: 503 | Status Code: UNAVAILABLE | Application Code: FORM_RETRIEVAL_ERROR | Description: Form retrieval failed due to a temporary service issue. ``` ### Examples ### Create a submission with a media file (with $w) ```javascript /******************************************** * Backend code - my-backend-file.web.js/ts * *******************************************/ import { Permissions, webMethod } from '@wix/web-methods'; import { submissions } from '@wix/forms'; import { auth } from '@wix/essentials'; // Get a URL for uploading a media file export const myGetMediaUploadUrlFunction = webMethod(Permissions.Anyone, async (formId, filename, mimeType) => { try { const elevatedGetMediaUploadUrl = auth.elevate(submissions.getMediaUploadUrl); const uploadUrl = await elevatedGetMediaUploadUrl(formId, filename, mimeType); return uploadUrl; } catch (error) { console.error(error); // Handle the error } }); // Create a submission export const myCreateSubmissionFunction = webMethod(Permissions.Anyone, async (submission, options) => { try { const elevatedCreateSubmission = auth.elevate(submissions.createSubmission); const createdSubmission = await elevatedCreateSubmission(submission, options); return createdSubmission; } catch (error) { console.error(error); // Handle the error } }); /************* * Page code * ************/ import { myCreateSubmissionFunction, myGetMediaUploadUrlFunction } from 'backend/my-backend-file.web'; const submission = { "formId": "21bcb6c7-02b3-4ed1-b6db-7856094fac03", "seen": false, "revision": "6", "submissions": { "first_name": "Jane", "last_name": "McBride", "file_upload_7a7f": "" } } const formId = "21bcb6c7-02b3-4ed1-b6db-7856094fac03" const filename = "photo.jpg" const mimeType = "image/jpg" $w.onReady(() => { myGetMediaUploadUrlFunction(formId, filename, mimeType).then((result) => { submission.submissions.file_upload_7a7f = result.uploadUrl // push the URL into the submissions object }); /* Upload a media file to the generated URL by following the information written in the Upload API (https://www.wix.com/velo/reference/wix-media-v2/upload-api) article. */ myCreateSubmissionFunction(submission).then((result) => { console.log('Success! Created submission:', result); }); }); ``` ### Create a submission ```javascript import { submissions } from '@wix/forms'; /* Sample submission value: { "formId": "21bcb6c7-02b3-4ed1-b6db-7856094fac03", "seen": false, "status": "PENDING", "submissions": { "first_name": "Patsy", "last_name": "McBride" } } */ export async function myCreateSubmissionFunction(submission, options) { try { const createdSubmission = await submissions.createSubmission(submission, options); console.log('Success! Created submission:', createdSubmission); return createdSubmission; } catch (error) { console.error(error); // Handle the error } } /* Promise resolves to: { "submission": { "formId": "21bcb6c7-02b3-4ed1-b6db-7856094fac03", "namespace": "wix.form_app.form", "status": "PENDING", "submissions": { "first_name": "Patsy", "last_name": "McBride" }, "revision": "1", "submitter": { "applicationId": "151e476a-715e-ec33-db9a-a7ff4d51f70a" }, "seen": false, "_id": "f8281b62-1b2f-45bf-ba7d-f041d7653d2d", "_createdDate": "2023-12-28T12:55:55.630Z", "_updatedDate": "2023-12-28T12:55:55.746Z" } } */ ``` ### createSubmission (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { submissions } from '@wix/forms'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { submissions }, // Include the auth strategy and host as relevant }); async function createSubmission(submission,options) { const response = await myWixClient.submissions.createSubmission(submission,options); }; ``` ---