Package management

The MASV API allows authorized users to manage packages that have been sent and received under their account.

Info

Packages tied to Portals are discussed in detail in Portals, but can be managed the same as a sent package.

Listing sent packages

Users can retrieve a list of packages in a Team that meets specific criteria, subject to the MASV access policy.

This endpoint returns a list of packages that were sent to a Team. To retrieve a list of packages received from a Portal, see Listing Portal packages.

To paginate through all packages, use the metadata.total property in the response. It contains the total number of packages that meet your request's criteria.

Info

This request uses version 1.1 of the API. To retrieve a list of packages with version 1.0 of the API, see Listing sent packages (legacy).

Method	Route
GET	/v1.1/teams/{{ team_id }}/packages

HEADERS

Name	Type	Required	Description
X-API-KEY	String	Yes	API key
Content-Type	String	Yes	Must be application/json

QUERY PARAMETERS

Name	Type	Required	Description
page	Integer	Yes	Page number of records to respond with. Default: 1.
limit	Integer	Yes	The number of records in a page, from 1 to 50. Default: 50.
sort	String	No	Sort results ascending (fieldname) or descending (-fieldname). These field names are accepted: name, created_at, size, usage_total_bytes, expiry, sender, status, teamspace_id.
status	Array of Strings	No	Retrieve records that match at least one of the specified states: new, finalized, expired, or archived. Default: [finalized, expired]
name	String	No	Retrieve records where name is a substring of the full package name
sender	String	No	Retrieve records that match the package sender’s email address
tags	String	No	Retrieve records where the package tag is equal to one of the tag IDs in this string of comma-separated IDs
created_at_start	String	No	Retrieve records where the package was created on or after a date. Accepted format: ISO 8601.
created_at_end	String	No	Retrieve records where the package was created on or before a date. Accepted format: ISO 8601.
teamspaces	String	No	Retrieve records where the package belongs to one of the Teamspace IDs in this string of comma-separated IDs

PATH PARAMETERS

Name	Type	Required	Description
team_id	String	Yes	The Team ID that the package is bound to.

REQUEST

curl

curl -H "Content-Type: application/json" \
    -H "X-API-KEY: $API_KEY" \
    -X GET https://api.massive.app/v1.1/teams/$TEAM_ID/packages?page=1\&limit=3

This endpoint returns an HTTP response with a status code of 200 OK and a body similar to the one below.

Example JSON Response

{
  "metadata": {
    "total": 34
  },
  "records": [
    {
      "access_limit": 3,
      "access_token": "...",
      "contains_virus": false,
      "created_at": "2022-11-01T20:09:48.249Z",
      "custom_expiry": false,
      "description": "Good day to you",
      "expiry": "2022-11-06T20:09:48.175Z",
      "id": "E1XGADMXPSLEE9NGH7WRWJ069D",
      "name": "Delta's Team - 202211012009",
      "password": "****",
      "recipients": [
        "[email protected]"
      ],
      "sender": "[email protected]",
      "size": 41610,
      "state": "expired",
      "total_files": 1,
      "unlimited_storage": false,
      "updated_at": "2022-11-06T20:39:19.455Z",
      "usage_updated_at": "2022-11-01T20:09:48.249Z"
    },
    {
        ...
    },
    {
        ...
    }
  ]
}

Response Properties:

Property	Description
metadata	Information about all of the Team's packages. The total property is the total number of packages in the Team that match the request's criteria.
records	An array of up to limit package objects

Changing the name

Authorized users can update the name for any package in a new or finalized state that they are authorized to view, subject to the access policy.

Method	Route
PUT	/v1/packages/{{ package_id }}

HEADERS

Name	Type	Required	Description
X-Package-Token	String	Yes	Package access token
Content-Type	String	Yes	Must be application/json

BODY

Name	Type	Required	Description
name	String	Yes	Name for the package

PATH PARAMETERS

Name	Type	Required	Description
package_id	String	Yes	Package ID for which to grab data from.

REQUEST

curl

curl -d "{\"name\": \"$NAME\"}" \
-H "X-Package-Token: $PACKAGE_TOKEN" \
-H "Content-Type: application/json" \
-X POST https://api.massive.app/v1/packages/$PACKAGE_ID

After a successful request where the package name has been updated, this endpoint will return an HTTP response with a status code of 200 OK and the updated package object.

Changing the expiry

MASV stores an uploaded package in MASV storage until its expiry time. When it expires, MASV deletes the package. For more information, see Deleting a package.

Expired packages cannot be downloaded and links do not give access to the package.

Authorized users can update the expiry date for any package, subject to the MASV access policy. The package must be in the finalized state.

To delete a package immediately, which also expires it immediately, see Deleting a package.

Attention

Extended Storage charges will be incurred beyond the free period included with the Team's pricing plan. For example, setting a package's expiry to 10 days in a Team with a plan that includes 7 days of free storage will incur charges for 10 - 7 = 3 days for the package. For details, see How does Extended Storage Work and Pricing.

Method	Route
PUT	/v1/packages/{{ package_id }}/expiry

HEADERS

Name	Type	Required	Description
X-Package-Token	String	Yes	Package access token
Content-Type	String	Yes	Must be application/json

BODY

Name	Type	Required	Description
expiry	String	Yes	Date-time expiry for the package Default: 0001-01-01T00:00:00.000Z Accepted Format: ISO 8601
unlimited_storage	Boolean	No	If the package should use MASV extended storage. If true, omit expiry from the request. Default: false.

PATH PARAMETERS

Name	Type	Required	Description
package_id	String	Yes	Package ID for which to grab data from.

REQUEST

curl

curl -d "{\"expiry\": \"$EXPIRY\"}" \
-H "X-Package-Token: $PACKAGE_TOKEN" \
-H "Content-Type: application/json" \
-X POST https://api.massive.app/v1/packages/$PACKAGE_ID/expiry

After a successful request where the package expiry has been updated, this endpoint will return an HTTP response with a status code of 200 OK and the updated package object.

Deleting a package

Authorized users can permanently delete a package's contents, subject to the MASV access policy.

When it deletes a package, MASV deletes the package's files and custom metadata from MASV storage. It keeps the package's name, recipient list, and related information, and sets the package's state to expired. For related information, see Changing the expiry.

Warning

Deleting a package cannot be undone.

Method	Route
DELETE	/v1/packages/{{ package_id }}

HEADERS

Name	Type	Required	Description
X-Package-Token	String	Yes	Package access token
Content-Type	String	Yes	Must be application/json

PATH PARAMETERS

Name	Type	Required	Description
package_id	String	Yes	ID of the package to delete

REQUEST

curl

curl -H "Content-Type: application/json" \
     -H "X-Package-Token: $PACKAGE_TOKEN" \
     -X DELETE https://api.massive.app/v1/packages/$PACKAGE_ID

After a successful request, this endpoint returns an HTTP response with a status code of 204 No Content and an empty body.

Archiving expired packages

Authorized users can archive or unarchive any package that was previously in an expired state (access policy). Archived packages can be separated from expired packages using the filters on the package list. The unarchive endpoint will put the package back to an expired state.

Method	Route
PUT	/v1/packages/{{ package_id }}/archive
PUT	/v1/packages/{{ package_id }}/unarchive

HEADERS

Name	Type	Required	Description
X-Package-Token	String	Yes	Package access token
Content-Type	String	Yes	Must be application/json

PATH PARAMETERS

Name	Type	Required	Description
package_id	String	Yes	Package ID for which to grab data from.

BODY

No body parameters.

REQUEST

curl to archivecurl to unarchive

curl -H "X-Package-Token: $PACKAGE_TOKEN" \
-H "Content-Type: application/json" \
-X POST https://api.massive.app/v1/packages/$PACKAGE_ID/archive

curl -H "X-Package-Token: $PACKAGE_TOKEN" \
-H "Content-Type: application/json" \
-X POST https://api.massive.app/v1/packages/$PACKAGE_ID/unarchive

After a successful request, the archive or unarchive endpoint will return an HTTP response with a status code of 204 No Content and an empty body.

Archiving sent packages

Authorized users can archive or unarchive multiple packages that were previously in an expired state and sent by the team (subject to access policy). Archived packages can be separated from expired packages using the filters on the package list. The unarchive endpoint will put the packages back to an expired state.

Method	Route
PUT	/v1/teams/{{ package_id }}/archive
PUT	/v1/teams/{{ package_id }}/unarchive

HEADERS

Name	Type	Required	Description
X-API-KEY	String	Yes	API key
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. Default: 0001-01-01T00:00:00.000Z Accepted Format: ISO 8601
expiry_end	String	Yes	Latest package expiry date-time to archive/unarchive to. Default: 0001-01-01T00:00:00.000Z Accepted Format: ISO 8601

PATH PARAMETERS

Name	Type	Required	Description
team_id	String	Yes	The Team ID that the package is bound to.

REQUEST

curl to archivecurl to unarchive

curl -d '{"expiry_start": "$EXPIRY_START", "expiry_end": "$EXPIRY_END"}' \
-H "X-API-KEY: $API_KEY" \
-H "Content-Type: application/json" \
-X POST https://api.massive.app/v1/teams/$PACKAGE_ID/archive

curl -d '{"expiry_start": "$EXPIRY_START", "expiry_end": "$EXPIRY_END"}' \
-H "X-API-KEY: $API_KEY" \
-H "Content-Type: application/json" \
-X POST https://api.massive.app/v1/teams/$PACKAGE_ID/unarchive

After a successful request, the archive or unarchive 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.

Archiving received packages

Authorized users can archive or unarchive multiple packages that were previously in an expired state and received through a Portal (subject to access policy). Archived packages can be separated from expired packages using the filters on the package list. The unarchive endpoint will put the packages back to an expired state.

Method	Route
PUT	/v1/teams/{{ package_id }}/inbox/archive
PUT	/v1/teams/{{ package_id }}/inbox/unarchive

HEADERS

Name	Type	Required	Description
X-API-KEY	String	Yes	API key
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

PATH PARAMETERS

Name	Type	Required	Description
team_id	String	In /teams route	The Team ID that the package is bound to.

REQUEST

curl to archivecurl to unarchive

curl -d "{\"expiry_start\": \"$EXPIRY_START\", \"expiry_end\": \"$EXPIRY_END\"}" \
-H "X-API-KEY: $API_KEY" \
-H "Content-Type: application/json" \
-X POST https://api.massive.app/v1/teams/$TEAM_ID/inbox/archive

curl -d "{\"expiry_start\": \"$EXPIRY_START\", \"expiry_end\": \"$EXPIRY_END\"}" \
-H "X-API-KEY: $API_KEY" \
-H "Content-Type: application/json" \
-X POST https://api.massive.app/v1/teams/$TEAM_ID/inbox/unarchive

After a successful request, the archive or unarchive 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	Type	Description
total_updated	Integer	Number of records that were affected.

Package object

Represents a package in a Team.

Property	Type	Description
access_limit	Integer	Default access limit for new links to restrict download access to the package. A 0 value indicates that no default has been set.
access_token	String	Access token for managing and retrieving the package. It allows read/write access for requests the retrieve and modify the package.
contains_virus	Boolean	If this package contains a virus
created_at	String	Date-time that the package was created in ISO 8601 format
custom_expiry	Boolean	If a custom expiry date was set
custom_metadata_id	String	The ID of the form response that contains the data associated with this package, if any. See Submitting a form response.
description	String	Package description
expiry	String	The date and time at which the package will expire, in ISO 8601 format
id	String	The package's unique ID
name	String	Package name
password	String	A non-empty value indicates that there is a default password for the package for all new links to use. An empty or missing password means that no default password is set.
recipients	Array of Strings	Email addresses of recipients of the package
sender	String	Sender’s email address
size	Integer	Package size in bytes
state	String	Current status of the package: new, finalized, expired, or archived
teamspace	Teamspace object	The Teamspace that the package belonds to
total_files	Integer	Number of files in package
unlimited_storage	Boolean	If unlimited storage is enabled or disabled
updated_at	String	When the package metadata was last modified, in ISO 8601 format
usage_updated_at	String	When the package was last downloaded, in ISO 8601 format

Teamspace object

Represents the Teamspace that a package belongs to.

Name	Type	Required	Description
id	String	No	ID of the Teamspace
name	String	No	Name of the Teamspace