action.skip
Megaport Documentation
Managing Megaport Marketplace Forms
Copy for LLM ▼
Copy Page Content Open in ChatGPT Open in Claude Open in VS Code View Markdown
PDF

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.

Note

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

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"]
    }
}

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

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

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.

Note

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"
            },
        }
    }
}

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

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

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

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

Note

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

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

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

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

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

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

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

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

Response

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

Helpful references