Receive links.

A receive link lets someone without an account send files into a folder you can write. These calls manage the link. The sender's page is not called with an API key.

Receive links need the portal feature. Custom questions on a link need the automation feature. See the API reference for the key and for errors.

The link

GET /api/v1/receive-links

Your receive links, and the limits that apply to a new one.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

A receive link is an address you give to people who have no account, so they can send files straight into one of your folders. Receive links are part of the portal feature. An administrator sees every link on the server; everyone else sees their own, newest first. policy says whether a link may never expire, how many days a new one lasts by default, and whether this license includes custom form fields.

Success. 200.

{
  "links": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "name": "Rush delivery",
      "message": "The cut is in the folder.",
      "rootId": "k7Qm2sLp9vX4aB1c",
      "rootName": "example",
      "path": "projects/rush",
      "spaceName": "example",
      "spacePath": "projects/rush",
      "hasPasscode": true,
      "requireEmail": true,
      "verifyEmail": true,
      "allowedTypes": "example",
      "oneTime": true,
      "subfolder": true,
      "subfolderTemplate": "example",
      "notifyOwner": true,
      "formFields": [
        {
          "id": "k7Qm2sLp9vX4aB1c",
          "label": "example",
          "kind": {},
          "required": true,
          "choices": [
            "example"
          ]
        }
      ],
      "state": "active",
      "bytesReceived": 1,
      "submissionCount": 1,
      "ownerId": "k7Qm2sLp9vX4aB1c",
      "ownerEmail": "[email protected]",
      "createdAt": "2026-10-05T18:00:00Z"
    }
  ],
  "policy": {
    "allowNeverExpires": true,
    "defaultExpiryDays": 1,
    "formFieldsIncluded": true
  }
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "unauthenticated",
    "message": "sign in to continue"
  }
}

POST /api/v1/receive-links

Make a receive link.

Who. Any user with a key that has the write scope. A key with the admin scope includes the others. The key needs a license that includes the REST API. This call can also answer 402 when form fields were sent and this server's license does not include automation.

The reply is the only time the link's address is shown, in url: only a hash of the token is kept, so a lost address means making a new link. The destination must be a folder that already exists and that the owner may write to; the link acts with its owner's rights. Leaving out expiresInDays uses the administrator's default, and null means never, which the administrator has to allow. Custom form fields need the automation feature.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "name": "Rush delivery",
  "message": "The cut is in the folder.",
  "rootId": "k7Qm2sLp9vX4aB1c",
  "spaceId": "k7Qm2sLp9vX4aB1c",
  "path": "projects/rush",
  "expiresInDays": 1,
  "passcode": "example",
  "requireEmail": true
}

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "name": "Rush delivery",
  "message": "The cut is in the folder.",
  "rootId": "k7Qm2sLp9vX4aB1c",
  "rootName": "example",
  "path": "projects/rush",
  "spaceName": "example",
  "spacePath": "projects/rush",
  "hasPasscode": true,
  "requireEmail": true,
  "verifyEmail": true,
  "allowedTypes": "example",
  "oneTime": true,
  "subfolder": true,
  "subfolderTemplate": "example",
  "notifyOwner": true,
  "formFields": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "label": "example",
      "kind": {},
      "required": true,
      "choices": [
        "example"
      ]
    }
  ],
  "state": "active",
  "bytesReceived": 1,
  "submissionCount": 1,
  "ownerId": "k7Qm2sLp9vX4aB1c",
  "ownerEmail": "[email protected]",
  "createdAt": "2026-10-05T18:00:00Z"
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "no name, no folder, or a folder that is not there; a passcode under 6 characters; a limit below 1; a file type that is not one; more than 20 questions; a link that never expires when the administrator requires an expiry; or a `state`, which a new link cannot have"
  }
}

PATCH /api/v1/receive-links/{id}

Change a receive link, or switch it off and on.

Who. Any user with a key that has the write scope. A key with the admin scope includes the others. The key needs a license that includes the REST API. This call can also answer 402 when form fields were sent and this server's license does not include automation.

Send only what changes. Pointing the link at another folder checks the owner's rights there again. state may be active or disabled; to end a link, delete it. A link that has ended cannot be switched back on. The address is not shown again. Custom form fields need the automation feature. Anyone but the owner or an administrator is answered as if the link did not exist.

Parameters.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "name": "Rush delivery",
  "message": "The cut is in the folder.",
  "rootId": "k7Qm2sLp9vX4aB1c",
  "spaceId": "k7Qm2sLp9vX4aB1c",
  "path": "projects/rush",
  "expiresInDays": 1,
  "passcode": "example",
  "requireEmail": true
}

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "name": "Rush delivery",
  "message": "The cut is in the folder.",
  "rootId": "k7Qm2sLp9vX4aB1c",
  "rootName": "example",
  "path": "projects/rush",
  "spaceName": "example",
  "spacePath": "projects/rush",
  "hasPasscode": true,
  "requireEmail": true,
  "verifyEmail": true,
  "allowedTypes": "example",
  "oneTime": true,
  "subfolder": true,
  "subfolderTemplate": "example",
  "notifyOwner": true,
  "formFields": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "label": "example",
      "kind": {},
      "required": true,
      "choices": [
        "example"
      ]
    }
  ],
  "state": "active",
  "bytesReceived": 1,
  "submissionCount": 1,
  "ownerId": "k7Qm2sLp9vX4aB1c",
  "ownerEmail": "[email protected]",
  "createdAt": "2026-10-05T18:00:00Z"
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "a value that is not allowed, `state` set to `ended`, or a folder that is not there"
  }
}

DELETE /api/v1/receive-links/{id}

End a receive link.

Who. Any user with a key that has the delete scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

The link stops taking files at once and cannot be turned back on. The record stays, so what it received still has a name and a folder. Ending a link that has already ended is not an error.

Parameters.

Success. 200.

{
  "id": "k7Qm2sLp9vX4aB1c",
  "name": "Rush delivery",
  "message": "The cut is in the folder.",
  "rootId": "k7Qm2sLp9vX4aB1c",
  "rootName": "example",
  "path": "projects/rush",
  "spaceName": "example",
  "spacePath": "projects/rush",
  "hasPasscode": true,
  "requireEmail": true,
  "verifyEmail": true,
  "allowedTypes": "example",
  "oneTime": true,
  "subfolder": true,
  "subfolderTemplate": "example",
  "notifyOwner": true,
  "formFields": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "label": "example",
      "kind": {},
      "required": true,
      "choices": [
        "example"
      ]
    }
  ],
  "state": "active",
  "bytesReceived": 1,
  "submissionCount": 1,
  "ownerId": "k7Qm2sLp9vX4aB1c",
  "ownerEmail": "[email protected]",
  "createdAt": "2026-10-05T18:00:00Z"
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "not_found",
    "message": "not found"
  }
}

What a link has received

GET /api/v1/receive-links/{id}/submissions

What a receive link has received, newest first.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Up to 500 sends, each with its files, the sender's answers and the folder it was put in. scanState is pending, scanning, clean, blocked or notScanned.

Parameters.

Success. 200.

{
  "submissions": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "linkId": "k7Qm2sLp9vX4aB1c",
      "senderEmail": "[email protected]",
      "senderName": "example",
      "emailVerified": true,
      "formValues": {},
      "folder": "example",
      "bytes": 1048576,
      "fileCount": 1,
      "state": "active",
      "scanState": "example",
      "startedAt": "2026-10-05T18:00:00Z",
      "files": [
        {
          "id": "k7Qm2sLp9vX4aB1c",
          "path": "projects/rush",
          "finalPath": "projects/rush",
          "bytes": 1048576,
          "checksum": "example",
          "scanResult": "example",
          "scanDetail": "example"
        }
      ]
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "not_found",
    "message": "not found"
  }
}

POST /api/v1/receive-links/{id}/submissions/{submission_id}/receipt

Email a sender their receipt again.

Who. Any user with a key that has the write scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Built from what is stored, for a send that is complete or blocked. Unlike the receipt at the end of a send, a failure here is the answer: the caller asked for the mail and is told why it did not go.

Parameters.

Request body. None.

Success. 200.

{
  "sentTo": "example"
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "the sender gave no email address"
  }
}

POST /api/v1/receive-links/{id}/block

Stop one email address sending through a link.

Who. Any user with a key that has the write scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

The address is lowercased and refused from then on. Any send it has open on this link is abandoned, so a sender found halfway through an upload cannot finish. Other links are not affected.

Parameters.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "email": "[email protected]"
}

Success. 200.

{
  "blocked": "example"
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "not an email address"
  }
}

Invitations

GET /api/v1/receive-links/{id}/invites

Who a receive link was emailed to, and whether they opened it.

Who. Any user with a key that has the read scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Parameters.

Success. 200.

{
  "invites": [
    {
      "id": "k7Qm2sLp9vX4aB1c",
      "email": "[email protected]",
      "createdAt": "2026-10-05T18:00:00Z",
      "sentAt": "2026-10-05T18:00:00Z",
      "openedAt": "2026-10-05T18:00:00Z",
      "openCount": 1,
      "revoked": true
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "not_found",
    "message": "not found"
  }
}

POST /api/v1/receive-links/{id}/invites

Email a receive link to people, each with a link of their own.

Who. Any user with a key that has the write scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Each address gets a personal link. Opening it proves the address the way a sign-in link does, so the person is not asked for their address or a code, and what they send is put under their name. The personal token is random, only its hash is kept, and it stops working when the link ends or the invitation is withdrawn. Uses the receive.invite email template; the optional note is kept to its first 1,000 characters. Up to 50 addresses a call and 200 an hour per owner. Each address is answered on its own, so one that is not valid, is blocked on this link, or could not be emailed does not stop the rest.

Parameters.

Request body. JSON.

A field the server does not know is refused with 400.

{
  "emails": [
    "[email protected]"
  ],
  "note": "The cut is in the folder."
}

Success. 200.

{
  "invites": [
    {
      "email": "[email protected]",
      "sent": true,
      "error": "example"
    }
  ]
}

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "bad_request",
    "message": "no addresses, or more than 50"
  }
}

DELETE /api/v1/receive-links/{id}/invites/{invite_id}

Withdraw one person's invitation.

Who. Any user with a key that has the write scope. A key with the admin scope includes the others. The key needs a license that includes the REST API.

Their personal link stops working at once. The receive link itself, and everyone else's invitation, are untouched. Answers 204.

Parameters.

Success. 204.

The reply has no body.

Errors. The body always has the shape in Errors. Match on code.

{
  "error": {
    "code": "not_found",
    "message": "not found"
  }
}

Farwing docs · farwing.io