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.

  JSON

  {
    "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.

  JSON

  {
    "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:

  JSON

  {
  	"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.

  JSON

  {
    "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).

  JSON

  {
    "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.

  JSON

  {
    "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.

  JSON

  {
    "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.

  JSON

  {
    "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:

  JSON

  {
    "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.

  JSON

  {
    "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.

  JSON

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

• 500 Internal Server Error

  The server encountered an error during verification.

  JSON

  {
    "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. Proof Lifecycle & Callback Notification

How a Proof is Confirmed

When you submit a file or hash, the proof goes through two stages:

1. Pending — The hash has been received and included in a Bitcoin transaction, but the transaction has not yet received enough confirmations. If you download the .ots file at this stage, it will be a pending proof — valid but not yet fully verifiable against the blockchain.

2. Confirmed — The Bitcoin transaction has received at least 3 block confirmations (typically ~30 minutes after submission). The .ots file is now a complete, independently verifiable proof. At this point, the callback notification is triggered.

Note: Simple Proof also submits hashes to the Alice and Bob calendars from opentimestamps.org, so the resulting .ots files are compatible with the standard OpenTimestamps ecosystem.

Downloading the OTS File

The .ots file available for download reflects the current state of the proof:

• Before confirmation: The file is a pending .ots proof.
• After confirmation: The file is the complete .ots proof, fully verifiable against the Bitcoin blockchain.

You can use the confirmed field in the API response or the callback notification to determine when the complete file is ready.

Callback URL Notification

If you provide a callback_url when submitting a proof, the server will send a POST request to that URL once the proof has been confirmed (3+ block confirmations). This allows you to automate workflows — for example, updating a local .ots file, committing to an archive, or notifying a user that the proof is ready.

The callback applies to proofs submitted via:

• POST /api/proof/file
• POST /api/proof/timestamp/hashes

Callback Request Format

• Method: POST
• Content-Type: application/json

Example Callback Payload

{
  "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/..."
}

Callback JSON Fields

Handling the Callback

Your server at the callback_url must:

• Accept POST requests with application/json body.
• Respond with an appropriate HTTP status code.

Example Response

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

• 200 OK — The notification was received and processed successfully.
• 400 Bad Request — There was an issue processing the notification (e.g., invalid payload).