> ## Documentation Index
> Fetch the complete documentation index at: https://docs.invopop.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create an entry with ID
> Create a new silo entry with the given UUID.
## New Documents
The fastest way to upload data to Invopop is by creating an entry with the data property containing the GOBL JSON of either a pre-built [Envelope](https://docs.gobl.org/draft-0/envelope) or a partial document like an [Invoice](https://docs.gobl.org/draft-0/bill/invoice) or [Party](https://docs.gobl.org/draft-0/org/party).
The `key` property can be used to ensure idempotency, preventing the creation of duplicate entries with the same key within the workspace.
A `409 Conflict` response will be provided if either the entry ID or key have been used in an existing document.
```json Invoice Body Example theme={"system"}
{
"data": {
"$schema": "https://gobl.org/draft-0/bill/invoice",
"series": "DEMO",
"code": "001",
"currency": "USD",
"supplier": {
"name": "Provide One Inc.",
"tax_id": {
"country": "US"
},
"addresses": [
{
"num": "16",
"street": "Jessie Street",
"locality": "San Francisco",
"region": "CA",
"code": "94105",
"country": "US"
}
],
"emails": [
{
"addr": "billing@provideone.com"
}
]
},
"customer": {
"name": "Sample Consumer",
"emails": [
{
"addr": "email@sample.com"
}
]
},
"lines": [
{
"quantity": "20",
"item": {
"name": "Development services",
"price": "90.00",
"unit": "h"
},
"discounts": [
{
"percent": "10%",
"reason": "Special discount"
}
],
"taxes": [
{
"cat": "ST",
"percent": "8.5%"
}
]
}
]
}
}
```
Any data uploaded to the Invopop Silo will first be normalized, calculated, and then validated to check for any errors.
Invopop will attempt to automatically determine the folder in which to store the document based on the schema, but you can override this by including the folder field in the request.
If there are any validation issues with the uploaded data, the service will respond with an error message including a `key` and `message`. Additionally, the `fields` property may include a nested structure to help identify the specific property with a validation fault.
Use UUID versions 1 or 7 for documents with a specific lifespan, such as
invoices or payment receipts. For long-lived data, like parties or items, use
versions 3, 4, or 5. The rules for UUID versions are enforced by specific
folder configurations.
## Creating Entries from Previous Documents
You can create new entries based on a previous entry by using the previous\_id field. This allows you to provide patch data instead of a full new document by setting the patch type in the content\_type field to one of the following:
* application/json-patch+json - for JSON Patch (RFC 6902)
* application/merge-patch+json - for JSON Merge Patch (RFC 7396)
Additionally, the previous\_id field can be used to create corrective documents by including corrective option data in the correct field. For more details, refer to the GOBL documentation on correction options.
## OpenAPI
````yaml PUT /silo/v1/entries/{id}
openapi: 3.0.0
info:
contact:
email: dev@invopop.com
name: Invopop Developers
description: >-
Store and manage GOBL documents along with their attachments in "Silo
Entries".
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
title: Silo Service API
version: 1.0.0
servers:
- description: production
url: https://api.invopop.com
security:
- authToken: []
paths:
/silo/v1/entries/{id}:
put:
description: Create a new silo entry with the given UUID.
parameters:
- description: UUID of the silo entry to create.
in: path
name: id
required: true
schema:
description: UUID of the silo entry to create.
example: 347c5b04-cde2-11ed-afa1-0242ac120002
title: ID
type: string
requestBody:
content:
application/json:
schema:
properties:
allow_invalid:
description: >-
When true, the envelope's contents are allowed to be
invalid.
example: true
title: Allow Invalid
type: boolean
content_type:
description: The content type of the data being uploaded.
example: application/json
title: Content Type
type: string
correct:
description: JSON object containing the GOBL correction option data.
example:
credit: true
title: Correct
type: object
data:
description: >-
Data contents to upload which may either be a GOBL Envelope
or Object. Any partial data will be calculated and validated
automatically.
title: Data
type: object
folder:
description: >-
In which folder the entry should be associated, leave empty
to use the automatic rules.
title: Folder
type: string
key:
description: >-
Key used to identify the entry idempotently within a
workspace.
example: invoice-101
title: Key
type: string
previous_id:
description: The UUID of the previous silo entry to copy.
format: uuid
title: Previous ID
type: string
sign:
description: When true, the GOBL envelope will be signed automatically.
example: false
title: Sign
type: boolean
type: object
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/SiloEntry'
description: OK
components:
schemas:
SiloEntry:
properties:
attachments:
description: List of files for this entry.
items:
$ref: '#/components/schemas/SiloFile'
title: Attachments
type: array
context:
description: >-
When entry provided within a related query, this is the context
within the document.
example: line.item
title: Context
type: string
created_at:
description: The date and time the silo entry was created.
example: '2018-01-01T00:00:00.000Z'
title: Created At
type: string
data:
description: JSON envelope contents when specifically requested.
title: Data
type: object
digest:
$ref: '#/components/schemas/DsigDigest'
doc_schema:
description: Schema URL for the envelope's payload.
example: https://gobl.org/draft-0/bill/invoice
title: Object Schema
type: string
draft:
description: Deprecated. When true, indicates that the envelope is not signed.
example: true
title: Draft
type: boolean
env_schema:
description: Schema URL for the envelope.
example: https://gobl.org/draft-0/envelope
title: Envelope Schema
type: string
faults:
description: >-
List of faults that occurred during the processing of the job
associated with the last state.
items:
$ref: '#/components/schemas/SiloFault'
title: Faults
type: array
folder:
description: Key for the folder where the entry is located.
example: sales
title: Folder
type: string
id:
description: UUID of the silo entry.
example: 347c5b04-cde2-11ed-afa1-0242ac120002
title: ID
type: string
invalid:
description: >-
When true, the envelope's contents are invalid and need to be
reviewed.
example: true
title: Invalid
type: boolean
key:
description: Key used to identify the entry idempotently within a workspace.
example: invoice-101
title: Key
type: string
meta:
description: Additional meta fields associated with the entry.
items:
$ref: '#/components/schemas/SiloMeta'
title: Meta
type: array
signed:
description: When true, the envelope has been signed and should not be modified.
example: true
title: Signed
type: boolean
snippet:
description: JSON object containing a snippet of the document.
example:
title: Sample Title
title: Snippet
type: object
state:
description: Current state of the silo entry if not a draft.
example: sent
title: State
type: string
tags:
description: Copy of tags stored in the envelope header.
items:
type: string
title: Tags
type: array
updated_at:
description: The date and time the silo entry was last updated.
example: '2018-01-01T00:00:00.000Z'
title: Updated At
type: string
type: object
SiloFile:
properties:
category:
description: Category of the file.
example: version
title: Category
type: string
created_at:
description: The date and time this file was created.
example: '2018-01-01T00:00:00.000Z'
title: Created At
type: string
desc:
description: Description of the file.
example: Invoice for January 2021.
title: Description
type: string
embeddable:
description: When true, the file can be embedded inside another file, like a PDF.
example: true
title: Embeddable
type: boolean
entry_id:
description: The UUID of the entry this file belongs to.
example: 347c5b04-cde2-11ed-afa1-0242ac120002
title: Entry ID
type: string
hash:
description: SHA256 hash of the file.
example: a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
title: Hash
type: string
id:
description: The UUID that identifies the file in the entry.
title: ID
type: string
key:
description: >-
Key used to identify the file by the service or app that generated
it.
example: pdf
title: Key
type: string
meta:
additionalProperties:
type: string
description: Any additional meta data about the file.
title: Meta
type: object
mime:
description: MIME type of the file.
example: application/pdf
title: MIME
type: string
name:
description: Name of the file.
example: invoice.pdf
title: Name
type: string
previous:
description: Set of previous versions of the file.
items:
$ref: '#/components/schemas/SiloFileVersion'
title: Previous
type: array
private:
description: When true, the file will not have a public link.
title: Private
type: boolean
size:
description: Size of the file in bytes.
example: 12345
title: Size
type: integer
stored:
description: >-
When true, indicates that the file's contents have been uploaded
successfully.
example: true
title: Stored
type: boolean
url:
description: URL where the file's contents can be downloaded.
title: Public URL
type: string
type: object
DsigDigest:
properties:
alg:
type: string
val:
type: string
type: object
SiloFault:
properties:
code:
description: >-
Code assigned by the provider that may provide additional
information about the fault.
title: Code
type: string
message:
description: >-
Message assigned by the provider that may provide additional
information about the fault.
title: Message
type: string
paths:
description: JSON Paths to the properties affected by the fault.
items:
type: string
title: Paths
type: array
provider:
description: ID of the provider that generated the fault.
example: pdf
title: Provider
type: string
type: object
SiloMeta:
properties:
created_at:
description: Timestamp of when the row was created.
example: '2018-01-01T00:00:00.000Z'
title: Created At
type: string
entry_id:
description: ID of the entry this meta row belongs to
example: 347c5b04-cde2-11ed-afa1-0242ac120002
title: Entry ID
type: string
id:
description: Compound ID of the meta row.
example: 347c5b04-cde2-11ed-afa1-0242ac120002:source:key
title: ID
type: string
indexed:
description: When true, the meta entry is indexed for search.
example: true
title: Indexed
type: boolean
key:
description: Key used to identify the meta entry by the source.
example: service-id
title: Key
type: string
link_scope:
description: Describes the context in which the link should be made available.
example: public
title: Link Scope
type: string
link_url:
description: >-
URL associated with the meta row that may be used to perform
additional actions or view more details.
example: https://example.com/info
title: Link URL
type: string
owned:
description: When true, the meta entry is indexed by owner ID.
example: true
title: Owned
type: boolean
owner_id:
description: >-
UUID of the owner of the silo entry, typically a workspace ID.
Included for reference when the authentication token does not
already include the owner such as for lookups by reference.
title: Owner ID
type: string
ref:
description: >-
Indexable value used to locate the meta entry if a silo entry ID is
not available.
title: Reference
type: string
secure:
description: >-
When true, the meta entry is never included in lists and needs to be
specifically requested.
example: true
title: Secure
type: boolean
shared:
description: When true, the meta entry may be shared with other applications.
example: true
title: Shared
type: boolean
src:
description: The service or source that create this meta entry.
example: source
title: Source
type: string
updated_at:
description: Timestamp of when the row was last updated.
example: '2018-01-01T00:00:00.000Z'
title: Updated At
type: string
value:
description: The JSON data stored with the meta row.
example:
key: value
title: Value
type: object
type: object
SiloFileVersion:
properties:
created_at:
description: The date and time this file was created.
example: '2018-01-01T00:00:00.000Z'
title: Created At
type: string
hash:
description: The SHA256 of the file's contents.
title: Hash
type: string
id:
description: The UUID that identifies the file when it was originally uploaded.
title: ID
type: string
size:
description: Size of the file.
title: Size
type: integer
type: object
securitySchemes:
authToken:
bearerFormat: JWT
description: >-
Use the `Bearer` scheme with a valid JWT token to authenticate requests.
Example: `Authorization: Bearer `
scheme: bearer
type: http
````