Send files from another system

Your system uploads the file to Dew, gets a shared link back, and can have Dew email that link to the recipient with access limited to their address. This guide uses a billing system sending an invoice as the example.

Before you start, create a service account and token with the Files: Upload and share permission. Add Files: View and download to list or download what it sent, Files: Delete to withdraw a file, and Monitoring: File activity to see downloads in your system.

Upload the file

Send the file as the request body and name it in the URL. domain is the web address the link should use, without https://; leave it out to use the address you call:

curl -X PUT -H "Authorization: Bearer dewsa_<token>" -H "Content-Type: application/pdf" --data-binary @invoice-2291.pdf "https://files.example.com/api/file/invoice-2291.pdf?domain=files.example.com"

The response carries the file’s ID and its shared link:

{
  "success": true,
  "data": {
    "id": "q7Rk2LmZ",
    "url": "https://files.example.com/f/q7Rk2LmZ",
    "filename": "invoice-2291.pdf",
    "filesize": 1048576,
    "expires_at": "2026-11-03T09:15:00Z"
  }
}

The link is open to anyone who has it, and expires after the number of days your admin set for the domain (30 by default). Nobody has the link until you send it, so protect it in the next step before you do.

To protect the link in the same request instead, add the link settings to the URL. For a password Dew chooses, add &link_type=protected&protection_method=password&auto_generate=true: the response returns the password once, as data.generated_password. Email recipients can’t be set this way; use the next step for them.

Email it to the recipient

To have Dew email the link and ask the recipient for a code sent to their address before they can open it, change the link settings:

curl -X PUT -H "Authorization: Bearer dewsa_<token>" -H "Content-Type: application/json" -d '{"link_type":"protected","protection_method":"email","email_recipients":[{"email":"anna@customer.com"}],"email_message":"Your October invoice"}' https://files.example.com/api/file/q7Rk2LmZ/link-settings

Anna gets an email from the service account’s name with your message. Each change sends the full settings for the link, including link_type.

To protect the link with a password instead, send "protection_method":"password" with your own "password", or "auto_generate":true to have Dew choose one: the response returns it once, as data.generated_password. Send the password to the recipient another way than the link.

Set when the link expires

curl -X PUT -H "Authorization: Bearer dewsa_<token>" -H "Content-Type: application/json" -d '{"expires_at":"2026-10-31T23:59:59Z"}' https://files.example.com/api/file/q7Rk2LmZ/expiry

The date can’t be later than your domain’s maximum link lifetime: max_expiry_at in GET /api/files is the latest date each file allows. Links made through the API always expire; only an admin in the web app can remove a link’s expiry.

Send several files

Put the files in one ZIP and upload the ZIP. Unless your admin turned it off for the domain, its link opens a page where the recipient can see and download the files inside it, or download the whole archive.

Withdraw a file

To stop a link working before it expires, for example when an invoice is canceled, delete the file:

curl -X DELETE -H "Authorization: Bearer dewsa_<token>" https://files.example.com/api/file/q7Rk2LmZ

Know when the file was downloaded

Two options:

Email: turn on a download receipt, and Dew emails the service account’s contact email the first time someone downloads the file:

curl -X PUT -H "Authorization: Bearer dewsa_<token>" -H "Content-Type: application/json" -d '{"enabled":true}' https://files.example.com/api/file/q7Rk2LmZ/download-receipt

In your system: read file.downloaded events from the activity feed and match target.id to the file’s ID.

Check it worked

Open the link from the response in a private browser window. For an email-protected link, Dew asks for an email address and sends that address a code. GET /api/files lists what the service account has sent, newest first: 15 files per call by default, up to 100 with ?limit=100 (a higher value returns the default 15). For the next page, pass the last file’s created_at and id as cursor_ts and cursor_id.

If something doesn’t work

What you see	What to do
`403` with “This API token doesn’t have permission for this action.”	Add Files: Upload and share to the service account.
`403` with “Not allowed to use this domain”	Send a `domain` the service account has, or add the domain under Domains on the service account.
`413` with “File too large”	The file is larger than the domain allows. Ask your admin to raise the limit, or split the file.
The recipient didn’t get the email	Check their spam folder, then resend with `POST /api/file/<id>/resend-invitations`.

Every endpoint used here is in the Files API reference.