NAV TransferNow
shell

Introduction

Welcome to the TransferNow API!

Use our API endpoints or our NodeJS SDK to programmatically upload and download files across the world!

HTTP API

Authentication

In all your requests, use this header:

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here" \
  -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxx"

Make sure to replace xxxxxxxxxxxxxxxxxxxxxxxxx with your personal API key.

TransferNow uses API keys to provide access to the API. Create a TransferNow API account to get a key to our TransferNow API website.

TransferNow expects the API key to be included in all API requests to the server in a header that looks like the following:

x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxx

Key Limits

Any API key is limited to 100 000 requests per 24 hours. All requests to the public API count towards this limit. If you require a larger quota, please contact our TransferNow API team via our website.

Transfers

The Transfer API offers the same features you can get with the TransferNow Website. Use it to upload files, get the link and share magic.

Transfers created through the APIs have the same limitations that you have when using the website.

Create a new Transfer

curl -XPOST "https://api.transfernow.net/v1/transfers" \
  -H "Content-Type: application/json" \
  -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
        "langCode": "en",
        "toEmails": ["my.contact@provider.com", "my.other.contact@provider.com"],
        "files": [{
          "name": "file1.txt",
          "size": 14587
        },{
          "name": "music.mp3",
          "size": 5496409
        }],
        "message": "A brillant transfer content, thank you",
        "subject": "Text and Music",
        "validityStart": "2022-10-28T08:52:25.955Z",
        "validityEnd": "2022-11-01T08:52:25.955Z",
        "allowPreview": true,
        "maxDownloads": 7
      }'

The above command returns a JSON with the following structure:

{
  "transferId": "20220928GtrzYF5U",
  "link": "https://www.transfernow.net/dl/20220928GtrzYF5U/Z1xqwZWq",
  "senderSecret": "Z1xqwZWq",
  "files": [
    {
      "multipartUpload": {
        "uploadId": "2~Smii4AV8TYNdq8d0e2tyN4Sa0NwV27a",
        "parts": [
          {
            "partNumber": 1,
            "start": 0,
            "size": 14587
          }
        ]
      },
      "size": 14587,
      "name": "file1.txt",
      "id": "lZEpvC1T"
    },
    {
      "multipartUpload": {
        "uploadId": "2~L43qAIUVYGeOOsqUEKi7K9ZYvT90Ctu",
        "parts": [
          {
            "partNumber": 1,
            "start": 0,
            "size": 5242880
          },
          {
            "partNumber": 2,
            "start": 5242880,
            "size": 253529
          }
        ]
      },
      "size": 5496409,
      "name": "music.mp3",
      "id": "hyPT4Sg1"
    }
  ]
}

Use this endpoint to create a new Transfer.

HTTP Request

POST https://api.transfernow.net/v1/transfers

Body Parameters

Parameter Mandatory Default Description
langCode false your user langCode The ISO lang code (eg. en) associated with your transfer, used for email notifications.
toEmails false [] The transfer recipient emails. Can be left empty for simple link creation.
files true The file array. Each file object consists of a name and a size attribute.
message true The message associated with your transfer, a description.
subject false "" The transfer subject.
validityStart false now A date in the future if you want to postpone the transfer.
validityEnd false + 7 days The date of the transfer end.
allowPreview false true Allow file preview when your recipient will access the file in our website.
maxDownloads false unlimited Limit the number of downloads (total download if no recipient, per recipient otherwise)
password false A password to protect the transfer download page
sseC false false Whether the password should be used to encrypt the data. This technique is known as Server-side encryption with customer-provided keys : SSE-C). Be aware that the following next steps will include additional settings if you enable this option.
customId false false Assign a customId to your transfer, will make your link customized with this id
timezone false "" Sets the date timezone to use in emails. If none provided, UTC will be used.

Response Codes

Code Description
201 Transfer creation successful.
400 Bad request - your payload was probably malformed. Possible limit errors include:
- MESSAGE_LENGTH_LIMIT_EXCEEDED: Message length exceeds the allowed limit.
- NUMBER_OF_FILES_LIMIT_EXCEEDED: Number of files exceeds the allowed limit.
- VALIDITY_LIMIT_EXCEEDED: File validity exceeds the allowed number of days.
- MAX_RECIPIENT_LIMIT_EXCEEDED: Number of recipients exceeds the allowed limit.
- UPLOAD_SIZE_LIMIT_EXCEEDED: Upload size exceeds the allowed limit.
- STORAGE_SIZE_LIMIT_EXCEEDED: Storage size exceeds the allowed limit.
- GLOBAL_STORAGE_SIZE_LIMIT_EXCEEDED: Global storage size exceeds the allowed limit.
401 Unauthorized - no API keys were provided.
403 Forbidden - invalid API key or quota was reached.

Request file part upload URLs

curl "https://api.transfernow.net/v1/transfers/20220928GtrzYF5U/files/lZEpvC1T/parts/1?uploadId=2~Smii4AV8TYNdq8d0e2tyN4Sa0NwV27a" \
  -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxx"

The above command returns a JSON with the following structure:

{
  "uploadUrl": "https://tnow-prod-eu-west-1-1.fra1.digitaloceanspaces.com/2022-10-28/22b86aee994ebb65a4bdccc072274dff/20220928EE8NVVFp/wRB1LP7R/file1.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=T2EJV3BHPLDZN6ZVKQR4%2F20220928%2Ffra1%2Fs3%2Faws4_request&X-Amz-Date=20220928T092803Z&X-Amz-Expires=900&X-Amz-Signature=1a9dfab700b4c557403e9d20cb774cda8866fbec84362928319058f17f893035&X-Amz-SignedHeaders=host&partNumber=1&uploadId=2~tseY85ruj4hylQDG2MdOBEO6WtOVFZb"
}

If you look at that response above, you see can see that all your files were split into a given number of parts. Depending on its size, a file can be split in one or more parts. Each parts of every files will have to be uploaded separately on different urls. For each part, you will have to query the following route on our API to get the upload url.

HTTP Request

GET https://api.transfernow.net/v1/transfers/{transferId}/files/{fileId}/parts/{partNumber}?uploadId={uploadId}

Path Parameters

Parameter Description
transferId The transfer id received in the transfer creation response.
fileId One of the file ids received in the transfer creation response.
partNumber One of the part number received in the transfer creation response.

Query Parameters

Parameter Description
uploadId The upload Id associated with the file in the transfer creation response.

Response Codes

Code Description
200 Url request was successful.
401 Unauthorized - no api keys were provided.
403 Forbidden - invalid api key, quota was reached.
404 Transfer or file not found.

File parts upload

curl -i -T "./path/to/file1.txt" "https://tnow-prod-eu-west-1-1.fra1.digitaloceanspaces.com/2022-10-28/22b86aee994ebb65a4bdccc072274dff/20220928EE8NVVFp/wRB1LP7R/file1.txt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=T2EJV3BHPLDZN6ZVKQR4%2F20220928%2Ffra1%2Fs3%2Faws4_request&X-Amz-Date=20220928T092803Z&X-Amz-Expires=900&X-Amz-Signature=1a9dfab700b4c557403e9d20cb774cda8866fbec84362928319058f17f893035&X-Amz-SignedHeaders=host&partNumber=1&uploadId=2~tseY85ruj4hylQDG2MdOBEO6WtOVFZb"

If you look at that response above, you see can see that you received a URL. Use this URL to upload your file content. Beware that you need to upload only the portion of the file corresponding to your file.

HTTP Request

PUT {uploadURL}

Header Description
x-amz-server-side-encryption-customer-algorithm Use this header to specify the encryption algorithm. The header value must be AES256.
x-amz-server-side-encryption-customer-key Use this header to provide the 256-bit, base64-encoded encryption key for TransferNow to use to encrypt or decrypt your data.
x-amz-server-side-encryption-customer-key-MD5 Use this header to provide the base64-encoded 128-bit MD5 digest of the encryption key according to RFC 1321. TransferNow uses this header for a message integrity check to ensure that the encryption key was transmitted without error.

Complete file upload

curl -XPUT "https://api.transfernow.net/v1/transfers/20220928GtrzYF5U/files/lZEpvC1T/upload-done?uploadId=2~tseY85ruj4hylQDG2MdOBEO6WtOVFZb" \
  -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxx"

Once all parts of a given file are uploaded, you need to call our API to complete the file upload.

HTTP Request

PUT https://api.transfernow.net/v1/transfers/{transferId}/files/{fileId}/upload-done

Path Parameters

Parameter Description
transferId The transfer id received in the transfer creation response.
fileId One of the file ids received in the transfer creation response.

Query parameters

Name Description
uploadId The upload Id associated with the file in the transfer creation response.

Response Codes

Code Description
200 Url request was successful.
401 Unauthorized - no api keys were provided.
403 Forbidden - invalid api key, quota was reached.
404 Transfer or file not found.

Complete Transfer upload

curl -XPUT "https://api.transfernow.net/v1/transfers/20220928GtrzYF5U/upload-done" \
  -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxx"

Once all files have been uploaded, you need to call our API to complete the transfer.

HTTP Request

PUT https://api.transfernow.net/v1/transfers/{transferId}/upload-done

Path Parameters

Parameter Description
transferId The transfer id received in the transfer creation response.

Response Codes

Code Description
200 Url request was successful.
401 Unauthorized - no api keys were provided.
403 Forbidden - invalid api key, quota was reached.
404 Transfer not found.

Get a Transfer

curl "https://api.transfernow.net/v1/transfers/20220928GtrzYF5U" \
  -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxx"

The above command returns a JSON with the following structure:

{
  "message": "A brillant transfer content, thank you",
  "langCode": "en",
  "notifications": {
    "expiryReminder": false,
    "summary": true,
    "downloadConfirmation": false
  },
  "skipScan": false,
  "owner": {
    "userId": "d253cb9b-c205-4cf5-a259-d27fb15e5243",
    "email": "your@email.com",
    "planType": "PREMIUM"
  },
  "recipients": [{
    "email": "my.contact@provider.com",
    "secret": "kdxH6f"
  }, {
    "email": "my.other.contact@provider.com",
    "secret": "qpR4X0"
  }],
  "lastStatusUpdate": "2022-09-28T11:31:46.183Z",
  "bucketPath": "2022-09-28/22b86aee994ebb65a4bdccc072274dff/20220928xE9xZ4W8",
  "bucketId": "7c44b5ff-832e-4d89-a808-487a051e3ff8",
  "files": [{
    "name": "file1.txt",
    "size": 14587,
    "id": "lZEpvC1T"
  },{
    "name": "music.mp3",
    "size": 5496409,
    "id": "hyPT4Sg1"
  }],
  "id": "20220928GtrzYF5U",
  "senderSecret": "eJXmc0EC",
  "totalDownloadedSize": 115071780,
  "sender": {
    "email": "your@email.com",
    "fullname": "John Doe"
  },
  "customFields": [],
  "subdomain": "www",
  "viewsCount": 0,
  "source": "API",
  "size": 23014356,
  "events": [
    {
      "timestamp": "2022-09-28T11:31:37.300Z",
      "code": "CREATED",
      "args": {}
    },
    {
      "code": "UPLOADED",
      "timestamp": "2022-09-28T11:31:46.007Z"
    },
    {
      "args": {
        "daysAvailable": 8,
        "recipientCount": 0
      },
      "code": "AVAILABLE",
      "timestamp": "2022-09-28T11:31:46.183Z"
    }
  ],
  "type": "S1",
  "allowPreview": true,
  "downloadsCount": 5,
  "validity": {
    "from": "2022-09-28T11:31:37.300Z",
    "to": "2022-10-05T11:31:37.300Z"
  },
  "createDate": "2022-09-28T11:31:37.300Z",
  "status": "ENABLED"
}

A transfer can be fetched to retrieve some of its metadata.

HTTP Request

GET https://api.transfernow.net/v1/transfers/{transferId}

Path Parameters

Parameter Description
transferId The transfer id received in the transfer creation response.

Response Codes

Code Description
200 Retrieve metadata was successful.
401 Unauthorized - no api keys were provided.
403 Forbidden - invalid api key, quota was reached.
404 Transfer not found.

Download a file

curl "https://api.transfernow.net/v1/transfers/20220928GtrzYF5U/files/lZEpvC1T" \
  -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxx"


curl -O "https://storage-prod-eu-west-1-a.transfernow.net/files/2024-04-03%2F4d781ec4b6678be59dc5712379c49983%2F20240403DRoWE9HG%2FBr8RyoI7%2Ffile1.txt?fileName=file1.txt&bucketName=tnow-prod-eu-west-1-1&size=8956853&singleFile=true&storageCache=true"

The above command returns a JSON with the following structure:

{
  "url": "https://storage-prod-eu-west-1-a.transfernow.net/files/2024-04-03%2F4d781ec4b6678be59dc5712379c49983%2F20240403DRoWE9HG%2FBr8RyoI7%2Ffile1.txt?fileName=file1.txt&bucketName=tnow-prod-eu-west-1-1&size=8956853&singleFile=true&storageCache=true"
}

Then download the file using the above url

curl -H "Referer: https://www.transfernow.net" -O "https://storage-prod-eu-west-1-a.transfernow.net/files/2024-04-03%2F4d781ec4b6678be59dc5712379c49983%2F20240403DRoWE9HG%2FBr8RyoI7%2Ffile1.txt?fileName=file1.txt&bucketName=tnow-prod-eu-west-1-1&size=8956853&singleFile=true&storageCache=true"

A file can be downloaded. First, retrieve the download url. Then, download the file.

HTTP Request

GET https://api.transfernow.net/v1/transfers/{transferId}/files/{fileId}

Path Parameters

Parameter Description
transferId The transfer id received in the transfer creation response.
fileId The file id received in the get transfer response.

Query Parameters

Parameter Description
password The optional password.
expiresInSecs The number of seconds after which the link will expires. Must be between 1 and 120. Default value "120".

Response Codes

Code Description
200 Retrieve metadata was successful.
401 Unauthorized - no api keys were provided.
403 Forbidden - invalid api key, quota was reached.
404 Transfer or file not found.

Delete a Transfer

curl -XDELETE "https://api.transfernow.net/v1/transfers/20220928GtrzYF5U" \
  -H "x-api-key: xxxxxxxxxxxxxxxxxxxxxxxxx"

A transfer can be permanently deleted. The associated files will no longer be available.

HTTP Request

DELETE https://api.transfernow.net/v1/transfers/{transferId}

Path Parameters

Parameter Description
transferId The transfer id to be deleted.

Response Codes

Code Description
200 Url request was successful.
401 Unauthorized - no api keys were provided.
403 Forbidden - invalid api key, quota was reached.
404 Transfer not found.

Search Transfers

curl -XPOST "https://api.transfernow.net/v1/search" \
  -H "Content-Type: application/json" \
  -H "x-api-key: a8b6aaa5-bc0f-46a2-ae26-42362aea40ae" \
  -d '{
        "from": 0,
        "size": 50,
        "sort": ["createDate:desc"],
        "types": ["S1", "S3"],
        "statuses": ["ENABLED"]
      }'

The above command returns a JSON with the following structure:

{
  "count": 1,
  "items": [
    {
      "message": "A brillant transfer content, thank you",
      "langCode": "en",
      "notifications": {
        "expiryReminder": false,
        "summary": true,
        "downloadConfirmation": false
      },
      "skipScan": false,
      "owner": {
        "userId": "d253cb9b-c205-4cf5-a259-d27fb15e5243",
        "email": "your@email.com",
        "planType": "PREMIUM"
      },
      "recipients": [
        {
          "email": "my.contact@provider.com",
          "secret": "kdxH6f"
        },
        {
          "email": "my.other.contact@provider.com",
          "secret": "qpR4X0"
        }
      ],
      "lastStatusUpdate": "2022-09-28T11:31:46.183Z",
      "bucketPath": "2022-09-28/22b86aee994ebb65a4bdccc072274dff/20220928xE9xZ4W8",
      "bucketId": "7c44b5ff-832e-4d89-a808-487a051e3ff8",
      "files": [
        {
          "name": "file1.txt",
          "size": 14587,
          "id": "lZEpvC1T"
        },
        {
          "name": "music.mp3",
          "size": 5496409,
          "id": "hyPT4Sg1"
        }
      ],
      "id": "20220928GtrzYF5U",
      "senderSecret": "eJXmc0EC",
      "totalDownloadedSize": 115071780,
      "sender": {
        "email": "your@email.com",
        "fullname": "John Doe"
      },
      "customFields": [],
      "subdomain": "www",
      "viewsCount": 0,
      "source": "API",
      "size": 23014356,
      "events": [
        {
          "timestamp": "2022-09-28T11:31:37.300Z",
          "code": "CREATED",
          "args": {}
        },
        {
          "code": "UPLOADED",
          "timestamp": "2022-09-28T11:31:46.007Z"
        },
        {
          "args": {
            "daysAvailable": 8,
            "recipientCount": 0
          },
          "code": "AVAILABLE",
          "timestamp": "2022-09-28T11:31:46.183Z"
        }
      ],
      "type": "S1",
      "allowPreview": true,
      "downloadsCount": 5,
      "validity": {
        "from": "2022-09-28T11:31:37.300Z",
        "to": "2022-10-05T11:31:37.300Z"
      },
      "createDate": "2022-09-28T11:31:37.300Z",
      "status": "ENABLED"
    }
  ]
}

This route lets you search your sent and received transfers.

HTTP Request

POST https://api.transfernow.net/v1/search

Body Parameters

Parameter Mandatory Default Description
from false 0 The start index of your search
size false 100 The max number of transfers returned. Please note the "count" attribute in the response will ignore the size limit and return the total number of items matching the query.
sort false ["createDate:desc"] List of fields to sort on.
senderEmail false Filter on the sender's email.
types false Filter on the transfer type ("S1" for transfer sent transfer to recipients, "S2" for transfer link generation, "S3" for received transfer in push, widget or secondary inbox).
statuses false Filter on the the transfer status ("UPLOADING", "CLONING", "MODERATING", "ENABLED", "PENDING", "DISABLED", "DELETED", "SCANNING").

Response Codes

Code Description
200 Url request was successful.
401 Unauthorized - no api keys were provided.
403 Forbidden - invalid api key, quota was reached.

Nodejs SDK

Authentication

The apiKey property has to be passed to the upload function on every call.

upload({
    apiKey: 'xxxxxxxxxxxxxxxxxxxxxxxxx',
    ...
});

Make sure to replace xxxxxxxxxxxxxxxxxxxxxxxxx with your personal API key.

TransferNow uses API keys to provide access to the API. Create a TransferNow API account to get a key to our TransferNow API website.

TransferNow expects the API key to be passed in every api usage.

Key Limits

Any API key is limited to 100 000 requests per 24 hours. All requests to the public API count towards this limit. If you require a larger quota, please contact our TransferNow API team via our website.

SDK Usage

Install the sdk with npm.

npm install @transfernow/api-sdk

Upload

The upload() function allows you to seamlessly upload your files, it handles all the magic ! See the example on the right section.

import {upload} from '@transfernow/api-sdk';

upload({
    apiKey: 'xxxxxxxxxxxxxxxxxxxxxxxxx',
    toEmails: ['my.contact@provider.com', 'my.other.contact@provider.com'],
    filePaths: ['/tmp/file_to_upload.txt', '/tmp/file2.txt'],
    message: 'A brillant transfer content, thank you',
    subject: 'Text and Music',
}).then(r => console.log(`transfer ${r.transferId} was sent successfully`))
    .catch(e => console.error(e));

Function Parameters

Parameter Mandatory Default Description
apiKey true Your API key
langCode false your user langCode The ISO lang code (eg. en) associated with your transfer, used for email notifications.
toEmails false [] The transfer recipient emails. Can be left empty for simple link creation.
filePaths false The file paths to be uploaded. At leat one path must be provided if no file url was provided.
fileUrls false The file urls to be uploaded. At leat one url must be provided if no file path was provided.
message true The message associated with your transfer, a description.
subject false "" The transfer subject.
validityStart false now A date in the future if you want to postpone the transfer.
validityEnd false + 7 days The date of the transfer end.
allowPreview false true Allow file preview when your recipient will access the file in our website.
maxDownloads false unlimited Limit the number of downloads (total download if no recipient, per recipient otherwise)
password false A password to protect the transfer download page
sseC false false Whether the password should be used to encrypt the data.
customId false false Assign a customId to your transfer, will make your link customized with this id.

Response

Attribute Description
transferId The generated transferId

Get transfer details

The get() function allows you to retrieve the transfer metadata.

import {get} from '@transfernow/api-sdk';

get({
    apiKey: 'xxxxxxxxxxxxxxxxxxxxxxxxx',
    toEmails: ['my.contact@provider.com', 'my.other.contact@provider.com'],
    filePaths: ['/tmp/file1.txt', '/tmp/file2.txt'],
    message: 'A brillant transfer content, thank you',
    subject: 'Text and Music',
}).then(transfer => console.log(`transfer metadata: ${JSON.stringify(transfer)}`))
    .catch(e => console.error(e));

Function Parameters

Parameter Mandatory Default Description
apiKey true Your API key
transferId true The transfer Id

Response

Attribute Description
...allTransfer metadata All the transfer attributes

Download

The download() function allows you to download your transfer files in a given location on disk.

import {download} from '@transfernow/api-sdk';

download({
    apiKey: 'xxxxxxxxxxxxxxxxxxxxxxxxx',
    transferId: '20220928GtrzYF5U',
    outputDirectory: '/tmp/downloads'
}).then(r => console.log('done'))
    .catch(e => console.error(e));

Function Parameters

Parameter Mandatory Default Description
apiKey true Your API key
transferId true The transfer Id
outputDirectory true The directory in which the transfer files will be copied
password false The transfer password if one was specified

Remove

The remove() function allows you to delete a transfer before it expires.

import {remove} from '@transfernow/api-sdk';

remove({
    apiKey: 'xxxxxxxxxxxxxxxxxxxxxxxxx',
    transferId: '20220928GtrzYF5U',
}).then(r => console.log('done'))
    .catch(e => console.error(e));

Function Parameters

Parameter Mandatory Default Description
apiKey true Your API key
transferId true The transfer Id

The search() function allows you to search for transfers.

import {search} from '@transfernow/api-sdk';

search({
    apiKey: 'xxxxxxxxxxxxxxxxxxxxxxxxx',
    types: [TransferType.S2]
}).then(r => console.log('results : ', r))
    .catch(e => console.error(e));
Parameter Mandatory Default Description
from false 0 The start index of your search
size false 100 The max number of transfers returned. Please note the "count" attribute in the response will ignore the size limit and return the total number of items matching the query.
sort false ["createDate:desc"] List of fields to sort on.
senderEmail false Filter on the sender's email.
types false Filter on the transfer type ("S1" for transfer sent transfer to recipients, "S2" for transfer link generation, "S3" for received transfer in push, widget or secondary inbox).
statuses false Filter on the the transfer status ("UPLOADING", "CLONING", "MODERATING", "ENABLED", "PENDING", "DISABLED", "DELETED", "SCANNING").
shell