Managing Megaport Marketplace Forms with the API

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. Before you begin, obtain a valid access token. For more information, see Creating an 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.
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:

{
"type": "object",
"properties": {
  "email": { 
    "type": "string", 
    "format": "email" 
  }
 }
}

and an example for adding a drop-down field:

{
"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

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

{
    "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.

{
    "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

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

GET {baseUrl}/v3/marketplace/forms?status=ACTIVE

Example Response

{
    "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

GET {baseUrl}/v3/marketplace/forms/{formUid}

Path Parameters

Parameter	Description
formUid	The unique identifier of the form.

Example Request

GET {baseUrl}/v3/marketplace/forms/abc12345-6789-0def-ghij-klmnopqrstuv

Example Response

{
    "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 and Deleting a form.

Endpoint

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

{
    "name": "Updated Customer Onboarding Form",
    "formStructure": {
        "type": "object",
        "properties": {
            "companyName": {
                "type": "string",
                "title": "Updated Company Name"
            },
        }
    }
}

Example Response

{
    "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

POST {baseUrl}/v3/marketplace/forms/{formUid}/activate

Path Parameters

Parameter	Description
formUid	The unique identifier of the form to activate.

Example Request

POST {baseUrl}/v3/marketplace/forms/abc12345-6789-0def-ghij-klmnopqrstuv/activate

Example Response

{
    "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

DELETE {baseUrl}/v3/marketplace/forms/{formUid}

Path Parameters

Parameter	Description
formUid	The unique identifier of the form to delete.

Example Request

DELETE {baseUrl}/v3/marketplace/forms/abc12345-6789-0def-ghij-klmnopqrstuv

Example Response

{
    "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

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

{
    "serviceUid": "svc12345-6789-0def-ghij-klmnopqrstuv",
    "formUid": "abc12345-6789-0def-ghij-klmnopqrstuv"
}

Example Response

{
    "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

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

GET {baseUrl}/v3/marketplace/service_forms?serviceUid=svc12345-6789-0def-ghij-klmnopqrstuv

Example Response

{
    "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

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

{
    "formUid": "newform12-3456-789a-bcde-fghijklmnopq"
}

Example Response

{
    "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

DELETE {baseUrl}/v3/marketplace/service_forms/{serviceFormUid}

Path Parameters

Parameter	Description
serviceFormUid	The unique identifier of the service-form association to remove.

Example Request

DELETE {baseUrl}/v3/marketplace/service_forms/assoc123-4567-89ab-cdef-ghijklmnopqr

Example Response

{
    "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

GET {baseUrl}/v3/marketplace/form_submissions

Example Request

GET {baseUrl}/v3/marketplace/form_submissions

Example Response

{
  "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

GET {baseUrl}/v3/marketplace/form_submissions/{submissionUid}

Path Parameters

Parameter	Description
submissionUid	The unique identifier of the form submission.

Example Request

GET {baseUrl}/v3/marketplace/form_submissions/sub12345-6789-0def-ghij-klmnopqrstuv

Example Response

{
  "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

GET {baseUrl}/v3/marketplace/form_submissions/form/{formUid}

Path Parameters

Parameter	Description
formUid	The unique identifier of the form.

Example Request

GET {baseUrl}/v3/marketplace/form_submissions/form/abc12345-6789-0def-ghij-klmnopqrstuv

Example Response

{
  "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

GET {baseUrl}/v3/marketplace/form_submissions/service/{serviceUid}

Path Parameters

Parameter	Description
serviceUid	The unique identifier of the service.

Example Request

GET {baseUrl}/v3/marketplace/form_submissions/service/svc12345-6789-0def-ghij-klmnopqrstuv

Example Response

{
  "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

DELETE {baseUrl}/v3/marketplace/form_submissions/{submissionUid}

Path Parameters

Parameter	Description
submissionUid	The unique identifier of the form submission to delete.

Example Request

DELETE {baseUrl}/v3/marketplace/form_submissions/e900d0d5-1030-4e29-b2d8-816ad4263190

Example Response

{
  "message": "Action completed successfully",
  "terms": "This data is subject to the Acceptable Use Policy https://www.megaport.com/legal/acceptable-use-policy"
}

Megaport Documentation

Managing Megaport Marketplace Forms with the API

Use cases

Prerequisites

Managing form definitions

Supported field types

Creating a form

Listing forms

Retrieving a form

Updating a form

Activating a form

Deleting a form

Linking forms to services

Attaching a form to a service

Listing service-form associations

Updating a service-form association

Detaching a form from a service

Managing form submissions

Listing all form submissions

Retrieving a form submission

Listing submissions by form

Listing submissions by service

Deleting a form submission

Helpful references

​Use cases

​Prerequisites

​Managing form definitions

​Supported field types

​Creating a form

​Listing forms

​Retrieving a form

​Updating a form

​Activating a form

​Deleting a form

​Linking forms to services

​Attaching a form to a service

​Listing service-form associations

​Updating a service-form association

​Detaching a form from a service

​Managing form submissions

​Listing all form submissions

​Retrieving a form submission

​Listing submissions by form

​Listing submissions by service

​Deleting a form submission

​Helpful references

Use cases

Prerequisites

Managing form definitions

Supported field types

Creating a form

Listing forms

Retrieving a form

Updating a form

Activating a form

Deleting a form

Linking forms to services

Attaching a form to a service

Listing service-form associations

Updating a service-form association

Detaching a form from a service

Managing form submissions

Listing all form submissions

Retrieving a form submission

Listing submissions by form

Listing submissions by service

Deleting a form submission

Helpful references