File Transfer 2.0 API Specification

Using the API

You will need to contact the State ITSD service desk either by phone at 406-444-2000, or by email at servicedesk@mt.gov to obtain an API user account.

All API methods are protected with HTTP Basic Authentication (http://www.w3.org/Protocols/HTTP/1.0/spec.html#BasicAA). Once your user agent is authenticated (use the username and password supplied to you) you will be able to use all of the api methods.

/add_user_access

MT DRIVE FUNCTIONALITY

Not available for API users. Only State Employee users can access this functionality.

DESCRIPTION

Adds one or more user(s) to an access role for a MT Drive folder that the current logged in user is an owner of and sends an invitation email. Returns the meta-data for the MT Drive folder and the users added. The data includes: folder name, email address for user(s), access role, owner name,an optional message added to the invitation email, as well as, an error code and message if an error occurred. The user cannot already have a role for the MT Drive Folder.

URL STRUCTURE

https://transfer.mt.gov/api2/add_user_access?param=val

param=val The URL-encoded parameters for this request. They cannot be sent in the request body.

METHOD

GET

PARAMETER

Field	Type	Description
folderName	[required]	The name of the MT Drive folder to add the user(s) access to. Folder must be owned by the currently logged in user.
role	[required]	The role to grant to the user(s). Values are VIEW and EDITOR
inviteUsers	[required]	One or more user email addresses. If more than one, separate using a comma.
message	[optional]	Additional message to add to the invitation email that user(s) will receive inviting them to the folder.

RETURNS

200 The metadata of your access request. The following describes the format of the response:

Sample JSON response

{
    "folderName":"Shannons Folder",
    "ownerName":null,
    "role":"VIEW",
    "inviteUsers":[ "mmouse@disney.com","donaldduck@disney.com","pluto@disney.com"],
    "message":"Welcome to my folder!!",
    "ErrorCode":null,
    "ErrorMessage":null
}

Errors

Code	Description
402	Returned if a user already has an access role to the folder already. A user can only have one access role per folder.
403	Returned if access denied (user must be the owner of a folder) or credentials used are not valid.
404	Returned if a folder with the folderName owned by the currently logged in user was not found.
400	Returned if folderName, role, or user(s) were not provided. If a role other than VIEW or EDITOR were passed as param. Returned if the folder is disabled or the owner no longer exists.

/remove_user_access

MT Drive Functionality

Not available for API users. Only State Employee users can access this functionality.

Description

Removes a specific user access role for a MT Drive Folder that the currently logged in user is the owner of. Returns the meta-data for the user access that was removed. The data includes: folder name, user email address, and access role.

URL Structure

https://transfer.mt.gov/api2/remove_user_access?param=val

param=val The URL-encoded parameters for this request. They cannot be sent in the request body.

Method

GET

Parameter

Field	Type	Description
folderName	[required]	The name of the MT Drive folder to remove the user access to. Logged in user must be the owner.
role	[required]	The name of the role to remove permission for the user(s). Values are VIEW and EDITOR
userEmail	[required]	The email address of the user.

Returns

200 The metadata of your access request. The following describes the format of the response:

Sample JSON response

{
    "folderName": Shannons Folder,
    "role": VIEW,
    "userEmail": mmouse@disney.com
}

Errors

Code	Description
403	Returned if access denied (logged in user must be the owner of the folder).
404	Returned if the folder was not found by the folder name provided.
400	Returned if folder name, role, or user email address were not provided. If a role other than VIEW or EDITOR were passed as param. Returned if the folder is disabled or the owner no longer exists. Returned if a user is not found for the email address provided.

/retrieve_folder

MT Drive Functionality

An API User can only use this functionality if they have been invited to view or edit a State Users folder.

Description

Retrieves the meta-data for the MT Drive folder for the folder name and owner provided.

URL Structure

https://transfer.mt.gov/api2/retrieve_folder?param=val

param=val The URL-encoded parameters for this request. The parameter cannot be sent in the request body.

Method

GET

Parameter

Field	Type	Description
folderName	[required]	The name of the MT Drive folder to retrieve. Maximum length is 50 characters. Logged in user must either be the owner or have access to the folder.
ownerEmail	[required]	The email address of the owner of the folderName that is passed in.

Returns

200 The metadata of the folder found. The following describes the format of the response:

Sample JSON response

{
    "folderName":"Shannons Folder",
    "ownerEmail":"somewheree@mt.gov",
    "ownerName":"Shannon Jackson",
    "createdDate":"2015-02-26T00:00:00",
    "viewUsers":
        [
            {"UserName":"Kurt Jones",
            "UserID":38778,
            "accessRole":"VIEW",
            "emailAddress":"KJones@mt.gov",
            "UserAccessID":309
            },
            {"UserName":"shannon Jorge",
             "UserID":73450,
            "accessRole":"VIEW",
            "emailAddress":"adams@msn.com",
            "UserAccessID":291
            }
        ],
    "editUsers":
        [
            {"UserName":"Evan Jirrad",
            "UserID":58679,
            "accessRole":"EDITOR",
            "emailAddress":"jirrad@mt.gov",
            "UserAccessID":311
            },
            {"UserName":"John Stocki",
            "UserID":58942,
            "accessRole":"EDITOR",
            "emailAddress":"johsn@mt.gov",
            "UserAccessID":310
            }
         ],
    "delAdminUsers":[],
    "folderSize":159264257,
    "currentUserAccessRole":null
}

Errors

Code	Description
403	Returned if access denied (user must be a viewer, editor, or owner of a folder). Returned if the logged in user is not valid.Returned if the ownerEmail is neither the owner or an editor of the folderName provided.
404	Returned if the MT Drive Folder was not found with the folder name provided. Returned if the user for the ownerEmail provided was not found.

/create_new_folder

MT Drive Functionality

Not available for API users. MT Drive storage is for State Employees only.

Description

Creates a new MT Drive folder with the name passed in for the logged in user.

URL Structure

https://transfer.mt.gov/api2/create_new_folder?param=val

param=val The URL-encoded parameters for this request. The parameter cannot be sent in the request body.

Method

GET

Parameter

Field	Type	Description
folderName	[required]	The name of the MT Drive folder to create. If the name already exists, a (1) will be appended to the end of the folder name. Maximum length is 50 characters.

Returns

200 The metadata of your newly created folder. The following describes the format of the response:

Sample JSON response

{
    "folderName":"Shannons Folder",
    "ownerEmail":"somewhere@mt.gov",
    "ownerName":"Shannon Owner",
    "createdDate":"2015-02-26T00:00:00",
    "viewUsers":[],
    "editUsers":[],
    "delAdminUsers":[],
    "folderSize":null,
    "currentUserAccessRole":null
}

Errors

Code	Description
403	Returned if access denied the logged in user does not exist.

/retrieve_folders

MT Drive Functionality

Not available for API users. Only State Employee users can access this functionality.

Description

Retrieves the meta-data for all the MT Drive folders the logged in user is the owner of.

URL Structure

https://transfer.mt.gov/api2/retrieve_folders

Method

GET

Returns

200 The meta-data of the logged in user's MT Drive folders. The following describes the format of the response:

Sample JSON response

[{
    "folderName":"Shannons Folder",
    "ownerEmail":"somewhere@mt.gov",
    "ownerName":"Shannon Owner",
    "createdDate":"2015-02-26T00:00:00",
    "viewUsers":
        [
            {"UserName":"Kurt Jones",
            "UserID":38778,
            "accessRole":"VIEW",
            "emailAddress":"kjones@mt.gov",
            "UserAccessID":309
            },
            {"UserName":"shannon Johhsnonc",
             "UserID":73450,
            "accessRole":"VIEW",
            "emailAddress":"jore345@msn.com",
            "UserAccessID":291
            ,
        ],
    "editUsers":
        [
            {"UserName":"Evan Jaorkord",
            "UserID":58679,
            "accessRole":"EDITOR",
            "emailAddress":"jackord@mt.gov",
            "UserAccessID":311
            },
            {"UserName":"John Microsoft",
            "UserID":58942,
            "accessRole":"EDITOR",
            "emailAddress":"joshnc@mt.gov",
            "UserAccessID":310
            }
       ],
    "delAdminUsers":[],
    "folderSize":159264257,
    "currentUserAccessRole":null
},
{   "folderName":"Shannons Second Folder",
    "ownerEmail":"somewhere@mt.gov",
    "ownerName":"Shannon Owner",
    "createdDate":"2015-02-26T00:00:00",
    "viewUsers":
        [
            {"UserName":"Kurt Jones",
            "UserID":38778,
            "accessRole":"VIEW",
            "emailAddress":"Jones@mt.gov",
            "UserAccessID":309
            }
        ],
    "editUsers":[],
    "delAdminUsers":[],
    "folderSize":5874,
    "currentUserAccessRole":null
}]

Errors

Code	Description
403	Returned if access denied.

/retrieve_shared_folders

MT Drive Functionality

An API User can only use this functionality if they have been invited to view or edit a State Users folder.

Description

Retrieves the meta-data for all the MT Drive folders that are shared with the user who is logged in.

URL Structure

https://transfer.mt.gov/api2/retrieve_shared_folders?param=val

param=val The URL-encoded parameters for this request. The parameter cannot be sent in the request body.

Method

GET

Parameter

Field	Type	Description
role	[optional]	The access role to retrieve shared folders for. The values are VIEW or EDITOR. If not passed in, all folders that are shared with the currently logged in user.

Returns

200 Returns the meta-data of the logged in user's shared MT Drive folders. If no parameter is passed in, all the folders that are shared with the logged in user are returned.

The following describes the format of the response:

Sample JSON response

    [{
        "folderName":"Shannons Folder",
        "ownerEmail":"somewhere@mt.gov",
        "ownerName":"Shannon Stencil",
        "createdDate":"2015-02-26T00:00:00",
        "viewUsers":
            [
                {"UserName":"Kurt Jones",
                "UserID":38778,
                "accessRole":"VIEW",
                "emailAddress":"kurt@mt.gov",
                "UserAccessID":309
                },
                {"UserName":"shannon Poshmark",
                 "UserID":73450,
                "accessRole":"VIEW",
                "emailAddress":"posher@msn.com",
                "UserAccessID":291
                ,
            ],
        "editUsers":
            [
                {"UserName":"Evan Robbionson",
                "UserID":58679,
                "accessRole":"EDITOR",
                "emailAddress":"robbionsls@mt.gov",
                "UserAccessID":311
                },
                {"UserName":"John Schulketer",
                "UserID":58942,
                "accessRole":"EDITOR",
                "emailAddress":"schulterks@mt.gov",
                "UserAccessID":310
                }],
        "delAdminUsers":[],
        "folderSize":159264257,
        "currentUserAccessRole":null
    },
    {   "folderName":"Shannons Second Folder",
        "ownerEmail":"somewhere@mt.gov",
        "ownerName":"Shannon Posher",
        "createdDate":"2015-02-26T00:00:00",
        "viewUsers":
            [
                {"UserName":"Kurt Jones",
                "UserID":38778,
                "accessRole":"VIEW",
                "emailAddress":"Jones@mt.gov",
                "UserAccessID":309
                }
            ],
        "editUsers":[],
        "delAdminUsers":[],
        "folderSize":5874,
        "currentUserAccessRole":null
    }]

Errors

Code	Description
403	Returned if access denied. If the currently logged in user is not valid.

/retrieve_mt_drive_files

MT Drive Functionality

An API User can only use this functionality if they have been invited to view or edit a State Users folder.

Description

Retrieves the meta-data for the files inside of a specific MT Drive folder. The data includes: bytes, filename, status, folderName, transferId, uploadDate, removed, and the state of the file. The files must be in one of these states: READY_FOR_DOWNLOAD, UPLOAD_COMPLETE, VIRUS_SCAN.

URL Structure

https://transfer.mt.gov/api2/retrieve_mt_drive_files?param=val

param=val The URL-encoded parameters for this request. The parameter cannot be sent in the request body.

Method

GET

Parameter

Field	Type	Description
folderName	[required]	The name of the MT Drive folder to retrieve the files for.
ownerEmail	[optional]	The email address of the owner of the folderName to retrieve files for. If not present, the logged in user is the owner.

Returns

200 The metadata of the files inside of the MT Drive folder. The following describes the format of the response:

Sample JSON response

[{ 
    "bytes":116438, 
    "fileName":"FTS2APISpecification (1).docx", 
    "folderName":"Shannons Folder", 
    "transferId":"bf40c221-8912-4393-895f-53c188e73090", 
    "uploadDate":"2015-03-05T14:22:08.893", 
    "status":"REMOVED_MT_DRIVE", 
    "removed":false, 
    "uploadedBy":"Shannon Sitser" 
}, 
{ 
    "bytes":24270, 
    "fileName":"DownloadAttachment (1).docx", 
    "folderName":"Shannons Folder", 
    "transferId":"a04735a8-7ef2-4050-b83f-0a1510658cb0", 
    "uploadDate":"2015-03-05T14:22:09.147", 
    "status":"REMOVED_MT_DRIVE", 
    "removed":false, 
    "uploadedBy":"Shannon Sitser" 
}, 
{ 
    "bytes":16317, 
    "fileName":"DownloadAttachment.docx", 
    "folderName":"Shannons Folder", 
    "transferId":"1760dcf4-3cd4-4110-be98-4def4ae46e1d", 
    "uploadDate":"2015-03-05T14:22:09.393", 
    "status":"REMOVED_MT_DRIVE", 
    "removed":false, 
    "uploadedBy":"Shannon Sitser" 
}]

Errors

Code	Description
403	Returned if access denied. The currently logged in user is not valid.
404	Returned if the ownerEmail address provided is not found.

/received_files_report

Description

Retrieves the meta-data for a specific file transfer. The data includes: file information of removed, bytes, filename, status, transferId, downloadDate, expireDate, senderName, and uploadedDate Also returned is the messages that have been entered for the file, and any recipient messages entered for the file (Example: date recipient downloaded file - messageType="DOWNLOADED").

URL Structure

https://transfer.mt.gov/api2/received_files_report?param=val

param=val The URL-encoded parameters for this request. They cannot be sent in the request body.

Method

GET

Parameter

Field	Type	Description
transferID	[required]	The transferID that uniquely identifies a file in the system.

Returns

200 The metadata of your received files. The following describes the format of the response: NOTE: The difference between fileMessages and recipientMessages - there is not a value for the recipientName in the fileMessages

Sample JSON response

{
"receivedFile":
{
    "bytes":17436,
    "fileName":"Decision Type.docx",
    "transferId":"80eb84ee-5647-4f0d-bc39-939840e0d1a9",
    "uploadedDate":"2015-01-12T14:17:41.317",
    "expireDate":"2015-01-27T14:17:41.317",
    "senderName":"George Jones",
    "senderEmail":null,
    "downloadDate":"2015-01-12T14:20:00.413",
    "removed":false,
    "status":"Ready for Download"
},
"fileMessages":
[{
    "message":"You have a new file available in your File Transfer Service Inbox.",
    "messageType":"UPLOAD",
    "messageDate":"2015-01-12T14:17:41.327",
    "recipientName":""
},
{
    "message":"Did you receive my email?",
    "messageType":"USER",
    "messageDate":"2015-01-12T14:18:14.103",
    "recipientName":""
},
{
    "message":"Beginning the virus scan for file: Decision Type.docx",
    "messageType":"VIRUS_SCAN",
    "messageDate":"2015-01-12T14:18:59.133",
    "recipientName":""
}],
"recipientMessages":
[{ 
    "message":"The file was downloaded successfully.",
    "messageType":"DOWNLOADED",
    "messageDate":"2015-01-12T14:20:00.43",
    "recipientName":"Missy Smith"
}]
}

/sent_files_report

Description

Retrieves the meta-data for a specific file transfer that was sent. The data includes: file information of: removed, bytes, fileName, status, transferId, expireDate, recipients, and uploadDate Also returned are the recipients’ names and email address that the file was sent to, the messages for the files, and the recipient messages on the file. NOTE: The file messages do not have a recipientName meaning they are messages on the file itself, where recipient messages have a specific recipient, so that you may retrieve the date downloaded for a recipient by looking at the messageType=”DOWNLOADED”

URL Structure

https://transfer.mt.gov/api2/sent_files_report?param=val

param=valThe URL-encoded parameters for this request. They cannot be sent in the request body.

Method

GET

Parameter

Field	Type	Description
transferID	[required]	The transferID that uniquely identifies a file in the system.

Returns

200 The metadata of your sent file. The following describes the format of the response:

Sample JSON response

{"sentFiles":
{
    "bytes":17436,
    "fileName":"Decision Type.docx",
    "recipients":[{"recipientName":"Rebecca Black","recipientEmail":Srblacksmith25@mt.gov},{"recipientName":"Bekkatica Orange","recipientEmail":orange@msn.com}],
    "transferId":"80eb84ee-5647-4f0d-bc39-939840e0d1a9",
    "uploadDate":"2015-01-12T14:17:41.317",
    "status":"Ready for Download",
    "expiredDate":"2015-01-27T14:17:41.317",
    "removed":false
},
"fileMessages":
    [{"message":"You have a new file available in your File Transfer Service Inbox.","messageType":"UPLOAD","messageDate":"2015-01-12T14:17:41.327","recipientName":""},
    {"message":"Did you receive my email?","messageType":"USER","messageDate":"2015-01-12T14:18:14.103","recipientName":""},
    {"message":"Beginning the virus scan for file: Decision Type.docx","messageType":"VIRUS_SCAN","messageDate":"2015-01-12T14:18:59.133","recipientName":""}],
    "recipientMessages":
    [{"message":"The file was downloaded successfully.",messageType":"DOWNLOADED","messageDate":"2015-01-12T14:20:00.43","recipientName":"Latilda Blue"}]
}

/change_password

Description

Changes the password for your api account.

URL Structure

https://transfer.mt.gov/api2/change_password?param=val

param=valThe URL-encoded parameters for this request. They cannot be sent in the request body.

Method

GET

Parameter

Field	Type	Description
oldPassword	[required]	Your current password.
newPassword	[required]	The new password to set.

Returns

200 The specified file’s contents.

Sample JSON response

"true"

Errors

The call will return false if the oldPassword parameter does not match the current password.

/get_file

Description

Downloads a file.

URL Structure

https://transfer.mt.gov/api2/get_file?param=val

param=valThe URL-encoded parameters for this request. They cannot be sent in the request body.

Method

GET

Parameter

Field	Type	Description
transferId	[required]	The transferId that uniquely identifies a file in mt-drive.

Returns

200 The specified file’s contents.

The HTTP response contains meta-data in JSON format within an x-mt-drive-metadata header The content of the x-mt-drive-metadata header are shown below:

Sample JSON response

{
    "bytes" : 33 ,
    "fileName" : "test.txt" ,
    "transferId" : "80eb84ee-5647-4f0d-bc39-939840e0d1a9"
}

Errors

Code	Description
403	Logged-in user does not have permission to download the file.
404	The file wasn’t found.

/chunked_upload

Description

Uploads large files in multiple chunks. Also has the ability to resume if the upload is interrupted. This allows for uploading large files with a slow or unreliable network connection.

Typical usage:

Send a POST request to /chunked_upload with the first chunk of the file without setting a transferId, and receive a transferId in return.
Repeatedly POST subsequent chunks using the upload_id to identify the upload in progress and an offset representing the number of bytes transferred so far.
After each chunk has been uploaded, the server returns a new offset representing the total amount transferred.
After the last chunk, POST to /commit_chunked_upload to complete the upload.

Chunks can be any size up to 2GB. A typical chunk is 4 MB. Using large chunks will mean fewer calls to /chunked_upload and faster overall throughput. However, whenever a transfer is interrupted, you will have to resume at the beginning of the last chunk, so it is often safer to use smaller chunks.

If the offset you submit does not match the expected offset on the server, the server will ignore the request and respond with a 400 error that includes the current offset. To resume upload, seek to the correct offset (in bytes) within the file and then resume uploading from that point.

A chunked upload can take a maximum of 24 hours before expiring.

URL Structure

https://transfer.mt.gov/api2/chunked_upload?param=val

param=val The URL-encoded parameters for this request. They cannot be sent in the request body.

Method

POST

Request Headers

Content-Length: The Content-Length request header is required and must match the amount of data sent in the request body (measured in number of bytes). See RFC 2616 for details.

Request Body

required A chunk of data from the file being uploaded. If resuming, the chunk should begin at the number of bytes into the file that equals the offset.

Parameter

Field	Type	Description
transferId		The transferId of the file. If left blank, the server will create a new transferId and return it in the metadata.
offset		The offset into the file (in bytes). If left blank, 0 is assumed.

Returns

200 The metadata for the uploaded file. The following describes the format of the response:

Sample JSON response

{
    "transferId": "2C7339CF-2B09-4501-B3F3-F3508C9228ED", 
    "offset": 31337, 
    "expires": "Tue, 19 Jul 2011 21:55:38 +0000",
    "fileName":"TortoiseSVN-1.8.10.26129-x64-svn-1.8.11.msi" 
}

Errors

Code	Description
400	The offset parameter does not match up with what the server expects. The body of the error response will be JSON similar to the above, indicating the correct offset to upload.
404	The transferId does not exist or has expired.

/commit_chunked_upload

Description

Completes an upload initiated by the /chunked_upload method. Saves a file uploaded via /chunked_upload to mt-drive. An API User can only send to email addresses of State Employees or other API Users. Trying to address to any other email address will not work.

URL Structure

https://transfer.mt.gov/api2/commit_chunked_upload

Method

POST

Request Headers

Content-Length: The Content-Length request header is required and must match the amount of data sent in the request body (measured in number of bytes). See RFC 2616 for details.

Request Body

required The body contains a json message containing the meta-data and recipients of the file.

Sample JSON request body

{ 
    "emailRecipients": ["user1@mt.gov" , "user2@mt.gov"], 
    "stateGroupRecipients" : ["GROUP_1" , "GROUP2"], 
    "filename": "Getting_Started.pdf", 
    "transferId" : "2C7339CF-2B09-4501-B3F3-F3508C9228ED" 
}

Returns

200 The metadata for the uploaded file. The following describes the format of the response:

Sample JSON response

{ 
    "bytes": 230783, 
    "filename": "Getting_Started.pdf", 
    "transferId": "2C7339CF-2B09-4501-B3F3-F3508C9228ED"
}

Errors

Code	Description
400	Returned if the request does not contain a transferId or if there is no chunked upload matching the given transferId. Also returned if there are no recipients.

/commit_mover_upload

Description

Completes an upload initiated by the /chunked_upload method as a Mover Type file. This sets the file to be moved to the location associated with a given name. When the file is moved to the given location, it is named using the following format:

transferId_

Example: ad0873ed-1e13-49ed-a18e-28ddd974c255_testing.txt

URL Structure

https://transfer.mt.gov/api2/commit_mover_upload?param=val

param=val The URL-encoded parameters for this request. They cannot be sent in the request body.

Method

GET

Parameter

Field	Type	Description
transferId	[required]	The transferId of the file to be moved.
moverLocationName	[required]	The name of the mover location as defined in File Transfer Service database.
fileName	[required]	The name of the file to be moved.

Returns

200 The metadata for the uploaded file. The following describes the format of the response:

Sample JSON response

 { 
    "bytes": 230783, 
    "filename": "Getting_Started.pdf", 
    "transferId": "2C7339CF-2B09-4501-B3F3-F3508C9228ED"
}

Errors

Code	Description
300	Returned if the file is not in the correct state to be Committed.
403	Returned if access denied (you did not initiate the transfer)
404	Returned if the file or mover location was not found.

/commit_mt_drive_upload

MT Drive Functionality

MT Drive storage is only available to State Employees. API users can commit to a state users MT Drive folder only if they have been invited as an "Editor" of the folder.

Description

Completes an upload initiated by the /chunked_upload method as an MT Drive file. This endpoint will commit an upload to the specified folder name for the specified email address.

If an email address not sent with the request, the folder for the user will be created or renamed as provided.

URL Structure

https://transfer.mt.gov/api2/commit_mt_drive_upload?param=val

param=val The URL-encoded parameters for this request. They cannot be sent in the request body.

Method

GET

Parameter

Field	Type	Description
transferId	[required]	The transferId of the file associated with the MT Drive Folder
folderName	[required]	The name of the MT Drive Folder
fileName	[required]	The name of the file that was uploaded
ownerEmail	[optional]	MT drive folder owner’s email address, if blank assumes owner is current logged in user. Only state employees can own folders.

Returns

200 The metadata for the uploaded file. The following describes the format of the response:

Sample JSON response

 { 
    "bytes": 230783, 
    "filename": "Getting_Started.pdf", 
    "transferId": "2C7339CF-2B09-4501-B3F3-F3508C9228ED"
}

Errors

Code	Description
300	Returned if the file is not in the correct state to be Committed.
403	Returned if access denied (user must be an editor or owner of a folder) also the folderName must belong to the email provided.
404	Returned if the file was not found.

/received_files

Description

Returns a list of received files that belong to the authenticated user which includes information such as file name, transferId, size (in bytes), expire date (when it will be removed from the server), upload date, and details on the sender of the file (name and email address).

URL Structure

https://transfer.mt.gov/api2/received_files

Method

GET

Returns

200 The metadata of your received files. The following describes the format of the response:

Sample JSON response

 [{ 
    "bytes": 230783, 
    "fileName": "Getting_Started.pdf", 
    "transferId": "2C7339CF-2B09-4501-B3F3-F3508C9228ED", 
    "uploadedDate": "Tue, 19 Jul 2011 21:55:38 +0000", 
    "expireDate": "Wed, 04 Aug 2011 21:55:38 +0000", 
    "senderName": "Peter Jones", 
    "senderEmail": "Pjones@mt.gov", 
    "downloadDate": "Thu, 05 Aug 2011 21:55:38 +0000", 
    "removed":false , 
    "status": "Ready for Download" 
}, 
{ "bytes": 252343, 
    "filename": "Moving_Forward.pdf", 
    "transferId": "2C7339CF-2B09-4501-B3F3-F3508C9228ED", 
    "uploadDate": "Tue, 19 Jul 2011 21:55:38 +0000", 
    "expireDate": "Wed, 04 Aug 2011 21:55:38 +0000", 
    "senderName": "Melissa Jenkins", 
    "senderEmail": "Mjenkins@mt.gov", 
    "downloadDate": "Thu, 05 Aug 2011 21:55:38 +0000", 
    "removed":true , 
    "status": "Ready for Download" 
}]

/sent_files

Description

Returns a list of files the authenticated user has sent with a list of file recipient names and emails if available. Includes information such as file name, transferId, size (in bytes), expire date (when it will be removed from the server), upload date, and details on the recipients of the file (name and email address).

URL Structure

https://transfer.mt.gov/api2/sent_files

Method

GET

Returns

200 The metadata of your received files. The following describes the format of the response:

Sample JSON response

 [{ 
    "bytes":53248, 
    "fileName":"NetReflector.dll", 
    "recipients": [{ "recipientName":"John Smith", "recipientEmail": "--------@mt.gov" }], 
    "transferId":"6b2ed8b4-28ea-40fa-a9ad-0aacae3b23c7", 
    "uploadDate":"2014-12-09T11:29:23.577", 
    "status":"Ready for Download", 
    "expiredDate":"2014-12-24T11:29:23.577", 
    "removed": false, 
}, 
{ "bytes":95775, 
    "fileName":"SVN Repository Guide (2).docx", 
    "recipients": [{ "recipientName":"John Schuldt", "recipientEmail":"------@mt.gov" }, { "recipientName":" ", "recipientEmail":"-------@gmail.com" }, { "recipientName":"Tom Cruise", "recipientEmail":"-------@mt.gov" }],
    "transferId":"291cb254-8a47-4faf-a601-3e9561723557", 
    "uploadDate":"2014-12-09T14:16:28.703", 
    "status":"Transfer was initiated, but no file uploaded for unknown reason", 
    "expiredDate":"2014-12-24T14:16:28.703", 
    "removed": false 
}]

Flow Charts

Mover Flow (External Client)

Recipient Flow (Internal Client, External Customer)

Recipient Flow (External Client, Internal Customer)

Using wget Utility

(available on unix environment and Cygwin on windows)

wget --user user --password password https://test.transfer.mt.gov/api2/received_files

wget --user user --password password https://test.transfer.mt.gov/api2/get_file?transferId=transferid

The following (if you put it into a shellscript called wget_upload.sh) will upload a file to fts.

#!/bin/bash
#FileName: wget_upload.sh
#This is an example on how to call the fts2 api to upload a file.
#Put the result of the api call into x
echo Calling chunked_upload
x=`wget --user user --password password --post-file wget_upload.sh -O - https://test.transfer.mt.gov/api2/chunked_upload`
#Parse the transferid into $y
echo Parsing the transferId
y=`echo $x|sed -e 's/^.*"transferId":"\([^"]*\).*$/\1/'` 
#Finalize the upload by calling commit_chunked_upload. This is where you pick the recipients.
echo Calling commit_chunked_upload
wget --user user --password password -O - --post-data '{"emailRecipients" : ["state-user-email-address@mt.gov"] , "fileName" : "test-file2.txt" , "transferId" : "'$y'"}' https://test.transfer.mt.gov/api2/commit_chunked_upload