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
delivery_note_idstringnullable
expense_idstringnullable
categorystring
urlstring
formatstring
widthintegernullable
heightintegernullable
bytesinteger
filenamestringnullable
mime_typestring
metadatastringnullable
cache_keystringnullable
created_atstring<date-time>
updated_atstring<date-time>
Examplejson
{
  "id": "file_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_507f1f77bcf86cd799439011",
  "invoice_id": null,
  "estimate_id": null,
  "credit_note_id": null,
  "advance_invoice_id": null,
  "delivery_note_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 logo, signature, or attachment with explicit file metadata. Set category to logo for logo uploads. The x-entity-id header selects the entity, and business_unit_id can assign a logo to a business unit.
Files are automatically optimized and stored in entity-specific folders. Entity-level logos and signatures replace the existing file in the same category, 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

categorystringrequired

File category (logo, signature, or attachment)

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

Other parameters
import SpaceInvoices from '@spaceinvoices/js-sdk/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"
}, { entity_id: 'YOUR_ENTITY_ID' });

console.log(response);
Response

Returns

idstring
Other parameters
entity_idstring
business_unit_idstringnullable
invoice_idstringnullable
estimate_idstringnullable
credit_note_idstringnullable
advance_invoice_idstringnullable
delivery_note_idstringnullable
expense_idstringnullable
categorystring
urlstring
formatstring
widthintegernullable
heightintegernullable
bytesinteger
filenamestringnullable
mime_typestring
metadatastringnullable
cache_keystringnullable
created_atstring<date-time>
updated_atstring<date-time>
json
{
  "id": "file_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_507f1f77bcf86cd799439011",
  "invoice_id": null,
  "estimate_id": null,
  "credit_note_id": null,
  "advance_invoice_id": null,
  "delivery_note_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"

document_idstringoptional

Filter by issued document ID (attachments of an invoice, estimate, credit note, advance invoice or delivery note)

account_payable_idstringoptional

Deprecated alias for document_id.

business_unit_idstringoptional

Filter by business unit ID

expense_idstringoptional

Filter by expense ID (for attachments)

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

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

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,
      "delivery_note_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. Prefix depends on the resource, for example inv_, cus_, or ent_.

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

const response = await sdk.files.get('fil_6595a27b5d35015c3ef0c3fd', {
  entity_id: "YOUR_ENTITY_ID"
});

console.log(response);
Response

Returns

idstring
Other parameters
entity_idstring
business_unit_idstringnullable
invoice_idstringnullable
estimate_idstringnullable
credit_note_idstringnullable
advance_invoice_idstringnullable
delivery_note_idstringnullable
expense_idstringnullable
categorystring
urlstring
formatstring
widthintegernullable
heightintegernullable
bytesinteger
filenamestringnullable
mime_typestring
metadatastringnullable
cache_keystringnullable
created_atstring<date-time>
updated_atstring<date-time>
json
{
  "id": "file_6595a27b5d35015c3ef0c3fd",
  "entity_id": "ent_507f1f77bcf86cd799439011",
  "invoice_id": null,
  "estimate_id": null,
  "credit_note_id": null,
  "advance_invoice_id": null,
  "delivery_note_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. Prefix depends on the resource, for example inv_, cus_, or ent_.

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

const sdk = new SpaceInvoices('YOUR_API_KEY');

await sdk.files.delete('fil_6595a27b5d35015c3ef0c3fd', {
  entity_id: "YOUR_ENTITY_ID"
});

console.log('Deleted successfully');