> ## Documentation Index > Fetch the complete documentation index at: https://docs.megaport.com/llms.txt > Use this file to discover all available pages before exploring further. # Managing Megaport Marketplace Forms with the API > This help topic describes how to use the Megaport API to create and manage Megaport Marketplace forms for collecting customer information during connection requests. export const Anchor = ({name}) => { const errorPrefix = '\x1b[31;1;4mERROR\x1b[0m: Anchor -'; if (name === undefined || name === null || name === 'undefined') { console.error(`${errorPrefix} \`name\` must have a value — rendering an empty string instead`); return <>; } const raw = typeof name === 'string' ? name : JSON.stringify(name); const id = raw.replace(/\s+/g, '-').replace(/[^A-Za-z0-9_-]/g, '').replace(/-+/g, '-').replace(/^-+|-+$/g, ''); if (!id) { console.error(`${errorPrefix} \`name\` "${name}" sanitizes to an empty id — rendering an empty string instead`); return <>; } return ; }; This topic describes how to use the Megaport API to create and manage Megaport Marketplace forms. Service providers use these forms to collect onboarding information from customers during connection requests and integrate customer-provided information into provisioning workflows. This helps automate onboarding, accelerate approvals, and reduce manual communication. For more information, see [Megaport Marketplace Forms](/marketplace/forms). Before you begin, obtain a valid access token. For more information, see [Creating an API Key](/api/api-key). You must be a Company Admin to create and manage forms via the API. ## Use cases These API endpoints help service providers automate form management for their Megaport Marketplace services. Common use cases include: * Creating custom forms to collect specific onboarding information from customers. * Linking forms to services so customers can complete them when requesting connections. * Retrieving submitted form data for processing connection requests. * Integrating form data into your provisioning workflows. ## Prerequisites * You must have a Megaport Marketplace profile. For more information, see [Creating a Megaport Marketplace Profile](/marketplace/profile). * You must be a Company Admin to create and manage forms. ## Managing form definitions Form definitions define the structure and fields of forms that customers complete. Each form can contain multiple fields of different types. ### Supported field types Form field structure and validation are defined in JSON. These field types are supported in form definitions: | Type | Format | Description | | :------ | :-------------- | :--------------------------------------------------------------------------------------------------------------------------------------------- | | string | | A text field for short answers. | | string | format: "email" | A field for entering a contact email address. | | string | multiline: true | A text area for longer or more detailed responses. | | string | enum: \[...] | A drop-down field for selecting a single option from a list.
You must define at least 2 options, with a maximum of 100 options per field. | | integer | | A whole number value. | | number | | A numeric value (integer or decimal). | | boolean | | A true/false value, typically rendered as a check box. | | array | | A list of values. | | object | | A nested group of fields. | An example for adding an email: ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "type": "object", "properties": { "email": { "type": "string", "format": "email" } } } ``` and an example for adding a drop-down field: ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "inactive", "pending" ] } } } ``` ### Creating a form To create a new form definition, send a POST request to the forms endpoint with the form structure. After the form is created, it is set to the *Active* status by default and can be linked to your services. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} POST {baseUrl}/v3/marketplace/forms ``` **Request Body** | Field | Required | Description | | :------------ | :------- | :--------------------------------------------------------------- | | name | Yes | The name of the form. | | formStructure | Yes | A JSON object that defines the form fields and validation rules. | **Example Request** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "name": "Customer Onboarding Form", "formStructure": { "type": "object", "properties": { "companyName": { "type": "string", "title": "Company Name" }, "contactEmail": { "type": "string", "format": "email", "title": "Contact Email" }, "serviceType": { "type": "string", "title": "Service Type", "enum": ["Standard", "Premium", "Enterprise"] }, "additionalNotes": { "type": "string", "title": "Additional Notes", "multiline": true } }, "required": ["companyName", "contactEmail", "serviceType"] } } ``` **Example Response** A successful request returns the created form definition with its unique identifier. ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Form created", "data": { "formUid": "abc12345-6789-0def-ghij-klmnopqrstuv", "name": "Customer Onboarding Form", "status": "ACTIVE", "formStructure": { ... }, "createDate": "2026-01-15T10:30:00.000Z", "lastUpdate": "2026-01-15T10:30:00.000Z" } } ``` ### Listing forms To retrieve all form definitions for your company, send a GET request to the forms endpoint. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/forms ``` **Query Parameters** | Parameter | Required | Description | | :-------- | :------- | :------------------------------------------------------------------------------------------------------------------------- | | status | No | Filter by form status: `ACTIVE` or `ARCHIVED`.
By default, active forms are included and archived forms are excluded. | **Example Request** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/forms?status=ACTIVE ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Forms retrieved", "data": [ { "formUid": "abc12345-6789-0def-ghij-klmnopqrstuv", "name": "Customer Onboarding Form", "status": "ACTIVE", "formStructure": { ... }, "createDate": "2026-01-15T10:30:00.000Z", "lastUpdate": "2026-01-15T10:30:00.000Z" } ] } ``` ### Retrieving a form To retrieve a specific form definition, send a GET request with the form UID. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/forms/{formUid} ``` **Path Parameters** | Parameter | Description | | :-------- | :--------------------------------- | | formUid | The unique identifier of the form. | **Example Request** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/forms/abc12345-6789-0def-ghij-klmnopqrstuv ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Form retrieved", "data": { "formUid": "abc12345-6789-0def-ghij-klmnopqrstuv", "name": "Customer Onboarding Form", "status": "ACTIVE", "formStructure": { ... }, "createDate": "2026-01-15T10:30:00.000Z", "lastUpdate": "2026-01-15T10:30:00.000Z" } } ``` ### Updating a form To update an existing form definition, send a PUT request with the updated fields. Form definitions can be updated after a VXC connection has been requested using the form. Form requirements might change over time, so forms can be updated as required without affecting existing submissions. Form status cannot be updated. To change the form status to *Archived*, use the delete endpoint. This marks the form as *Archive* if it has submissions against it or permanently deletes it if there are no submissions. To reactivate an archived form, use the activate endpoint. For more information, see [Activating a form](#activate-form) and [Deleting a form](#delete-form). **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} PUT {baseUrl}/v3/marketplace/forms/{formUid} ``` **Path Parameters** | Parameter | Description | | :-------- | :------------------------------------------- | | formUid | The unique identifier of the form to update. | **Request Body** Include only the fields you want to update. You can update the `name` and `formStructure` fields. **Example Request** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "name": "Updated Customer Onboarding Form", "formStructure": { "type": "object", "properties": { "companyName": { "type": "string", "title": "Updated Company Name" }, } } } ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Form updated", "data": { "formUid": "abc12345-6789-0def-ghij-klmnopqrstuv", "name": "Updated Customer Onboarding Form", "status": "ACTIVE", "formStructure": { ... }, "createDate": "2026-01-15T10:30:00.000Z", "lastUpdate": "2026-01-16T14:00:00.000Z" } } ``` ### Activating a form To activate an archived or draft form, send a POST request to the activate endpoint. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} POST {baseUrl}/v3/marketplace/forms/{formUid}/activate ``` **Path Parameters** | Parameter | Description | | :-------- | :--------------------------------------------- | | formUid | The unique identifier of the form to activate. | **Example Request** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} POST {baseUrl}/v3/marketplace/forms/abc12345-6789-0def-ghij-klmnopqrstuv/activate ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Form activated", "data": { "formUid": "abc12345-6789-0def-ghij-klmnopqrstuv", "status": "ACTIVE" } } ``` ### Deleting a form To delete a form definition, send a DELETE request. If the form has service associations, these associations will be removed and the form will be deleted. If the form has linked submissions, it will be archived instead of deleted. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} DELETE {baseUrl}/v3/marketplace/forms/{formUid} ``` **Path Parameters** | Parameter | Description | | :-------- | :------------------------------------------- | | formUid | The unique identifier of the form to delete. | **Example Request** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} DELETE {baseUrl}/v3/marketplace/forms/abc12345-6789-0def-ghij-klmnopqrstuv ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Form deleted" } ``` ## Linking forms to services After creating a form definition, link it to your Megaport Marketplace services so customers can complete the form when requesting a connection. ### Attaching a form to a service To attach a form to a service, send a POST request to the service forms endpoint. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} POST {baseUrl}/v3/marketplace/service_forms ``` **Request Body** | Field | Required | Description | | :--------- | :------- | :--------------------------------------------------------- | | serviceUid | Yes | The unique identifier of the Megaport Marketplace service. | | formUid | Yes | The unique identifier of the form to attach. | **Example Request** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "serviceUid": "svc12345-6789-0def-ghij-klmnopqrstuv", "formUid": "abc12345-6789-0def-ghij-klmnopqrstuv" } ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Service form association created", "data": { "serviceFormUid": "assoc123-4567-89ab-cdef-ghijklmnopqr", "serviceUid": "svc12345-6789-0def-ghij-klmnopqrstuv", "formUid": "abc12345-6789-0def-ghij-klmnopqrstuv" } } ``` Each service can be linked to only one form, but a form can be linked to multiple services. ### Listing service-form associations To list all service-form associations, send a GET request with optional parameter filters. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/service_forms ``` **Query Parameters** | Parameter | Required | Description | | :--------- | :------- | :--------------------- | | serviceUid | No | Filter by service UID. | | formUid | No | Filter by form UID. | **Example Request** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/service_forms?serviceUid=svc12345-6789-0def-ghij-klmnopqrstuv ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Service form associations retrieved", "data": [ { "serviceFormUid": "assoc123-4567-89ab-cdef-ghijklmnopqr", "serviceUid": "svc12345-6789-0def-ghij-klmnopqrstuv", "formUid": "abc12345-6789-0def-ghij-klmnopqrstuv", "formStructure": { ... } } ] } ``` ### Updating a service-form association To change the form associated with a service, send a PUT request with the UID of the new form. This replaces the form currently associated with the service. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} PUT {baseUrl}/v3/marketplace/service_forms/{serviceFormUid} ``` **Path Parameters** | Parameter | Description | | :------------- | :----------------------------------------------------- | | serviceFormUid | The unique identifier of the service-form association. | **Request Body** | Field | Required | Description | | :------ | :------- | :--------------------------------------------- | | formUid | Yes | The unique identifier of the new form to link. | **Example Request** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "formUid": "newform12-3456-789a-bcde-fghijklmnopq" } ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Service form association updated", "data": { "serviceFormUid": "assoc123-4567-89ab-cdef-ghijklmnopqr", "serviceUid": "svc12345-6789-0def-ghij-klmnopqrstuv", "formUid": "newform12-3456-789a-bcde-fghijklmnopq" } } ``` ### Detaching a form from a service To remove a form from a service, send a DELETE request. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} DELETE {baseUrl}/v3/marketplace/service_forms/{serviceFormUid} ``` **Path Parameters** | Parameter | Description | | :------------- | :--------------------------------------------------------------- | | serviceFormUid | The unique identifier of the service-form association to remove. | **Example Request** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} DELETE {baseUrl}/v3/marketplace/service_forms/assoc123-4567-89ab-cdef-ghijklmnopqr ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Service form association deleted" } ``` ## Managing form submissions When customers request a connection to a service with a form configured, they submit the form data. Service providers can retrieve this data to review connection requests. ### Listing all form submissions To list all form submissions for your company's forms, send a GET request to the submissions endpoint. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/form_submissions ``` **Example Request** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/form_submissions ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Action completed successfully", "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy", "data": [ { "companyId": 123, "createDate": "2025-11-12T10:15:30.123Z", "formData": { "company_name": "Acme Corp", "industry": "technology", "number_of_locations": 3, "requires_redundancy": true }, "formDefinitionId": 42, "formStructure": { "type": "object", "properties": { "company_name": { "type": "string" }, "industry": { "type": "string", "enum": [ "technology", "finance", "healthcare", "other" ] }, "number_of_locations": { "type": "integer" }, "requires_redundancy": { "type": "boolean" } }, "required": [ "company_name", "industry" ] }, "lastUpdate": "2025-11-12T10:15:30.123Z", "uid": "e900d0d5-1030-4e29-b2d8-816ad4263190", "vxcOrderId": 100 } ] } ``` ### Retrieving a form submission To retrieve a specific form submission, send a GET request with the submission UID. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/form_submissions/{submissionUid} ``` **Path Parameters** | Parameter | Description | | :------------ | :-------------------------------------------- | | submissionUid | The unique identifier of the form submission. | **Example Request** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/form_submissions/sub12345-6789-0def-ghij-klmnopqrstuv ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Action completed successfully", "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy", "data": { "companyId": 123, "createDate": "2025-11-12T10:15:30.123Z", "formData": { "company_name": "Acme Corp", "industry": "technology", "number_of_locations": 3, "requires_redundancy": true }, "formDefinitionId": 42, "formStructure": { "type": "object", "properties": { "company_name": { "type": "string" }, "industry": { "type": "string", "enum": [ "technology", "finance", "healthcare", "other" ] }, "number_of_locations": { "type": "integer" }, "requires_redundancy": { "type": "boolean" } }, "required": [ "company_name", "industry" ] }, "lastUpdate": "2025-11-12T10:15:30.123Z", "uid": "sub12345-6789-0def-ghij-klmnopqrstuv", "vxcOrderId": 100 } } ``` ### Listing submissions by form To retrieve all submissions for a specific form, send a GET request with the form UID. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/form_submissions/form/{formUid} ``` **Path Parameters** | Parameter | Description | | :-------- | :--------------------------------- | | formUid | The unique identifier of the form. | **Example Request** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/form_submissions/form/abc12345-6789-0def-ghij-klmnopqrstuv ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Action completed successfully", "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy", "data": [ { "companyId": 123, "createDate": "2025-11-12T10:15:30.123Z", "formData": { "company_name": "Acme Corp", "industry": "technology", "number_of_locations": 3, "requires_redundancy": true }, "formDefinitionId": 42, "formStructure": { "type": "object", "properties": { "company_name": { "type": "string" }, "industry": { "type": "string", "enum": [ "technology", "finance", "healthcare", "other" ] }, "number_of_locations": { "type": "integer" }, "requires_redundancy": { "type": "boolean" } }, "required": [ "company_name", "industry" ] }, "lastUpdate": "2025-11-12T10:15:30.123Z", "uid": "abc12345-6789-0def-ghij-klmnopqrstuv", "vxcOrderId": 100 } ] } ``` ### Listing submissions by service To retrieve all submissions for a specific service, send a GET request with the service UID. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/form_submissions/service/{serviceUid} ``` **Path Parameters** | Parameter | Description | | :--------- | :------------------------------------ | | serviceUid | The unique identifier of the service. | **Example Request** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} GET {baseUrl}/v3/marketplace/form_submissions/service/svc12345-6789-0def-ghij-klmnopqrstuv ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Action completed successfully", "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy", "data": [ { "companyId": 123, "createDate": "2025-11-12T10:15:30.123Z", "formData": { "company_name": "Acme Corp", "industry": "technology", "number_of_locations": 3, "requires_redundancy": true }, "formDefinitionId": 42, "formStructure": { "type": "object", "properties": { "company_name": { "type": "string" }, "industry": { "type": "string", "enum": [ "technology", "finance", "healthcare", "other" ] }, "number_of_locations": { "type": "integer" }, "requires_redundancy": { "type": "boolean" } }, "required": [ "company_name", "industry" ] }, "lastUpdate": "2025-11-12T10:15:30.123Z", "uid": "svc12345-6789-0def-ghij-klmnopqrstuv", "vxcOrderId": 100 } ] } ``` ### Deleting a form submission To delete a form submission, send a DELETE request to the submissions endpoint. **Endpoint** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} DELETE {baseUrl}/v3/marketplace/form_submissions/{submissionUid} ``` **Path Parameters** | Parameter | Description | | :------------ | :------------------------------------------------------ | | submissionUid | The unique identifier of the form submission to delete. | **Example Request** ```http theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} DELETE {baseUrl}/v3/marketplace/form_submissions/e900d0d5-1030-4e29-b2d8-816ad4263190 ``` **Example Response** ```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}} { "message": "Action completed successfully", "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy" } ``` ## Helpful references * [Creating a Megaport Marketplace Profile](/marketplace/profile) * [Megaport Marketplace Forms](/marketplace/forms) * [Megaport Marketplace Notifications](/marketplace/notifications) * [Using Webhooks in the Megaport Portal](/portal-admin/using-webhooks)