This endpoint allows users to perform the following:
Get a package
Create a package
Delete a Package
Bulk delete a package
Update and edit package attributes, recipients, and metadata
Search for a package
Forward a package
Replicate package contents

Note: Any endpoint that begins with "/api/users/" (unless it's in the format "/api/users/me/") is accessible to admins only. The identifier me—indicating that the user is accessing data within their own domain of privileges, only—can be substituted for {user_id} or {dropbox_id} in the request.

Get a package

GET /api/users/{user_id}/packages/{package_delivery_id}
GET /api/dropboxes/{dropbox_id}/packages/{package_delivery_id}

Returns information for a package with a specific package delivery ID

Query Parameters: None

Request Body: None

Response Codes

  • Success: 200 OK - Returns a package object
  • Error: 404 Not Found - Indicates that incorrect package ID was submitted/li>

Example Request and Response

GET users/me/packages
[
    {
        "id": "23565",
        "title": "asd",
        "recipients": [
            {
                "archived": false,
                "created_at": "2017/10/06 16:31:53 -0500",
                "delivery_id": 23565,
                "e_package_id": 22670,
                "id": 30938,
                "old_wg_delivery_id": null,
                "package_deleted": false,
                "private": false,
                "recipient_id": 2,
                "recipient_name": "admin",
                "recipient_type": "User",
                "send_to_email_passcode": null,
                "share_id": 2,
                "updated_at": "2017/10/06 16:31:53 -0500"
            }
        ],
        "release_policy": "release_now",
        "release_date": "2017-10-06T16:31:53.000-0500",
        "expiration_date": "2017-10-20T16:31:53.000-0500",
        "sender": "jeff",
        "state": "deleted",
        "archived": false,
        "ear_enabled": null,
        "notifiable_on_upload": [],
        "notifiable_on_download": [],
        "active_downloads": 0,
        "active_downloaders": [],
        "download_count": 0,
        "downloaders": [],
        "total_bytes": 0,
        "total_files": 0,
        "creation_date": "2017-10-06T16:31:53.000-0500",
        "last_modified": "2017-10-06T16:35:13.000-0500",
        "mailbox": "outbox"
    },
    {
        "id": "23544",
        "title": "asd",
        "recipients": [
            {
                "archived": false,
                "created_at": "2017/10/03 17:24:36 -0500",
                "delivery_id": 23544,
                "e_package_id": 22649,
                "id": 30917,
                "old_wg_delivery_id": null,
                "package_deleted": false,
                "private": false,
                "recipient_id": 2,
                "recipient_name": "admin",
                "recipient_type": "User",
                "send_to_email_passcode": null,
                "share_id": 2,
                "updated_at": "2017/10/03 17:24:36 -0500"
            }
        ],
        "release_policy": "release_now",
        "release_date": "2017-10-03T17:24:36.000-0500",
        "expiration_date": "2017-10-17T17:24:36.000-0500",
        "sender": "jeff",
        "state": "held",
        "archived": false,
        "ear_enabled": null,
        "notifiable_on_upload": [],
        "notifiable_on_download": [],
        "active_downloads": 0,
        "active_downloaders": [],
        "download_count": 0,
        "downloaders": [],
        "total_bytes": 0,
        "total_files": 0,
        "creation_date": "2017-10-03T17:24:36.000-0500",
        "last_modified": "2017-10-04T07:48:29.000-0500",
        "mailbox": "outbox"
    },
    {
        .  .  .
    },
    {
        .  .  .
    }
 ]

Create a package

POST /api/users|dropboxes/{user_id}|{dropbox_id}/packages

Creates a new package for a user with user_id or a dropbox with dropbox_id as sender or creator and creates an empty storage directory on the package creator’s storage share.

Note: After creating the package and directory, you can upload content with a separate request to the "Send Packages" endpoint with a POST request.

Request Parameters

Parameter Name Required/Optional Format Default Value Description
title required string none Package title
senders required string none User sending the package
recipients required string none Comma-separated list of usernames of package recipients
private_recipients optional string none Comma-separated customized list of usernames of package recipients
release_policy required string none Available values:
  • release_now - Faspex waits for one successful upload session to complete before routing the package to the recipients and sending notifications.
  • do_not_release - Package is never released. Package information is stored in Faspex’s MySQL database and the user can make subsequent uploads to add or remove files from the package.
  • release_on_date - Release package at a later time. Requires a value for release_date. If release_date is now or in the past, the release_on_date value is equivalent to release_now. If release_date is in the future, Faspex waits to send notifications until the first successful upload session completes or the release_date occurs, whichever is later.
note optional string none Developer's comment
metadata optional Array of JSON objects in the form, { “name” : “field1”, “value” : value1 }. Must have a value if "require"=false in the metadata profile. none For package forwarding; adds new metadata according to the specification in the metadata profile. To view metadata profile information, query the Metadata Profiles endpoint.

Note: Submitting metadata in a request overwrites any previous data. However, the old metadata is copied to the note field.

release_date optional ISO date format null Date to route a package to recipients and send notifications. Used with a release_policy value of release_on_date.
expiration_date optional ISO date format null Expiration date for a package; package contents are deleted.
download_limit optional unsigned integer null Number of times a package can be downloaded. Value can be null, indicating "no limit".
ear-enabled optional boolean none Encryption-at-rest is set for the package (true/false)
skip_recipient_validation optional boolean false If true, a list of usernames containing invalid values will not fail with an error. This parameter does not return a list of invalid usernames.
notify_on_upload optional boolean true Whether to send a notifcation ("Package Received" email) upon successful file upload. If true, need a value for notifiable_on_upload.
notifiable_on_upload optional array of strings none List of usernames to notify when upload occurs. Must have a value if notify_on_upload is selected.
notify_on_download optional boolean true Whether to send a notifcation ("Package Received" email) upon successful file download. If true, need a value for notifiable_on_download.
notifiable_on_download optional array of strings none List of usernames to notify when a download occurs. Must have a value if notify_on_download is selected.

Response Codes

  • HTTP 201 Created - Returned with a package object in the response body
  • HTTP 400 Bad Request - Indicates a failure of package database operations. Possible issues: the request may be missing a header or a required parameter, or a parameter may be faulty (for example, a title with too many characters).
  • HTTP 500 Internal Server Error - Indicates that the creation of the empty directory failed; the package is marked as deleted

Example Request and Response

curl -H "Accept: application/json" -H "Content-type: application/json" -H "Authorization: Bearer token_value" https://faspex.asperademo.com/aspera/faspex/api/users/me/packages 
--data '{"recipients": ["admin"], "senders": ["admin"], "title": "aqr"}'
{
    "id": "23592",
    "title": "asd",
    "release_policy": "release_now",
    "release_date": "2017-10-13T13:49:44.235-0500",
    "expiration_date": "2017-10-27T13:49:44.235-0500",
    "sender": "jeff",
    "state": "held",
    "archived": false,
    "ear_enabled": null,
    "notifiable_on_upload": [],
    "notifiable_on_download": [],
    "active_downloads": 0,
    "active_downloaders": [],
    "download_count": 0,
    "downloaders": [],
    "total_bytes": 0,
    "total_files": 0,
    "creation_date": "2017-10-13T13:49:44.250-0500",
    "last_modified": "2017-10-13T13:49:44.239-0500",
    "mailbox": "outbox"
}

Delete a package (for a user or dropbox)

DELETE /api/users/{user_id}/packages/{package_delivery_id}
    DELETE /api/dropboxes/{dropbox_id}/packages/{package_delivery_id}

Deletes the package’s files from all storage shares. The package is no longer accessible to its recipients; the sender can no longer access the package in any way.

Query Parameters: None

Request Body: None

Success Response Codes

  • HTTP 204 No Content - Returned without a response body

Bulk delete packages (for a user or dropbox)

DELETE /api/users/{user_id}/packages/
DELETE /api/dropboxes)/{dropbox_id}/packages/

This method deletes multiple packages, according to the package IDs submitted in the request body.

Query Parameters: None

Request Body

{“package_ids”: [1, 2, ...]}

Success Response Code

  • HTTP 200 OK - Returned without a response body

Example Error Response

 [
{"package_id"=>1,
 "error": {
       	 "code"=>404,
   	 "user_message"=>"Package with id 1 for user admin not found.",
   	 "internal_message"=>"Package with id 1 for user admin not found."}
 }
]

Update and edit package attributes, recipients, and metadata

PUT /api/(users|dropboxes)/{user_id|dropbox_id}/packages/{package_delivery_id}

The effects of editing a package with the PUT request depend on its state (held, released, or expired):

  • Held or expired - The package’s recipients, attributes and metadata, only, are updated
  • Released - The package’s attributes and metadata are updated. New recipients are notified and the package is made available to them on their assigned shares. Recipients who are removed no longer have access to the package.

The state attribute is returned in the GET request, above.

Note the following issues to consider when updating or editing a package:

  • Caution: Submitting metadata in a request over-writes any previous data.
  • The encryption-at-rest passphrase cannot be edited.
  • Notifiables (usernames for users to notify when upload or download occurs) cannot be edited.

Query Parameters: None

Request Parameters

Parameter Name Required/Optional Format Default Value Description
title required string none Package title
recipients required string none Comma-separated list of usernames of package recipients
release_policy required string do_not_release Available values:
  • release_now - Faspex waits for one successful upload session to complete before routing the package to the recipients and sending notifications.
  • do_not_release - Package information is stored in Faspex’s MySQL database and the user can make subsequent uploads to add or remove files from the package.
  • release_on_date - Requires a value for release_date. If release_date is now or in the past, the release_on_date value is equivalent to release_now. If release_date is in the future, Faspex waits to send notifications and other actions until the first successful upload session completes or the release_date occurs, whichever is later.
note optional string none Developer's comment; location where old metadata is copied if overwritten by new values in the request
metadata optional Array of JSON objects in the form, { “name” : “field1”, “value” : value1 }. Must have a value if "require"=false in the metadata profile. none For package forwarding; adds new metadata according to the specification in the metadata profile. To view metadata profile information, query the Metadata Profiles endpoint.

Note: Submitting metadata in a request overwrites any previous data. However, the old metadata is copied to the note field.

release_date optional ISO date format null Date to route a package to recipients and send notifications. Used with a release_policy value of release_on_date.
expiration_date optional ISO date format null Expiration date for a package
download_limit optional unsigned integer null Number of times package can be downloaded
skip_recipient_validation optional boolean false If true, a list of usernames containing invalid values will not fail with an error.
notify_on_upload optional boolean true Whether to send a notifcation ("Package Received" email) upon successful file upload. If true, need a value for notifiable_on_upload.
notifiable_on_upload optional array of strings none List of usernames to notify when upload occurs. Must have a value if notify_on_upload is selected.
notify_on_download optional boolean true Whether to send a notifcation ("Package Received" email) upon successful file download. If true, need a value for notifiable_on_download.
notifiable_on_download optional array of strings none List of usernames to notify when a download occurs. Must have a value if notify_on_download is selected.

Success Response Codes

  • HTTP 200 OK - Returned with a package object in the response body

Error Response Codes

  • HTTP 400 Bad Request - Indicates a failure of package database operations
  • HTTP 500 Internal Server Error - Indicates that the creation of the empty directory failed; the package is marked as deleted

GET /api/(users|dropboxes)/{user_id|dropbox_id}/packages

This method returns information about packages matching the request parameters.

Request Parameters

.
Parameter Name Required/Optional Format Default Value Description
title optional string none Full or partial title search string
state[] optional string none Available values: held, released, expired, deleted. Multiple values can be included in the search request, for example: state[]=held&state[]=released
mailbox optional string none Allowed values: inbox, outbox
archived optional boolean none Package is still present in the system but does not appear in the list of sent and received packages in the UI. This parameter does not return a list of invalid usernames.

Response Codes

  • HTTP 200 OK - Returns an array of package objects corresponding to the search terms submitted in the request.

Forward a package

POST /api/users|dropboxes/{user_id}|{dropbox_id}/packages/{package_delivery_id}

Duplicates the original package; applies the title, recipients, and release policy that are specified in the forwarding request to this duplicate package.

Request Parameters

Parameter Name Required/Optional Format Default Value Description
title required string none Package title
recipients required string none Usernames of package recipients
senders required string none User sending the package
release_policy required string do_not_release Available values:
  • release_now - Faspex waits for one successful upload session to complete before routing the package to the recipients and sending notifications.
  • do_not_release - Package information is stored in Faspex’s MySQL database and the user can make subsequent uploads to add or remove files from the package.
  • release_on_date - Requires a value for release_date. If release_date is now or in the past, the release_on_date value is equivalent to release_now. If release_date is in the future, Faspex waits to send notifications and other actions until the first successful upload session completes or the release_date occurs, whichever is later.
note required string none Developer's comment. If nothing, use empty string ("")
metadata required, unless the value "require"=false in the metadata profile none String Adds new metadata according to the specification in the metadata profile. To get the metadata profile information, query the Metadata Profiles endpoint.

Caution: Submitting metadata in a request overwrites any previous data. However, the old metadata is copied to the note field.

release_date optional string null Date to route a package to recipients and send notifications. Used with a release_policy value of release_on_date.
expiration_date optional string null Expiration date for transfer of a package
download_limit optional unsigned integer null Size limit for packages

Response Codes

  • Success: HTTP 201 Created - Returned with a package object in the response body
  • Error: HTTP 400 Bad Request - Indicates a failure of package database operations

Replicate package contents

POST /api/(users|dropboxes)/{user_id}|{dropbox_id}/packages/{package_delivery_id}/replicate_contents

Replicates the contents from the destination share—for packages shared among workgroups— to all custom inboxes, recipient shares and override shares . The typical use case is replicating contents after editing a package.

Response Codes

  • Success: HTTP 200 OK - Returns a package object
  • Error: HTTP 408 Request Timeout - The server returns error data in the response, for example:
    [{"share_id"=>3, "error"=>"Unable to get transfer spec: Connection error"},
     {"share_id"=>4, "error"=>"Unable to get transfer spec: Connection error"},
     {"share_id"=>5, "error"=>"Unable to get transfer spec: Connection error"}]
    
Video player

Video

×