Verify files

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.

  For unconfirmed documents (confirmed: false):

  JSON

  {
    "ok": true,
    "totalDocuments": 1,
    "documents": [
      {
        "hash": "870c8bcd4278ddfc1f8bd5769190b5513f05bed50f32b52f711ffbdf4f544d45",
        "name": "example-document.pdf",
        "creation_date": "2024-03-27T18:29:17.684Z",
        "confirmed": false,
        "confirmed_at": null,
        "url": "https://verify.simpleproof.com/SQ.....",
        "file_downloadable": true,
        "file_download_url": "https://example-storage.s3........",
        "ots_download_url": "https://example-storage.s3.u,,,...",
        "download_url_expiration_time": 1800
      }
    ]
  }
  

  For confirmed documents (confirmed: true):

  JSON

  {
    "ok": true,
    "totalDocuments": 1,
    "documents": [
      {
        "hash": "5ce32a6ce7fa488d055c2eb5e19bf2f5de7454af28bb951b96ad6d833be873c2",
        "name": "confirmed-document.csv",
        "creation_date": "2024-03-20T14:15:30.123Z",
        "confirmed": true,
        "block": 842150,
        "confirmed_at": "2024-03-20T14:45:22.000Z",
        "url": "https://verify.simpleproof.com/SQS/....",
        "file_downloadable": false,
        "file_download_url": "",
        "ots_download_url": "https://example-storage.s3......",
        "download_url_expiration_time": 1800
      }
    ]
  }
  

Response Fields

• ok (boolean): Indicates if the request was successful

• totalDocuments (integer): Number of documents found

• documents (array): Array of document objects with the following fields:

  • hash (string): The document's hash
  • name (string): Original filename
  • creation_date (string): ISO 8601 timestamp when the document was submitted
  • confirmed (boolean): Whether the document has been confirmed on the blockchain
  • url (string): Verification page URL
  • download_url_expiration_time (integer): Expiration time for download URLs in seconds

  Additional fields when confirmed: false:

  • confirmed_at (null): Will be null for unconfirmed documents
  • file_downloadable (boolean): Whether the original file can be downloaded
  • file_download_url (string): Direct download URL for the original file (if downloadable)
  • ots_download_url (string): Download URL for the OpenTimestamps proof file

  Additional fields when confirmed: true:

  • block (integer): Bitcoin block number where the proof was confirmed
  • confirmed_at (string): ISO 8601 timestamp when the document was confirmed
  • file_downloadable (boolean): Whether the original file can be downloaded
  • file_download_url (string): Direct download URL for the original file (empty if not downloadable)
  • ots_download_url (string): Download URL for the OpenTimestamps proof file

Important Notes

• The response structure differs based on the confirmation status of the document

• Confirmed documents typically only provide the OpenTimestamps proof file for download

• Bitcoin transaction information is not provided in the API response. To view the actual Bitcoin transaction details, you must use the OTS (OpenTimestamps) file with an OTS Navigator tool

• All timestamps are returned in ISO 8601 format

• Presigned 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.