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 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. |
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 |
Search
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"). |