Register a document by its hash: an invoice, a receipt, a contract, anything the books rest on
const url = 'https://example.com/v1/entities/example/documents';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"sha256":"example","filename":"example","media_type":"example","size_bytes":1,"blob_path":"","external_ref":"example","reason":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/v1/entities/example/documents \ --header 'Content-Type: application/json' \ --data '{ "sha256": "example", "filename": "example", "media_type": "example", "size_bytes": 1, "blob_path": "", "external_ref": "example", "reason": "example" }'Register a document; 201 when this call registered it, 200 when the same bytes were already here.
A document is identified by its content, so two entries resting on one invoice will register it twice in the
ordinary course of events. That is not refused, and the caller does not need to look first. The one
contradiction that is refused is a different size_bytes for the same hash.
Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The entity this path is relative to
The entity this path is relative to
Request Bodyrequired
Section titled “Request Bodyrequired”A document to register: the bytes’ hash, what the file is called, and where it is kept.
The ledger records this and does not fetch it, the same contract as POST /statements. Identity is
sha256 alone, so registering the same file twice returns the existing row rather than creating a second
one or refusing.
object
SHA-256 of the document, 64 lowercase hex characters; its identity here
Size of the document in bytes
Where the bytes are kept, when this service keeps them
Why it is being registered; kept in the record
Responses
Section titled “Responses”OK
object
A registered document, read back.
links.content is present only when the bytes are here to be served. An external document has
nothing at that address, and the link would only give the interface a button that always fails.
object
SHA-256 of the registered bytes, and the document’s identity
Stored | external
How many records cite this document
object
False when this call found the document already registered
One place a document is cited: which record, where in the file, and what it says.
object
Entry | statement
Example generated
{ "entity_id": "example", "legal_name": "example", "base_currency": "example", "snapshot_seq": 1, "document": { "sha256": "example", "filename": "example", "media_type": "example", "size_bytes": 1, "storage": "example", "external_ref": "example", "id": "example", "filing_count": 1, "created_at": "example", "created_by": "example", "links": { "additionalProperty": "example" } }, "created": true, "filings": [ { "evidence_id": "example", "subject_kind": "example", "subject_id": "example", "page": 1, "locator": "example", "caption": "example", "created_at": "example", "created_by": "example" } ]}Successful Response
object
A registered document, read back.
links.content is present only when the bytes are here to be served. An external document has
nothing at that address, and the link would only give the interface a button that always fails.
object
SHA-256 of the registered bytes, and the document’s identity
Stored | external
How many records cite this document
object
False when this call found the document already registered
One place a document is cited: which record, where in the file, and what it says.
object
Entry | statement
Example generated
{ "entity_id": "example", "legal_name": "example", "base_currency": "example", "snapshot_seq": 1, "document": { "sha256": "example", "filename": "example", "media_type": "example", "size_bytes": 1, "storage": "example", "external_ref": "example", "id": "example", "filing_count": 1, "created_at": "example", "created_by": "example", "links": { "additionalProperty": "example" } }, "created": true, "filings": [ { "evidence_id": "example", "subject_kind": "example", "subject_id": "example", "page": 1, "locator": "example", "caption": "example", "created_at": "example", "created_by": "example" } ]}Bad Request
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Unauthorized
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Forbidden
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Not Found
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Conflict
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Precondition Failed
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Unprocessable Content
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Internal Server Error
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}Service Unavailable
object
Example generated
{ "error": { "code": "example", "message": "example", "retryable": true, "details": [ {} ], "request_id": "example", "next_action": {} }}