Introduction

Welcome to the TransferNow API!

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

Check out the HTTP Api documentation
Check out the Nodejs SDK documentation

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 allow access to the API. You can register a new TransferNow API key at our 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

You must replace xxxxxxxxxxxxxxxxxxxxxxxxx with your personal API key.

Key Limits

Any API key is limited to 100 000 requests per 24 hours. All requests to the public API count towards this limit.

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 JSON structured like this:

{
  "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

Response Codes

Code	Description
201	Transfer creation successful.
400	Bad request - your payload was probably malformed.
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 JSON structured like this:

{
  "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 JSON structured like this:

{
  "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.

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.

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 allow access to the API. You can register a new TransferNow API key at our 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.

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	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