Skip to content
Space Invoices Documentation

Files

Files

File metadata management.
Upload and manage files (logos, signatures, attachments) associated with entities and documents.

Endpoints
IntroductionPOST/filesGET/filesGET/files/{id}DELETE/files/{id}

The File object

object

Attributes

idstring
Other attributes
entity_idstring
business_unit_idstringnullable
invoice_idstringnullable
estimate_idstringnullable
credit_note_idstringnullable
advance_invoice_idstringnullable
expense_idstringnullable
categorystring
urlstring
secureUrlstring
publicIdstring
formatstring
widthintegernullable
heightintegernullable
bytesinteger
filenamestringnullable
mime_typestring
metadatastringnullable
cache_keystringnullable
created_atstring<date-time>
updated_atstring<date-time>
secure_urlstring
public_idstring
Examplejson
{
  "id": "file_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_507f1f77bcf86cd799439011",
  "invoice_id": null,
  "estimate_id": null,
  "credit_note_id": null,
  "advance_invoice_id": null,
  "category": "logo",
  "url": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "secure_url": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "public_id": "si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "secureUrl": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "publicId": "si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "format": "png",
  "width": 576,
  "height": 192,
  "bytes": 45678,
  "filename": "company-logo.png",
  "mime_type": "image/png",
  "metadata": {},
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

Upload a file

POST/files

Upload a file (logo, signature, or attachment) to cloud storage.
Files are automatically optimized and stored in entity-specific folders.
Logos and signatures are entity-level (one per entity), while attachments can be associated with specific documents.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Body parameters

filestring<binary>required

File to upload

import SpaceInvoices from '@spaceinvoices/js-sdk';
import fs from 'fs';

const sdk = new SpaceInvoices('YOUR_API_KEY');

// Read file as Buffer
const fileBuffer = fs.readFileSync('/path/to/image.png');
const file = new File([fileBuffer], 'image.png', { type: 'image/png' });

const response = await sdk.files.uploadFile({
  file,
  category: "logo",
  account_payable_id: "string",
  business_unit_id: "string",
  expense_id: "string"
});

console.log(response);
Response

Returns

idstring
Other parameters
entity_idstring
business_unit_idstringnullable
invoice_idstringnullable
estimate_idstringnullable
credit_note_idstringnullable
advance_invoice_idstringnullable
expense_idstringnullable
categorystring
urlstring
secureUrlstring
publicIdstring
formatstring
widthintegernullable
heightintegernullable
bytesinteger
filenamestringnullable
mime_typestring
metadatastringnullable
cache_keystringnullable
created_atstring<date-time>
updated_atstring<date-time>
secure_urlstring
public_idstring
json
{
  "id": "file_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_507f1f77bcf86cd799439011",
  "invoice_id": null,
  "estimate_id": null,
  "credit_note_id": null,
  "advance_invoice_id": null,
  "category": "logo",
  "url": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "secure_url": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "public_id": "si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "secureUrl": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "publicId": "si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "format": "png",
  "width": 576,
  "height": 192,
  "bytes": 45678,
  "filename": "company-logo.png",
  "mime_type": "image/png",
  "metadata": {},
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}
Example:

List all files

GET/files

Retrieve a paginated list of files for an entity.
Supports filtering by category and optional document association.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Query parameters

limitintegeroptional

Number of results per request.

Default: 10

next_cursorstringoptional

Opaque cursor to fetch the next page of results. Reuse only with the same effective ordering. Use the value from pagination.next_cursor in the previous response.

prev_cursorstringoptional

Opaque cursor to fetch the previous page of results. Reuse only with the same effective ordering. Use the value from pagination.prev_cursor in the previous response.

include_total_countbooleanoptional

Whether to include the total count of items in pagination.total.
Default is true.
When false, pagination.total returns -1 for better performance.

categorystringoptional

Filter by file category

Possible values: "logo", "signature", "attachment"

account_payable_idstringoptional

Filter by account payable ID (for attachments)

business_unit_idstringoptional

Filter by business unit ID

expense_idstringoptional

Filter by expense ID (for attachments)

import SpaceInvoices from '@spaceinvoices/js-sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.files.list({ limit: 20 });

console.log(response);
Response

Returns

dataarray of objects
paginationobject

Pagination metadata including cursors and result counts

json
{
  "data": [
    {
      "id": "file_6595a27b5d35015c3ef0c3fd",
      "entity_id": "ent_507f1f77bcf86cd799439011",
      "invoice_id": null,
      "estimate_id": null,
      "credit_note_id": null,
      "advance_invoice_id": null,
      "category": "logo",
      "url": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
      "secure_url": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
      "public_id": "si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
      "secureUrl": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
      "publicId": "si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
      "format": "png",
      "width": 576,
      "height": 192,
      "bytes": 45678,
      "filename": "company-logo.png",
      "mime_type": "image/png",
      "metadata": {},
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z"
    }
  ],
  "pagination": {
    "total": 1,
    "next_cursor": null,
    "prev_cursor": null,
    "has_more": false
  }
}

Get file metadata by ID

GET/files/{id}

Retrieve file metadata by its unique identifier.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Unique resource identifier

import SpaceInvoices from '@spaceinvoices/js-sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.files.get("inv_6595a27b5d35015c3ef0c3fd");

console.log(response);
Response

Returns

idstring
Other parameters
entity_idstring
business_unit_idstringnullable
invoice_idstringnullable
estimate_idstringnullable
credit_note_idstringnullable
advance_invoice_idstringnullable
expense_idstringnullable
categorystring
urlstring
secureUrlstring
publicIdstring
formatstring
widthintegernullable
heightintegernullable
bytesinteger
filenamestringnullable
mime_typestring
metadatastringnullable
cache_keystringnullable
created_atstring<date-time>
updated_atstring<date-time>
secure_urlstring
public_idstring
json
{
  "id": "file_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_507f1f77bcf86cd799439011",
  "invoice_id": null,
  "estimate_id": null,
  "credit_note_id": null,
  "advance_invoice_id": null,
  "category": "logo",
  "url": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "secure_url": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "public_id": "si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "secureUrl": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "publicId": "si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "format": "png",
  "width": 576,
  "height": 192,
  "bytes": 45678,
  "filename": "company-logo.png",
  "mime_type": "image/png",
  "metadata": {},
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}
Example:

Delete a file

DELETE/files/{id}

Delete a file and its metadata.
The file is removed from cloud storage and the database.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Path parameters

idstring<resource-id>required

Unique resource identifier

import SpaceInvoices from '@spaceinvoices/js-sdk';

const sdk = new SpaceInvoices('YOUR_API_KEY');

await sdk.files.delete("inv_6595a27b5d35015c3ef0c3fd");

console.log('Deleted successfully');