Skip to content
Space Invoices Documentation

Files

Files

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

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

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. Optional - defaults to the first created entity if not provided.

Body parameters

filestring<binary>required

File to upload

curl -X POST "https://eu.spaceinvoices.com/files" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID" \
  -F "file=@/path/to/image.png"
Response
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": "http://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png",
  "secureUrl": "https://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png",
  "publicId": "si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011",
  "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. Optional - defaults to the first created entity if not provided.

Query parameters

limitintegeroptional

Number of results per request.

Default: 10

next_cursorstringoptional

Cursor to fetch the next page of results. Use the value from pagination.next_cursor in the previous response.

prev_cursorstringoptional

Cursor to fetch the previous page of results. 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)

curl "https://eu.spaceinvoices.com/files" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID"
Response

Returns

dataarray
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": "http://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png",
      "secureUrl": "https://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png",
      "publicId": "si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011",
      "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. Optional - defaults to the first created entity if not provided.

Path parameters

idstring<resource-id>required

Unique resource identifier

curl "https://eu.spaceinvoices.com/files/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID"
Response
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": "http://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png",
  "secureUrl": "https://res.cloudinary.com/demo/image/upload/v1234567890/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011.png",
  "publicId": "si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011",
  "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. Optional - defaults to the first created entity if not provided.

Path parameters

idstring<resource-id>required

Unique resource identifier

curl -X DELETE "https://eu.spaceinvoices.com/files/{id}" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "x-entity-id: YOUR_ENTITY_ID"