MASV Portal for intake

In this tutorial, you’ll use a MASV Portal as a hosted upload page that can collect files from anyone — including people who do not have a MASV account.

What you’ll learn

In this tutorial, you will:

• Create and configure a portal through the MASV API.
• Connect storage.
• Register a webhook.
• Share the portal.
• Process incoming packages.
• Manage portals.

Variants of this pattern

There are two sub-approaches you can take, depending on how much UI ownership you want:

Hosted portal (linked): You point senders to yourname.portal.massive.io. MASV hosts the upload page entirely. You configure its appearance — logo, colors, background — via the API or MASV Web App. No front-end code is required on your side.

Embedded portal (iframe): MASV generates embed code that you include in your own web page. The portal renders inside your site but still runs entirely on MASV infrastructure.

Custom intake with API + Web Uploader: You build the upload UI yourself (Pattern 2) but configure it to submit packages to your portal. This gives you full UI control while still routing files through your portal’s configuration — webhooks, cloud connections, access controls, and custom forms.

Before you begin

• Generate an API key.
• Decide whether senders will use the portal’s MASV-hosted URL, an embedded portal, or a fully custom UI.
• Plan what happens after a file arrives: Does it go to cloud storage? Trigger a workflow? Notify a team member?

Step 1: Create and configure a MASV Portal

Create a portal using the API:

# Store your API key in an environment variable — never hardcode it.
# See /api/api-keys/ for key management best practices.
curl -X POST "https://api.massive.app/v1/teams/$TEAM_ID/portals" \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Client Deliverables",
    "subdomain": "client-deliverables",
    "active": true,
    "recipients": ["team@yourcompany.com"],
    "message": "Please upload your project files here.",
    "custom_expiry_days": 7
  }'

Configure the portal according to your intake requirements. Key properties to consider:

Property	Purpose
has_access_code / access_code	Restrict who can upload — require a password from senders.
recipients	Who receives email notifications when a package arrives.
cloud_connections	Automatically route uploaded packages to S3, GCS, Wasabi, etc.
custom_webhooks	Call your endpoint when packages are created or finalized.
file_type_restriction_enabled / file_types	Restrict accepted file extensions.
max_file_size / max_package_size	Set limits on what senders can upload.
package_name_format	Enforce a naming convention using a regex pattern.
terms_of_service_enabled	Require senders to accept terms before uploading.

Step 2: Connect storage

If you want uploaded files to automatically appear in your cloud storage, you have the option to connect storage (integration) to the portal. MASV supports popular storage providers, such as Amazon S3, Google Cloud Storage, Azure Blob Storage, Backblaze B2, Wasabi, and others. Configure the connection in the MASV Web App or by using the API and reference its ID when creating or updating your portal:

{
  "cloud_connections": [
    {
      "id": "YOUR_CLOUD_CONNECTION_ID",
      "target_action": "transfer"
    }
  ]
}

Every package that arrives through this portal is automatically delivered to the connected storage location — no manual intervention required.

Step 3: Register a webhook

You can use a webhook to notify your application of incoming uploads. When you register a webhook on the portal, MASV sends a POST request to your endpoint when a package is created and again when it is finalized.

To attach an existing webhook to the portal, include it in the custom_webhooks array when creating or updating the portal. See Configure Portal webhooks for steps on creating a webhook and obtaining its ID.

{
  "custom_webhooks": [
    {
      "id": "YOUR_WEBHOOK_ID"
    }
  ]
}

When a package is finalized, your server receives:

{
  "event_type": "package.finalized",
  "object": {
    "id": "PACKAGE_ID",
    "portal_id": "PORTAL_ID",
    "name": "Client Deliverables Upload",
    "sender": "client@studio.com",
    "size": 2147483648,
    "total_files": 47,
    "state": "finalized"
  }
}

Step 4: Share the portal with senders

Direct link: Share https://yoursubdomain.portal.massive.io with your senders. They can drag and drop files, add a name and description, and submit the package — no MASV account required.

Embedded portal: From the MASV Web App, copy the portal’s embed code and include it in your web page’s HTML. The portal renders inline on your site.

Custom UI (Pattern 2 approach): Build your own upload form using the Web Uploader SDK. Resolve your portal’s ID using its subdomain, create packages against the portal ID, and handle uploads as described in Embed the MASV uploader.

Step 5: Process incoming packages

After your webhook fires, you have everything you need to act on the incoming transfer:

package.finalized received
    │
    ├── Look up the package by ID using the MASV API.
    ├── List the files: GET /packages/{package_id}/files (with X-Package-Token)
    ├── Download individual files: GET /packages/{package_id}/files/{file_id}/download
    └── Trigger your downstream workflow.

If you attached a storage connection in Step 2, the files are already in your storage by the time the webhook fires. You can skip the download step and work directly with the files in cloud storage.

Step 6: Manage portals

You can create and manage portals dynamically — useful for platforms that provision a dedicated intake portal per project, client, or campaign:

# List all portals in your team
curl -H "X-API-KEY: $API_KEY" \
  https://api.massive.app/v1.1/teams/$TEAM_ID/portals

# Update a portal's settings
curl -X PUT "https://api.massive.app/v1/portals/$PORTAL_ID" \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

# Disable a portal when it is no longer needed
curl -X PUT "https://api.massive.app/v1/portals/$PORTAL_ID" \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

# Delete a portal
curl -X DELETE "https://api.massive.app/v1/portals/$PORTAL_ID" \
  -H "X-API-KEY: $API_KEY"

Production considerations

• Per-project or per-client portals: If your platform provisions a portal per project or client, automate portal creation, expiration, and teardown through the API so portals are never left active after they are no longer needed.
• Access codes: For sensitive intake workflows, you can configure an access_code and distribute it through your own access management system rather than embedding it in a public link. Alternatively, if the contributor is part of your MASV Team, you can require them to sign in to MASV to authenticate ("user_authentication_required": true).
• Webhook idempotency: MASV retries webhook delivery up to five times. Your handler should record processed event IDs to avoid triggering your downstream workflow multiple times for the same package.
• Expiry management: Portal packages expire according to the portal’s custom_expiry_days setting. If your downstream processing might take longer than the expiry window, either extend the expiry or download files to your own storage promptly after receiving the package.finalized event.
• Large volumes: The portal package listing endpoint (GET /v1.1/portals/{portal_id}/packages) supports filtering by sender, date range, and tag, making it suitable for periodic polling if you prefer it over webhooks.