Files

Upload attachments, then reference them from other resources by file_id. Retrieve a file's metadata and a signed download URL.

Endpoints

POST/files
GET/files/{file_id}

The File object

Attributes

idstringRequired

namestringRequired

content_typestring

size_bytesinteger

download_urlstring · uri

Signed URL for downloading the file, valid for about 1 hour. Present only when the request includes expand=files.

purposestring

sha256string

created_atstring · date-time

expires_atstring · date-timeNullable

Time when the file is deleted if nothing references it by then.

The File object

{
  "id": "file_01J9KQ7X4M",
  "name": "delivery-note-4471.pdf",
  "content_type": "application/pdf",
  "size_bytes": 184213,
  "download_url": "https://storage.zester.co.il/signed/f7K2mQ9vT4xB",
  "purpose": "document_attachment",
  "sha256": "473af64451c51f7dd81a20d9ba6b6977c864a3f2da2691e7b87c77a1ed546e2c",
  "created_at": "2026-09-14T06:11:52+03:00",
  "expires_at": null
}

Upload a file

POST/files

Scopesupplier.documents:write
Scopebuyer.expenses:write

Upload a file as multipart/form-data, up to 25 MB. The response returns a file_id to reference from documents and expenses. Files that are not referenced within 24 hours are deleted.

Request body multipart/form-data

filestring · binaryRequired

purposestring

Possible valuesdocument_attachmentexpense_attachmentproduct_image

Responses

201The stored file.

idstringRequired

namestringRequired

content_typestring

size_bytesinteger

download_urlstring · uri

Signed URL for downloading the file, valid for about 1 hour. Present only when the request includes expand=files.

purposestring

sha256string

created_atstring · date-time

expires_atstring · date-timeNullable

Time when the file is deleted if nothing references it by then.

413The file is larger than 25 MB.

422The request body or query parameters failed validation. See errors[] for each invalid field.

POST /files

curl -X POST "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/files" \
  -H "Authorization: Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…" \
  -F "file=@delivery-note-4471.pdf" \
  -F "purpose=document_attachment"

const res = await fetch("https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/files", {
  method: "POST",
  headers: {
    Authorization: "Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…",
  },
  body: formData, // FormData with "file" and "purpose"
});
const data = await res.json();

import requests

res = requests.post(
    "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/files",
    headers={
        "Authorization": "Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…",
    },
    files={"file": open("delivery-note-4471.pdf", "rb")},
    data={"purpose": "document_attachment"},
)
data = res.json()

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…");
var body = new MultipartFormDataContent {
    { new StreamContent(File.OpenRead("delivery-note-4471.pdf")), "file", "delivery-note-4471.pdf" },
    { new StringContent("document_attachment"), "purpose" },
};
var res = await http.PostAsync("https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/files", body);
var data = await res.Content.ReadAsStringAsync();

Response

{
  "id": "file_01J9KQ7X4M",
  "name": "delivery-note-4471.pdf",
  "content_type": "application/pdf",
  "size_bytes": 184213,
  "download_url": "https://storage.zester.co.il/signed/a3Rt8LpW2nZe",
  "purpose": "document_attachment",
  "sha256": "473af64451c51f7dd81a20d9ba6b6977c864a3f2da2691e7b87c77a1ed546e2c",
  "created_at": "2026-09-14T06:11:52+03:00",
  "expires_at": "2026-09-15T06:11:52+03:00"
}

{
  "type": "https://developers.zester.co.il/errors/file_too_large",
  "title": "File too large",
  "status": 413,
  "code": "file_too_large",
  "detail": "delivery-note-4471.pdf is 31,457,280 bytes. The upload limit is 25 MB (26,214,400 bytes).",
  "request_id": "req_01J9KR5A4G"
}

{
  "type": "https://developers.zester.co.il/errors/validation_error",
  "title": "Validation failed",
  "status": 422,
  "code": "validation_error",
  "detail": "1 field is invalid",
  "request_id": "req_01J9KR5B7H",
  "errors": [
    {
      "field": "purpose",
      "code": "invalid_enum",
      "message": "purpose must be one of document_attachment, expense_attachment, product_image"
    }
  ]
}

Retrieve a file

GET/files/{file_id}

ScopeAny API key

Path parameters

file_idstringRequired

Responses

200The file's metadata, with a signed download URL that is valid for 1 hour.

idstringRequired

namestringRequired

content_typestring

size_bytesinteger

download_urlstring · uri

Signed URL for downloading the file, valid for about 1 hour. Present only when the request includes expand=files.

purposestring

sha256string

created_atstring · date-time

expires_atstring · date-timeNullable

Time when the file is deleted if nothing references it by then.

404The resource does not exist or belongs to another account.

GET /files/{file_id}

curl "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/files/file_01J9KQ7X4M" \
  -H "Authorization: Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…"

const res = await fetch("https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/files/file_01J9KQ7X4M", {
  method: "GET",
  headers: {
    Authorization: "Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…",
  },
});
const data = await res.json();

import requests

res = requests.get(
    "https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/files/file_01J9KQ7X4M",
    headers={
        "Authorization": "Bearer zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…",
    },
)
data = res.json()

using var http = new HttpClient();
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", "zk_test_XXXXXXXX_…zk_live_XXXXXXXX_…");
var res = await http.GetAsync("https://sandbox-api.zester.co.il/v2https://api.zester.co.il/v2/files/file_01J9KQ7X4M");
var data = await res.Content.ReadAsStringAsync();

Response

{
  "id": "file_01J9KQ7X4M",
  "name": "delivery-note-4471.pdf",
  "content_type": "application/pdf",
  "size_bytes": 184213,
  "download_url": "https://storage.zester.co.il/signed/f7K2mQ9vT4xB",
  "purpose": "document_attachment",
  "sha256": "473af64451c51f7dd81a20d9ba6b6977c864a3f2da2691e7b87c77a1ed546e2c",
  "created_at": "2026-09-14T06:11:52+03:00",
  "expires_at": null
}

{
  "type": "https://developers.zester.co.il/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "File file_01J9KQ7X4M does not exist, belongs to another account, or was deleted because it was not referenced within 24 hours.",
  "request_id": "req_01J9KR5C9J"
}