Portals

Portal Creation

The MASV API allows authorized users to create portals under any team that they belong to (access policy).

Portals can be created as regular or private. Packages received via a regular portal can be viewed by all team members, while packages uploaded to private portals are accessible only for the team members included in the portal's access list. Private portals require that an access_code be specified. By default, all portals are regular.

Note

The private portals feature is only available for a limited number of customers. To request access for your team, please contact team@masv.io.

Method	Route
`POST`	`/teams/{team_id}/portals`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token
`Content-Type`	String	Yes	Must be `application/json`

URL Parameters

Name	Type	Required	Description
`team_id`	String	Yes	The team id to bind the portal to.

BODY

Name	Type	Required	Description
`name`	String	Yes	Name of the portal to create
`subdomain`	String	Yes	Subdomain of the portal to create
`message`	String	Yes	Message displayed on the portal upload page
`recipients`	Array of Strings	Yes	Email(s) that will receive notifications for portal uploads
`access_code`	String	No	Access code to be able to access portal upload page
`has_access_code`	Boolean	No	Enable/disable access code for portal page
`download_password`	String	No	Password to protect download access on any package uploaded to this portal
`has_download_password`	Boolean	No	Enable/disable download password for portal packages
`active`	Boolean	Yes	Enable/disable portal page
`logo_url`	String	No	URL for logo to be displayed on portal page
`background_url`	String	No	URL for background image of the portal page
`primary_color`	String	No	HTML hex code for primary color used on portal page
`tag`	TagObject	No	An optional tag object used to assign a tag to the new portal. When a portal has a tag, all packages created on the portal are assigned the portal's tag. See the Tag Objects for tag fields.
`language`	String	No	An optional field used to store the language code for the portal.
`custom_expiry_days`	Integer	No	Length of storage days for packages that belong to the portal
`access_level`	String	No	Portal access level, can be `regular` or `private`. It is `regular` by default (if omitted)
`access_list`	Array of Strings	No	List of user membership IDs with access to the portal and its received packages. It is empty for `regular` portals.

Warning

If you set custom_expiry_days to -1, Unlimited Storage will be activated and Unlimited Storage charges will be incurred daily beyond the free period included with the team subscription for users who have activated their account. Trial accounts cannot extend the expiry beyond the original date given on creation - it can only be set earlier. How does Extended Storage Work?

REQUEST

curl

curl  -d "{\"name\": \"$NAME\", \"message\": \"$MESSAGE\", \"subdomain\": \"$SUBDOMAIN\", \"recipients\": [\"$R1_EMAIL\"], \"access_code\": \"$ACCESSCODE\", \"has_access_code\": true, \"download_password\": \"$DOWNLOADPASSWORD\", \"has_download_password\":true,\"custom_expiry_days\":$CUSTOMEXPIRYDAYS}" \
-H "X-User-Token: $USER_TOKEN" 
-H "Content-Type: application/json" 
-X POST https://api.massive.app/v1/teams/$TEAM_ID/portals

After a successful request where a portal has been created, this endpoint will return an HTTP response with a status code of 201 Created and a body similar to the one below.

Example JSON Response

{
  "active": true,
  "has_access_code": true,
  "has_download_password": true,
  "id": "01CTDNW11G67NKHQW5JE8TP2TJ",
  "message": "Hello world!",
  "name": "My portal",
  "tag": {
    "id": "01CTDNW91C67JSHQW5JE8TGGEZ",
    "name": "test tag name"
  },
  "recipients": [
    "[email protected]",
    "[email protected]"
  ],
  "subdomain": "customesub",
  "language": "en",
  "custom_expiry_days": 0,
  "access_level": "regular"
}

Response Properties:

Property	Description
`active`	The `enable/disable` state of the portal.
`has_access_code`	Is an access code required.
`has_download_password`	Is a password required for download.
`id`	Portal id for the portal created.
`message`	Message displayed on the portal upload page.
`name`	Name of the portal to create.
`recipients`	Email(s) that will receive notifications for portal uploads.
`subdomain`	Subdomain of the portal created.
`tag`	A Tag Object representing this portal's tag. If the portal does not have a tag, `tag` is excluded from the response.
`language`	The language code for this portal. If no value was set on the portal `language` it will be empty or omitted from the response.
`access_level`	Portal access level, can be `regular` or `private`.
`access_list`	List of user memberships with access to the portal and its received packages. It is empty for `regular` portals.

Access list object:

Name	Type	Required	Description
`membership_id`	String	No	User's membership ID
`name`	String	No	User's name
`email`	String	No	User's email

Portal Update

The MASV API allows authorized users to update portals under any team that they belong to (access policy).

The user performing the update must have the manage_portals permission OR their team membership ID must be included in the access list (for private portals only). Users who do not have manage_portals permission but have their membership ID included in the access list cannot: - remove their own membership ID from the portal's access list - change the portal access level from private to regular

Method	Route
`PUT`	`/portals/{portal_id}`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token
`Content-Type`	String	Yes	Must be `application/json`

URL Parameters

Name	Type	Required	Description
`portal_id`	String	Yes	The ID of the portal you are updating.

BODY

Name	Type	Required	Description
`name`	String	Yes	Name of the portal to create
`subdomain`	String	Yes	Subdomain of the portal to create
`message`	String	Yes	Message displayed on the portal upload page
`recipients`	Array of Strings	Yes	Email(s) that will receive notifications for portal uploads
`access_code`	String	No	Access code to be able to access portal upload page
`has_access_code`	Boolean	No	Enable/disable access code for portal page
`download_password`	String	No	Password to protect download access on any package uploaded to this portal
`has_download_password`	Boolean	No	Enable/disable download password for portal packages
`active`	Boolean	Yes	Enable/disable portal page
`logo_url`	String	No	URL for logo to be displayed on portal page
`background_url`	String	No	URL for background image of the portal page
`primary_color`	String	No	HTML hex code for primary color used on portal page
`tag`	TagObject	No	An optional tag object used to assign a tag to the new portal. When a portal has a tag, all packages created on the portal are assigned the portal's tag. See the Tag Objects for tag fields.
`language`	String	No	An optional field used to store the language code for the portal.
`custom_expiry_days`	Integer	No	Length of storage days for packages that belong to the portal
`access_level`	String	No	Portal access level, can be `regular` or `private`. It is `regular` by default (if omitted)
`access_list`	Array of Strings	No	List of user membership IDs with access to the portal and its received packages. It is empty for `regular` portals.

Warning

If you set custom_expiry_days to -1, Unlimited Storage will be activated and Unlimited Storage charges will be incurred daily beyond the free period included with the team subscription for users who have activated their account. Trial accounts cannot extend the expiry beyond the original date given on creation - it can only be set earlier. How does Extended Storage Work?

REQUEST

Note

The below request/response examples do not list all fields. When updating a portal, it is important that you provide the full portal object. A typical workflow would be: Get Portal > Modify Fields > Update Portal.

curl

curl  -d "{\"name\": \"$NAME\", \"message\": \"$MESSAGE\", \"subdomain\": \"$SUBDOMAIN\", \"recipients\": [\"$R1_EMAIL\"], \"access_code\": \"$ACCESSCODE\", \"has_access_code\": true, \"download_password\": \"$DOWNLOADPASSWORD\", \"has_download_password\":true,\"custom_expiry_days\":$CUSTOMEXPIRYDAYS}" \
-H "X-User-Token: $USER_TOKEN" 
-H "Content-Type: application/json" 
-X PUT https://api.massive.app/v1/portals/$PORTAL_ID

After a successful request where a portal has been updated, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below.

Example JSON Response

{
  "active": true,
  "has_access_code": true,
  "has_download_password": true,
  "id": "01CTDNW11G67NKHQW5JE8TP2TJ",
  "message": "Hello world!",
  "name": "My portal",
  "tag": {
    "id": "01CTDNW91C67JSHQW5JE8TGGEZ",
    "name": "test tag name"
  },
  "recipients": [
    "[email protected]",
    "[email protected]"
  ],
  "subdomain": "customesub",
  "language": "en",
  "custom_expiry_days": 0,
  "access_level": "regular"
}

Response Properties:

Property	Description
`active`	The `enable/disable` state of the portal.
`has_access_code`	Is an access code required.
`has_download_password`	Is a password required for download.
`id`	Portal id for the portal created.
`message`	Message displayed on the portal upload page.
`name`	Name of the portal to create.
`recipients`	Email(s) that will receive notifications for portal uploads.
`subdomain`	Subdomain of the portal created.
`tag`	A Tag Object representing this portal's tag. If the portal does not have a tag, `tag` is excluded from the response.
`language`	The language code for this portal. If no value was set on the portal `language` it will be empty or omitted from the response.
`access_level`	Portal access level, can be `regular` or `private`.
`access_list`	List of user memberships with access to the portal and its received packages. It is empty for `regular` portals.

Access list object:

Name	Type	Required	Description
`membership_id`	String	No	User's membership ID
`name`	String	No	User's name
`email`	String	No	User's email

Listing Portals

Authorized users can list all portals under any team they belong to (subject to access policy).

Method	Route
`GET`	`/teams/{team_id}/portals`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token

URL Parameters

Name	Type	Required	Description
`team_id`	String	Yes	The team id to bind the portal to.

REQUEST

curl

curl -H `X-User-Token: $USER_TOKEN` \
-X GET https://api.massive.app/v1/teams/$TEAM_ID/portals

After a successful request, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below.

Example JSON Response

[
    {
        "id": "01CNH24NGPTJTMXWWM2J8E2V8V",
        "message": "Hello world!",
        "name": "My portal",
        "subdomain": "myportal",
        "has_access_code": true,
        "has_download_password": true,
        "tag": {
          "id": "01CNH24NGPTJTMXGGEZJ8E2J2K",
          "name": "test tag name"
        },
        "custom_expiry_days": 0,
        "recipients": [
            "[email protected]",
            "[email protected]"
        ],
        "language": "en",
        "access_level": "regular"
    },
    {
        "id": "01CNEM9H2AG0MVH33X0EVDY8AQ",
        "message": "Hello world, again!",
        "name": "My other portal",
        "subdomain": "myotherportal",
        "has_access_code": false,
        "has_download_password": false,
        "custom_expiry_days": 0,
        "recipients": [
            "[email protected]"
        ],
        "language": "fr",
        "access_level": "private",
        "access_list": [
          {
            "membership_id": "01CNEM9H2AG0MVH33X0EVDYYPT",
            "name": "user1",
            "email": "[email protected]"
          },
          {
            "membership_id": "01CD5R9H08GOT6HTYU0EVDQW3E",
            "name": "user2",
            "email": "[email protected]"
          },
          ...            
        ]
    },
    ...
]

Response Properties:

Property	Description
`[]`	Top level array of `portal` objects.

Listing Portal Packages

Authorized users can list packages uploaded to any portal under their team(s) subject to access policy).

Method	Route
`GET`	`/portals/{portal_id}/packages?expired=1&finalized=1&new=1`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token

QUERY PARAMETERS

Name	Type	Required	Description
`expired`	Boolean	No	If expired packages should be included in response
`finalized`	Boolean	No	If finalized packages should be included in response
`new`	Boolean	No	If new packages should be included in response
`archived`	Boolean	No	If archived packages should be included in response

Note

The expired, finalized, new and archived parameters are optional and allow for filtering the package list to include packages in these states. If none of them are passed or all are set to 0 then only packages in the finalized and expired states will be returned.

URL Parameters

Name	Type	Required	Description
`portal_id`	String	Yes	The portal id that we are getting packages from.

REQUEST

curl

curl -H "X-User-Token: $USER_TOKEN" \
-X GET https://api.massive.app/v1/portals/$PORTAL_ID/packages?expired=1&finalized=1&new=0

After a successful request, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below:

Example JSON Response

[
  {
    "id": "01CNH4M62513B3FT70FXNFS6YS",
    "created_at": "2018-08-22T11:39:07.717-04:00",
    "updated_at": "2018-08-22T11:39:10.271-04:00"
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MzU1NTgxMDksImx2bCI6ImYiLCJzdWIiOiIwMUNOSDRNNjI1MTNCM0ZUNzBGWE5GUzZZUyIsInR5cCI6InBhY2thZ2UifQ.T1tTJkqcaaptWtHg59Ta94LcYl8DomtnY8ieYVdqP_I",
    "state": "finalized",
    "name": "Test package #1",
    "description": "Lorem ipsum dolor sit amet, consectetur adipiscing elit",
    "progress_channels": [],
    "unlimited_storage": false,
    "sender": "[email protected]"
  },
  {
    "id": "01CNH4WNNKZC5FWVG1V100JTXH",
    "created_at": "2018-08-22T11:43:45.843-04:00",
    "updated_at": "2018-08-22T11:43:47.111-04:00"
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MzU1NTgxMDksImx2bCI6ImYiLCJzdWIiOiIwMUNOSDRXTk5LWkM1RldWRzFWMTAwSlRYSCIsInR5cCI6InBhY2thZ2UifQ.Y2gI_a_utNNlU_nujZch0zLIDdZ5EDMtQpohIFifvXA",
    "state": "new",
    "name": "Another package",
    "description": "At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium",
    "progress_channels": [
        {
            "auth": {
                "auth_key": "xxxxxxxxxxxxxxxxx",
                "channel_name": "proc.upload.01CNH4WNNKZC5FWVG1V100JTXH",
                "publish_key": "pub-c-xxxxx-xxxxxxxxxxxxx",
                "subscribe_key": "sub-c-xxxxx-xxxxxxxxxxxxx"
            },
            "topic":"upload",
            "provider": "pubnub"
        }
    ],
    "sender": "[email protected]",
    "unlimited_storage": false
  },
  {
    "id": "01CXBDDNMJR5QQJ3298WQBGT1G",
    "created_at": "2018-08-22T11:43:45.843-04:00",
    "updated_at": "2018-08-22T11:43:47.111-04:00"
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE1MzU1NTgxMDksImx2bCI6ImYiLCJzdWIiOiIwMUNOSDRXTk5LWkM1RldWRzFWMTAwSlRYSCIsInR5cCI6InBhY2thZ2UifQ.Y2gI_a_utNNlU_nujZch0zLIDdZ5EDMtQpohIFifvXA",
    "state": "expired",
    "name": "Another package",
    "description": "At vero eos et accusamus et iusto odio dignissimos ducimus qui blanditiis praesentium",
    "progress_channels": [],
    "sender": "[email protected]",
    "unlimited_storage": false
  }
]

Note

If the referenced portal has a tag, each package created since the portal was given a tag will have the portal's tag.

Response Properties:

Property	Description
`id`	The package id requested.
`created_at`	Time that the object was created at
`updated_at`	Last time the package was updated.
`access_token`	Auth token required to interact with the package.
`state`	Indicates the state of the package Possible Values: `new`, `finalized`, `expired`, `archived`
`progress_channels`	PubNub progress events.
`progress_channels.zip`	Reports the progress of zip file creation for `finalized` packages.
`progress_channels.upload`	Reports the progress of initial package upload for `new` packages only.
`links`	List of download links created for this package.

Note

MASV integrates with PubNub for publishing and subscribing to progress messages. They provide client SDKs in several programming languages. More details can be found on their developer documentation website.

Listing Portal Package Files

Authorized users can list package files uploaded to any portal under their team(s) subject to access policy). The listing will include all files that are a part of the uploaded package.

Method	Route
`GET`	`/packages/{package_id}/files`

HEADERS

Name	Type	Required	Description
`X-Package-Token`	String	Yes	Package JSON Web Token

REQUEST

curl

curl -H "X-Package-Token: $PACKAGE_TOKEN" \
-X GET https://api.massive.app/v1/packages/$PACKAGE_ID/files

After a successful request, this endpoint will return an HTTP response with a status code of 200 OK and a body similar to the one below:

Example JSON Response

[
  {
    "id": "01CNH4M62EFJFX5F7XTC9GZWDF",
    "kind": "file",
    "name": "photo.jpg",
    "path": "/some/directory",
    "size": 193022
    "last_modified": "2018-08-22T11:39:10.280-04:00",
  },
  {
    "id": "01CNH4M86PKYWPKSK8EWEFEQPS",
    "kind": "file",
    "name": "my-image.png",
    "path": "/anotherpath",
    "size": 72012
    "last_modified": "2018-08-22T11:39:10.280-04:00",
  },
  {
    "id": "01CNH4M8J88WSVS7P3NMB1HG42",
    "kind": "zip_windows",
    "name": "windows.zip"
    "last_modified": "2018-08-22T11:39:10.280-04:00",
  },
  {
    "id": "01CNH4M8JMXHTWCTTS8R2PJFVE",
    "kind": "zip_mac",
    "name": "mac.zip"
    "last_modified": "2018-08-22T11:39:10.292-04:00",
  },
  ...
]

Property	Description
`id`	The file id requested.
`kind`	Indicates the kind of file Possible Values: `file`, `directory`, `zip_windows`, `zip_mac`
`name`	File or directory name.
`path`	The relative path in file system.
`size`	The file size in bytes. (If applicable)
`last_modified`	File's last modification date.

Archiving/Unarchiving Portal Packages

Authorized users can archive or unarchive multiple packages that were previously in an expired state and received through a specific portal (subject to access policy).

Archived packages can be separated from Expired packages using the filters on the package list. The Unarchive action will put the packages back to an expired state.

Archive/Unarchive

Method	Route
`PUT`	`/portals/{{ portal_id }}/packages/{{ package_id }}/archive`
`PUT`	`/portals/{{ portal_id }}//packages/{{ package_id }}/unarchive`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token
`Content-Type`	String	Yes	Must be `application/json`

BODY

Name	Type	Required	Description
`expiry_start`	String	Yes	Earliest package expiry date-time to archive/unarchive from
`expiry_end`	String	Yes	Latest package expiry date-time to archive/unarchive to

REQUEST PARAMETERS

Name	Type	Required	Description
`package_id`	String	Yes	Package ID for which to grab data from.
`portal_id`	String	Yes	The portal id that we are getting packages from.

REQUEST

curl

curl  -d "{\"expiry_start\": \"$EXPIRY_START\", \"expiry_end\": \"$EXPIRY_END\"}" \
-H "X-User-Token: $USER_TOKEN" \
-H "Content-Type: application/json" \
-X POST https://api.massive.app/v1/portals/$PORTAL_ID/packages/archive

After a successful request where the package(s) have been moved to or from the archived state, this endpoint will return an HTTP response with a status code of 200 OK and include a body similar to the one below.

Example JSON Response

{
    "total_updated": 51
}

Response Properties:

Property	Description
`total_updated`	Number of records that were effected.

Portal Deletion

The MASV API allows authorized users to delete portals that they have created.

Method	Route
`DELETE`	`/portals/{portal_id}`

HEADERS

Name	Type	Required	Description
`X-User-Token`	String	Yes	User JSON Web Token

URL Parameters

Name	Type	Required	Description
`portal_id`	String	Yes	The id of the portal to delete

REQUEST

curl

curl -X DELETE \
-H "X-User-Token: $USER_TOKEN" \
https://api.massive.app/v1/portals/$PORTAL_ID

After a successful request where a portal has been deleted, this endpoint will return an HTTP response with a status code of 204 No Content.