Documentation

1. List Documents

Retrieve a list of your documents, with options to filter by status and paginate the results.

Endpoint: GET /api/proof/document
Description: This endpoint fetches a batch of documents based on their status. You can filter documents by their processing status and paginate through the results.

Headers

x-access-token (string, required): Your API token.

Query Parameters

status (string, required): Filter documents by status. Possible values:
- confirmed
- pending
- pending_stamp
page (number, required): The page number to retrieve (starting from 0).
limit (number, required): The number of results per page.

Response

200 OK

The request was successful, and a list of documents is returned.

{
  "ok": true,
  "data": {
    "totalPages": 1,
    "totalCount": 1,
    "documents": [
      {
        "id": 5198978,
        "name": "source-simpleproof.png",
        "extension": "png",
        "storage_kb": "6.1",
        "creation_date": "2024-03-27T18:29:17.684Z",
        "document_hash": "870c8bcd4278ddfc1f8bd5769190b5513f05bed50f32b52f711ffbdf4f544d45",
        "prefix": "lnvtest/simpleproof-kpaowlua53vp1/",
        "blockchain": {},
        "document_status": "COMPLETE"
      }
    ]
  }
}

400 Bad Request

The request was invalid or cannot be otherwise served.
```
{
  "ok": false,
  "msg": "Something went wrong."
}
```

2. Submit Hashes for Timestamping

Send one or more SHA256 hashes to be timestamped on the Bitcoin blockchain. This endpoint supports up to 25 hashes per request.

Endpoint: POST /api/proof/timestamp/hashes
Description: Use this endpoint to timestamp an array of hashes on the Bitcoin blockchain. The hashes must be in hexadecimal format and 64 characters long.

Headers

x-access-token (string, required): Your API token.

Request Body

Content-Type: application/json

Schema:

{
	"callback_url": "https://example.com/callback",
	"hashes": [
    "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb",
    "1a8c3743df10869051e093753221651d69e9f556345492398daf0a944f4fe4a4",
    "149d5f7d5d3622f0495ab57f0646405946bf47f14831a7c9b1a69c41948de000"
  ]
}

hashes (array of strings, required): An array of up to 25 SHA256 hexadecimal hashes.
callback_url (string, optional): Valid URL to receive a POST request with the result in JSON format.

Response

200 OK

The hashes were successfully submitted for timestamping.

{
  "ok": true,
  "files": [
    "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb",
    "1a8c3743df10869051e093753221651d69e9f556345492398daf0a944f4fe4a4",
    "149d5f7d5d3622f0495ab57f0646405946bf47f14831a7c9b1a69c41948de000"
  ]
}

400 Bad Request

The request was invalid or violated the endpoint's constraints (e.g., exceeding the hash limit).
```
{
  "ok": false,
  "msg": "A maximum of 25 hashes per request is allowed."
}
```
500 Internal Server Error

The server encountered an unexpected issue while processing the request.
```
{
  "ok": false,
  "msg": "Internal server error. Please try again later."
}
```

Example Request (Using `curl`)

curl -X POST https://app.simpleproof.com/api/proof/timestamp/hashes \
-H "Content-Type: application/json" \
-H "x-access-token: YOUR_TOKEN" \
-d '{
	"callback_url": "https://example.com/callback",
	"hashes": [
    "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb",
    "1a8c3743df10869051e093753221651d69e9f556345492398daf0a944f4fe4a4",
    "149d5f7d5d3622f0495ab57f0646405946bf47f14831a7c9b1a69c41948de000"
  ]
}'

Notes

Each hash MUST TO BE exactly 64 characters long and in SHA256 hexadecimal hashes format.
If you need to timestamp more than 25 hashes, divide them into multiple requests.
Timestamps are recorded on the Bitcoin blockchain, ensuring immutable verification.

3. Upload Large Files

Allows you to upload large files to SimpleProof for verification and timestamping on the Bitcoin blockchain.

Endpoint: POST /api/proof/file
Description: This endpoint enables you to upload large files for verification. It uses multipart/form-data to efficiently handle the uploading of large files.

Headers

x-access-token (string, required): Your API token.

Request Body

Content-Type: multipart/form-data
Form Parameters:
- files (files, required): The file or files you wish to upload. It should be provided in binary format.
- callback_url (string, optional): Valid URL to receive a POST request with the result in JSON format.

Responses

200 OK

The request was successful, and the file was received and processed correctly.
```
{
  "ok": true,
  "files":[
    "FILE_HASH"
  ]
}
```
- ok (boolean): Indicates if the operation was successful.
- hash (string): The SHA-256 hash of the uploaded file.
400 Bad Request

The request was invalid or there was an error processing the file.
```
{
  "ok": false,
  "msg": "Something went wrong."
}
```
- ok (boolean): Indicates that the operation failed.
- msg (string): Descriptive error message.

4. Verify a Document

Check if a document's hash has been confirmed on the Bitcoin blockchain.

Endpoint: POST /proof/verification
Description: This endpoint verifies if a provided hash corresponds to a document that has been confirmed on the blockchain.

Headers

x-access-token (string, required): Your API token.

Request Body

Content-Type: application/json
Schema:
```
{
  "hash": "5ce32a6ce7fa488d055c2eb5e19bf2f5de7454af28bb951b96ad6d833be873c2"
}
```
- hash (string, required): The hexadecimal hash string of the file you want to verify.

Response

200 OK

The specified hash was found, and its verification status is returned.

{
  "ok": true,
  "totalDocuments": 1,
  "documents": [
    {
      "hash": "870c8bcd4278ddfc1f8bd5769190b5513f05bed50f32b52f711ffbdf4f544d45",
      "name": "source-simpleproof.png",
      "creation_date": "2024-03-27T18:29:17.684Z",
      "confirmed": false,
      "confirmed_at": null,
      "url": "<VERIFICATION_PAGE_URL>",
      "file_download_url": "",
      "ots_download_url": "https://simple-proof-demos-q1y7tx8r8yso.s3.us-east-2.amazonaws.com/...",
      "download_url_expiration_time": 1800
    }
  ]
}

Important Notes
- The cost is calculated per hash, not per request. You can optimize costs by sending multiple hashes in a single request.
- All timestamps are returned in ISO 8601 format
- Hash verification URLs are valid for 1800 seconds (30 minutes)

400 Bad Request

The request was invalid.

{
  "ok": false,
  "msg": "Something went wrong."
}

500 Internal Server Error

The server encountered an error during verification.

{
  "ok": false,
  "msg": "Internal server error, can't continue processing the file."
}

Error Handling

All error responses follow a standard format:

{
  "ok": false,
  "msg": "Error message describing what went wrong."
}

400 Bad Request: The request was invalid or malformed.
401 Unauthorized: Authentication failed due to invalid or missing API token.
429 Too Many Requests: Rate limit exceeded. Reduce the frequency of requests.
500 Internal Server Error: An error occurred on the server.

5. Callback URL Notification

When a file/hash is processed or confirmed, the server will send a notification to the specified callback_url. The notification will be delivered as a POST request containing a JSON payload with the result of the operation.

Endpoint: POST /api/proof/file or POST /api/proof/timestamp/hashes
Description: Once a file or hash has been successfully processed, the specified callback_url will receive a POST request containing the result in JSON format.

Request to Callback URL

Method: POST
Content-Type: application/json

The body of the notification will contain a JSON object with the processing result. This object may include various fields, such as the document or hash ID, confirmation status, timestamp, and any relevant metadata.

Example of Callback Payload (JSON)

{
  "id": 5598842,
  "confirmed": true,
  "hash": "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb",
  "name": "source-simpleproof.png",
  "blockheight": 889906,
  "verified_at": "2025-03-29T01:42:39.000Z",
  "verification_link": "https://verify.simpleproof.com/SP/..."
}

Fields in the Callback JSON

id (integer): The unique identifier of the document or hash.
confirmed (boolean): The confirmation status of the document or hash (true if confirmed, false otherwise).
hash (string): The SHA256 hash of the document or file.
name (string): The name of the file or document being processed.
blockheight (integer): The blockchain block height where the timestamp was recorded.
verified_at (string, ISO 8601 date): The timestamp of when the document or hash was verified on the blockchain.
verification_link (string): A URL that points to a page where the user can view more details about the verification.

Considerations

The callback_url must accept POST requests and handle JSON payloads.
The server will send the result in JSON format. This format is consistent across all endpoints that use a callback_url (e.g., /api/proof/file and /api/proof/timestamp/hashes).
Ensure that your server at the callback_url is prepared to handle the data and respond with an appropriate status code (e.g., 200 OK or 400 Bad Request).

Example Response to the Callback POST

Your server can respond to the callback request with a status code, typically 200 OK if the data was processed successfully, or an error code if something went wrong.

{
  "ok": true,
  "msg": "Notification received and processed successfully."
}

200 OK: The request was successfully received and processed by your server.
400 Bad Request: There was an issue with processing the data, such as invalid parameters or missing required fields.

1. List Documents

Headers

Query Parameters

Response

2. Submit Hashes for Timestamping

Headers

Request Body

Response

Example Request (Using curl)

Notes

3. Upload Large Files

Headers

Request Body

Responses

4. Verify a Document

Headers

Request Body

Response

Error Handling

5. Callback URL Notification

Request to Callback URL

Example of Callback Payload (JSON)

Fields in the Callback JSON

Considerations

Example Response to the Callback POST

Example Request (Using `curl`)