Generate attachment upload URL

POST

https://api.light.inc/v1/attachments/upload-url

Generates a secure upload URL for attachment files

Note

Step one of three; see Files. The URL is valid for five minutes. When you PUT the bytes to it, set Content-Type to the contentType you asked for and send every entry of the returned metadata as a request header — they are signed into the URL and the upload is rejected without them. Then register the file with POST /v1/attachments, passing the returned key as documentKey.

fileName must be unique per resourceId; reusing one fails with ATTACHMENT_FILE_NAME_FOR_RESOURCE_ALREADY_EXISTS. contentType must be one of the PDF, image (image/*), text or Office document types; anything else fails with UNSUPPORTED_FILE_MIME_TYPE. The key is generated by Light; you cannot choose it. There is no resourceType in this API: resourceId is the id of the record (an invoice, a purchase order, ...) and it is not checked against anything, so a typo produces an attachment nothing will ever show.

Authorization

Send one of these on every request. See Authentication for how to get credentials.

API key
Basic authentication header of the form Basic <api_key>, where <api_key> is your api key.
Bearer token

Request body

application/json;charset=UTF-8

resourceId string · uuid
fileName string
contentType string

Response

uploadUrl string · url
key string
Note
Pass this as documentKey to POST /v1/attachments once the upload is done.
metadata object
Note
Send every entry as a request header on the PUT to uploadUrl, exactly as returned. They are signed into the URL; the upload is rejected without them.

cURL

curl -X POST "https://api.light.inc/v1/attachments/upload-url" \
  -H "Authorization: Basic YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "resourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "fileName": "string",
  "contentType": "string"
}'

JavaScript

const res = await fetch("https://api.light.inc/v1/attachments/upload-url", {
  method: "POST",
  headers: {
    Authorization: `Basic ${process.env.LIGHT_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "resourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "fileName": "string",
    "contentType": "string"
  }),
});
const data = await res.json();

Python

import os, requests

res = requests.post(
    "https://api.light.inc/v1/attachments/upload-url",
    headers={
        "Authorization": f"Basic {os.environ['LIGHT_API_KEY']}",
    },
    json={
        "resourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "fileName": "string",
        "contentType": "string"
    },
)
data = res.json()

Example requestGenerated

{
  "resourceId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "fileName": "string",
  "contentType": "string"
}

Generated from the schema: shapes and types are real, values are placeholders, and fields that exclude each other are all shown. Do not send it unchanged.

Example responseGenerated

{
  "uploadUrl": "https://example.com",
  "key": "string",
  "metadata": null
}

Generated from the schema: shapes and types are real, values are placeholders.