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

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