Send files

POST /upload accepts a file from the authenticated user. You can send the file as multipart/form-data or as the binary request body; the optional metadata is the same in both formats.

Choose the format

Format	When to use	Metadata
`multipart/form-data`	Forms and most HTTP libraries.	Form fields
`application/octet-stream`	Streaming uploads or clients that do not build multipart requests.	`X-STCPDIRECTLINK-*` headers

Optional metadata

Whether you can use each metadata item depends on the operations enabled in the environment.

Multipart	Binary body (header)	Description
`file` (required)	`X-STCPDIRECTLINK-FILENAME` (required)	File sent (multipart) or file name (binary body).
`d`	`X-STCPDIRECTLINK-DESTINATION`	Recipient or destination user.
`m`	`X-STCPDIRECTLINK-EMAIL`	Email associated with the transfer notification.
`c`	`X-STCPDIRECTLINK-MOBILE`	Mobile phone associated with the transfer notification.
`h`	`X-STCPDIRECTLINK-HASH`	Expected SHA-256 hash of the file, in hexadecimal. The value is returned in the `X-STCPDIRECTLINK-HASH` header of the download.
`n`	`X-STCPDIRECTLINK-EMAIL-FROM`	Sender identification or email.
`i`	`X-STCPDIRECTLINK-INFO`	Additional information or tags for the transfer.

Send the file

Minimal upload:

curl -i \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -F 'file=@./document.pdf' \
  "$API_BASE/upload"

With recipient and notification:

curl -i \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -F 'file=@./document.pdf' \
  -F 'd=RECIPIENT' \
  -F 'm=recipient@example.com' \
  -F 'c=5511999999999' \
  -F "h=$(sha256sum ./document.pdf | cut -d' ' -f1)" \
  -F 'i=external-reference' \
  "$API_BASE/upload"

curl -i \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  -H 'Content-Type: application/octet-stream' \
  -H 'X-STCPDIRECTLINK-FILENAME: document.pdf' \
  -H 'X-STCPDIRECTLINK-DESTINATION: RECIPIENT' \
  --data-binary '@./document.pdf' \
  "$API_BASE/upload"

Read the response

The 200 response returns the transfer data:

{
  "status": 0,
  "description": "<description returned by the API>",
  "apiver": "v2 (9.0.1)",
  "user": "USER",
  "id": "<file identifier>",
  "destination": "RECIPIENT",
  "length": 12345,
  "linkURL": [],
  "time": "<date and time>"
}

Field	Description
`id`	Name or identifier of the received file.
`destination`	Transfer destination.
`length`	Size received, in bytes.
`linkURL`	Notification links generated for the transfer, if any.

The actual values depend on the environment; use the response you receive as the reference.

Tip

Compare length with the size of the local file and provide the hash in the upload to detect incomplete transfers.

Full contract in Reference: Transfers.

Receive files