Introduction

To use any of the API endpoints, you first need to acquire an API key. Contact us on enquiries@block.co to get your API key.

Block.co's API provides you with programmatic access to all of the platform's functionality and features, allowing you to issue, revoke and disseminate blockchain-anchored digital documents, without having to handle the low-level technical challenges of blockchain systems.

If you are looking for the API documentation for Block.co's NFT platform, you can find it here.

To gain access to the API you need to request an API key at enquiries@block.co.

Every request should contain an HTTP header Authorization: Token YOUR_API_KEY.

Please note that all API endpoint URLs should have a trailing slash `/` at the end.

Create Issuance

POST/issuance/

Creates an issuance of one or more documents and anchors it on the blockchain. The issuance will first have a "PROCESSING" (15) status where the documents are being processed and then a "ISSUED_PENDING" (20) status until the next block is added in the blockchain (average time ~10 minutes). The status then becomes "ISSUED" (25). Until the issuance's status becomes "ISSUED" (25), the issuance's documents will not be valid when validated. You can periodically check GET /issuance/{issuance_id}/ for the issuance status change. If the client has the private key is his ownership, the response is different, it contains information about the transaction and the raw data of the unsigned transaction that has to be signed and published to anchor the certificate files.

This request's Content-Type should be multipart/form-data. The "file" field contains a list of PDFs that are to be anchored, and the rest of the options provide access to the various issuance settings.

{ issuanceId: 212 }

{
    'issuanceId': 73,
    'tx_raw': '0200000001239f415e2b221d58cd142b1e3b7d20fb57488a4c9c316bf351cb4879d153b3040000000000ffffffff02b11f000000000000160014bb2063399ef159d8647671e5f41d55ba049e3ab00000000000000000326a3043524544000100042020202020202020bf8b7b3fe6cf3f4b5cea6d5a0b50729e1707fd4183cc1778dfeb270598b0ae3100000000',
    'address': 'tltc1qhvsxxwv779vaserkw8jlg824hgzfuw4svevc27',
    'tx_inputs': {
    '04b353d17948cb51f36b319c4c8a4857fb207d3b1e2b14cd581d222b5e419f23': 0.00013183
    }
}
                                        

Create Issuance

POST/issuance/{issuance_id}/sendsignedtx/

This endpoint is only for users which have the private key in their ownership, sends a signed transaction to server in order to be validated and published to the network. The issuance will first have a "PROCESSING" (15) status where the documents are being processed and then a "ISSUED_PENDING" (20) status until the next block is added in the blockchain (average time ~10 minutes). The status then becomes "ISSUED" (25). Until the issuance's status becomes "ISSUED" (25), the issuance's documents will not be valid when validated. You can periodically check GET /issuance/{issuance_id}/ for the issuance status change.

This request's Content-Type should be multipart/form-data. The "file" field contains a list of PDFs that are to be anchored, and the rest of the options provide access to the various issuance settings.

 { 'issuanceId': 71, 'txid': '04b353d17948cb51f36b319c4c8a4857fb207d3b1e2b14cd581d222b5e419f23' }

Create multi-issuance

POST/multi-issuance/

This endpoint is similar to the Create issuance endpoint, but it is meant to be used to issue documents on behalf or your account's sub-clients (see Sub-clients section). The only difference with the "Create Issuance" endpoint is that the CSV string in the request should contain a column __SUB_CLIENT_ID__ associating each document with a sub-client that was created by your account.)

Note: In order to use this feature your account should be authorized for this. Please contact us for more details.

Creates an issuance of one or more documents and anchors it on the blockchain. The issuance will be on a "ISSUED_PENDING" (20) state until the next block is added in the blockchain (average time ~10 minutes). Until the issuance's status becomes "ISSUED" (25), the issuance's documents will not be valid when validated. You can periodically check GET /issuance/{issuance_id}/ for the issuance status change.

This request's Content-Type should be multipart/form-data. The "file" field contains a list of PDFs that are to be anchored, and the rest of the options provide access to the various issuance settings.

{ issuanceId: 212 }

Get Issuances

GET/issuance/

All account's issuances are returned.

Possible issuance statuses are:

    PROCESSING = 15
    ISSUED_PENDING = 20
    ISSUED = 25
    EXPIRED = 30
    REVOKED_PENDING = 40
    REVOKED = 45
    FAILED = 100

    {
        "total": 12,
        "results": [
            {
                "id": 159,
                "issued_at": "2020-05-07T04:54:34.483291Z",
                "name": "Test Issuance",
                "status": 25
            }, ...
        ]
    }

Get Issuance

GET/issuance/{issuance_id}/

Returns issuance status and details.

Possible issuance statuses are:

    PROCESSING = 15
    ISSUED_PENDING = 20
    ISSUED = 25
    EXPIRED = 30
    REVOKED_PENDING = 40
    REVOKED = 45
    FAILED = 100

    {
        "id": 159,
        "name": "Test Issuance",
        "description": "",
        "status": 25,
        "issued_at": "2020-05-07T04:54:34.483291Z",
        "uploaded_to_cloud": true,
        "expiry_date": null,
        "txid": "4fca946497e50209ff84b06471ca5173c8bd86d4d53b66e7a807fbe0db51f783",
        "user": "vasilis",
        "documents": {
            "total": 1000,
            "revoked": 5,
        }
    }

Get Issuance document details

GET/issuance/{issuance_id}/documents-details/

Returns a list of all document details in an issuance.

Possible document statuses are:

    ISSUED_PENDING = 20
    ISSUED = 25
    EXPIRED = 30
    REVOKED_PENDING = 40
    REVOKED = 45
    FAILED = 100

    {
        "total": 2,
        "page": 1,
        "results": [
            {
                "id": 52131,
                "original_name": "s01-John_Smith.pdf",
                "metadata": {
                    ...
                },
                "status": 25,
                "link_id": "12345-1234-12425-123213",
                "sub_client_name": null
            },
            {
                "id": 52132,
                "original_name": "s02-Robert_Plant.pdf",
                "metadata": {
                    ...
                },
                "status": 25,
                "link_id": "12345-1234-12425-123213",
                "sub_client_name": null
            }
        ]
    }

Download Issuance documents

GET/issuance/{issuance_id}/documents/

Returns all the documents of the requested issuance as a ZIP file. This is allowed even when the issuance's status is pending, but the documents will not be valid when validated until the next block is mined on the blockchain (average 10 minutes).

All PDF documents as a ZIP file.

Get Issuance document links

GET/issuance/{issuance_id}/links/

Returns a list of all document links in an issuance.

    {
        "s01-Kostas_Karasavvas.pdf": {
            "id": "123",
            "url": "https://block-test.co/certificate/26817703-23b9-4178-a241-d8c262b441af/"
        },
        "s02-Andreas_Vlachos.pdf": {
            "id": "234",
            "url": "https://block-test.co/certificate/d78be6ef-00b7-44a8-8c67-a4704efc1ca3/"
        }
    }
    

Delete Issuance documents

DELETE/issuance/{issuance_id}/documents/

Delete all documents of the given issuance from Block.co's cloud (e.g. for GDPR purposes). This action cannot be undone.

Deleting the documents of an issuance prevents many additional features from working. You won't be able to download the documents again, Public links and QR-codes validation (if selected when issuing) will stop working etc.

A response with status 200 will be returned on success.

Revoke Issuance

DELETE/issuance/{issuance_id}/

Revokes the issuance (all of the documents). As with issuing, the issuance status will be "REVOKED_PENDING" for an average of 10 minutes until the next block is mined on the blockchain. If the client has the private key is his ownership, the response is different, it contains information about the transaction and the raw data of the unsigned transaction that has to be signed and published to validate the revocation of the issuance certificate files.

On success an empty response with status 204

{
  'issuanceId': 87,
  'tx_raw': '0200000001812ee21cff5fc6a0ffe0367f877a2912db61f1bed63d73cff3bf460ad49e61eb0000000000ffffffff029ed4000000000000160014bb2063399ef159d8647671e5f41d55ba049e3ab000000000000000002a6a284352454400010008f02659968d330acc8efb0ff37ee0347071262143749aa4d6423876e39321cff400000000',
  'address': 'tltc1qhvsxxwv779vaserkw8jlg824hgzfuw4svevc27',
  'tx_inputs': {
    'eb619ed40a46bff3cf733dd6bef161db12297a877f36e0ffa0c65fff1ce22e81': 0.00057972
  }
}
					

Revoke Issuance

DELETE/issuance/{issuance_id}/sendsignedtx/

This endpoint is only for users which have the private key in their ownership, sends a signed transaction to server in order to be validated and published to the network. Revokes the issuance (all of the documents). As with issuing, the issuance status will be "REVOKED_PENDING" for an average of 10 minutes until the next block is mined on the blockchain.

On success empty response with status 204

Download document

GET/document/{document_id}/

Returns the requested document as a PDF file. This is allowed even when the issuance's status is pending, but the document will not be valid when validated until the next block is mined on the blockchain (average 10 minutes).

The PDF file as an attachment

Revoke document

DELETE/document/{document_id}/

Revokes the specified document. The document's status will be "REVOKED_PENDING" for an average of 10 minutes until the next block is mined on the blockchain. If the client has the private key is his ownership, the response is different, it contains information about the transaction and the raw data of the unsigned transaction that has to be signed and published to validate the revocation of the certificate files.

On success an empty response with status 204

Revoke document

DELETE/document/{document_id}/sendsignedtx/

This endpoint is only for users which have the private key in their ownership, sends a signed transaction to server in order to be validated and published to the network.Revokes the specified document. The document's status will be "REVOKED_PENDING" for an average of 10 minutes until the next block is mined on the blockchain.

On success an empty response with status 204

Delete document

DELETE/delete-document/{document_id}/

Deletes the specified document from Block.co's storage. This could be done for example to satisfy GDPR requirements.

WARNING: You won't be able to download this document again! Public link validation (and QR-code validation) will not work anymore!

WARNING: The validation status of the document (if you have already downloaded it and try to validate it in a validator) won't change with this action. If it is valid, it will continue being valid. After this action, you won't be able to revoke this document!

On success an empty response with status 204

Validate document

POST/validate-document/

Check the validity of a document.

This request's Content-Type should be multipart/form-data. The "file" field should be a list containing only the PDF that is to be validated.

    On success a response with status 200 and a dict with document's information:
    {
        "cert": {PDF_FILENAME},
        "status": {VALIDATION_STATUS} ( "valid" / "invalid" ),
        "reason": {EXPLANATION_OF_THE_VALIDITY_RESULT}
    }
                                        

Get subclients

GET/auth/sub-client/

Returns a list of all the sub-clients the client has created.

Note: In order to create sub-clients and issue on behalf of them your account must have been authorized for it

    [
        {
        "id": 25,
        "name": "Subclient of Account",
        "logo": null,
        "domain": "https://example.org"
        },
        {
        "id": 27,
        "name": "Subclient2 of Account",
        "logo": null,
        "domain": "https://example2.org"
        }
    ]
                                        

Create sub-client

POST/auth/sub-client/

Create a sub-client under your account's organization. You may then use the Create multi-issuance endpoint to create issuances on behalf of sub-clients you have created. You can set/change a sub-client's logo (visible when someone validates a sub-client's document) using the Set client logo endpoint.

Note: This should be a POST request with `application/x-www-form-urlencoded` content-type

{ "sub_client_id": 28 }

Set client logo

POST/client/{client_id}/logo/

Set your organization's or one of your subclient's logo. The logo is visible when validating a document, in the public link of the document and when sending an email (through the web app).

Note: This request's Content-Type should be multipart/form-data. The "file" field should contain only the logo you decide to show up in the link, email and validate actions of a document.

{"logo": "{CLIENT_ID}/logo/{UPLOADED_FILENAME}"}

User data

GET/auth/user-data/

Get data for the current user (the associated account for the API_KEY).

    {
    "username": {CURRENT_USERNAME},
    "email": {USER'S_EMAIL},
    "verified_email": true,
    "client": {
        "id": {ORGANIZATION_ID},
        "name": {ORGANIZATION_NAME},
        "logo": {ORGANIZATION_ID}/logo/{UPLOADED_FILENAME},
        "domain": {ORGANIZATION_WEBSITE},
        "domain_identity_proof": true,
        "issuing_addresses": [
            {ORGANIZATION_BLOCKCHAIN_ADDRESS}
        ],
        "contract_type": "Contract",
        "has_pending_order": false,
        "client_links_domain": null,
        "options": {
            ...
            }
        }
    }