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.

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.

Create Issuance

POST/issuance/

Creates an issuance of one or more certificates and anchors it on the blockchain. The issuance will be on a "ISSUED_PENDING" (20) state until the next block is added in the Bitcoin blockchain (average time ~10 minutes). Until the issuance's status becomes "ISSUED" (25), the issuance's certificates 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.

Request

Parameter Type Position # Description
Authorization string Header Required Should be of the form: 'Token YOUR_API_TOKEN'.
file file FormData Required A list of the PDF(s) to be issued. Example: S0001-John_Smith.pdf, S0002-Robert_Plant.pdf
name string FormData Required The issuance name. It will not be published on the blockchain, it is used for archiving purposes. Example: Test issuance
description string FormData Optional An optional description for the issuance. It will not be published on the blockchain, it's used for archiving purposes. Example: Test description
expiry_date ISO date string FormData Optional An optional expiry date for the certificates of the issuance. Example 2020-05-14T21:00:00.000Z
csv CSV string FormData Optional A string representation of a CSV file that contains individual information for each certificate. This information will be injected into each certificate. Example: id,name,email\nS0001,John Smith,foo@example.com\nS0002,Robert Plant,bar@example.com
cert_names_csv_column string FormData Optional If the csv field was submitted, this field is required and indicates the csv column that contains the unique id which matches with the PDF filenames. E.g. for issuing 2 PDFs with filenames "S0001-John_Smith.pdf" and "S0002-Robert_Plant.pdf" and injecting some custom metadata into them, the CSV file needs to have a column that is used to match each row with each PDF file. So in our example in that column each row of metadata would have a values "S0001" and "S0002" or anything matching the beginning of the filenames. Example id
cert_metadata_columns JSON string FormData Optional An optional stringified JSON object that controls visibility, label and ordering and will be used for each metadata column when validating a document. This is only used if the csv field was included in the request. Example: {"columns":[{"id":{"order":0,"label":"id","hide":true}},{"name":{"order":1,"label":"name","hide":false}},{"email":{"order":2,"label":"email","hide":true}}]}
certificates_public Boolean FormData Optional If set to true, a public link (e.g. https://app.block.co/certificate/a1234-b56d7-....) will be created that will display and validate the certificate when visited. Example false
qr_code Boolean FormData Optional If set to true, a page with a QR-code will be appended to each PDF document. Scanning this code with any QR-code scanner application will visit the public link of the certificate. This option needs certificates_public option to be enabled. Example false

Response

{ issuanceId: 212 }

Create multi-issuance

POST/multi-issuance/

This endpoint is similar to the Create issuance endpoint, but it is meant to be used to issue certificates 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 certificate 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 certificates and anchors it on the blockchain. The issuance will be on a "ISSUED_PENDING" (20) state until the next block is added in the Bitcoin blockchain (average time ~10 minutes). Until the issuance's status becomes "ISSUED" (25), the issuance's certificates 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.

Request

Parameter Type Position # Description
Authorization string Header Required Should be of the form: 'Token YOUR_API_TOKEN'.
file file FormData Required A list of the PDF(s) to be issued. Example: S0001-John_Smith.pdf, S0002-Robert_Plant.pdf
name string FormData Required The issuance name. It will not be published on the blockchain, it is used for archiving purposes. Example: Test issuance
description string FormData Optional An optional description for the issuance. It will not be published on the blockchain, it's used for archiving purposes. Example: Test description
expiry_date ISO date string FormData Optional An optional expiry date for the certificates of the issuance. Example 2020-05-14T21:00:00.000Z
csv CSV string FormData Optional A string representation of a CSV file that contains individual information for each certificate. This information will be injected into each certificate. Example: id,name,email\nS0001,John Smith,foo@example.com\nS0002,Robert Plant,bar@example.com
cert_names_csv_column string FormData Optional If the csv field was submitted, this field is required and indicates the csv column that contains the unique id which matches with the PDF filenames. E.g. for issuing 2 PDFs with filenames "S0001-John_Smith.pdf" and "S0002-Robert_Plant.pdf" and injecting some custom metadata into them, the CSV file needs to have a column that is used to match each row with each PDF file. So in our example in that column each row of metadata would have a values "S0001" and "S0002" or anything matching the beginning of the filenames. Example id
cert_metadata_columns JSON string FormData Optional An optional stringified JSON object that controls visibility, label and ordering and will be used for each metadata column when validating a document. This is only used if the csv field was included in the request. Example: {"columns":[{"id":{"order":0,"label":"id","hide":true}},{"name":{"order":1,"label":"name","hide":false}},{"email":{"order":2,"label":"email","hide":true}}]}
certificates_public Boolean FormData Optional If set to true, a public link (e.g. https://app.block.co/certificate/a1234-b56d7-....) will be created that will display and validate the certificate when visited. Example false
qr_code Boolean FormData Optional If set to true, a page with a QR-code will be appended to each PDF document. Scanning this code with any QR-code scanner application will visit the public link of the certificate. This option needs certificates_public option to be enabled. Example false

Response

{ issuanceId: 212 }

Get Issuances

GET/issuance/

All account's issuances are returned.

Possible issuance statuses are:

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

Request

Parameter Type Position # Description
Authorization string Header Required Should be of the form: 'Token YOUR_API_TOKEN'.
page int Query parameter Optional If no issuance_id is provided (e.g. GET /issuance/), the resulting list of issuances is paginated by 10. A page query parameter is required to get the appropriate page. Example: ?page=2

Response

    {
        "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, along with a list of all the issuance's certificates details.

Possible issuance statuses are:

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

Request

Parameter Type Position # Description
Authorization string Header Required Should be of the form: 'Token YOUR_API_TOKEN'.
issuance_id int URL Optional If provided (e.g. /issuance/14), the details for issuance 14 will be returned. Otherwise, all user's issuances are returned.

Response

    {
        "id": 159,
        "name": "Test Issuance",
        "description": "",
        "status": 25,
        "issued_at": "2020-05-07T04:54:34.483291Z",
        "uploaded_to_s3": true,
        "expiry_date": null,
        "txid": "4fca946497e50209ff84b06471ca5173c8bd86d4d53b66e7a807fbe0db51f783",
        "user": "vasilis",
        "certificates": [
            {
                "id": 15207,
                "name": "s01-John_Smith.pdf",
                "original_name": "s01-John Smith.pdf",
                "metadata": { "id": "S01" },
                "status": 25,
                "link_id": "012958a2-53b7-4ad8-9039-147e074527d1"
            }, ...
        ]
    }

Download Issuance certificates

GET/issuance/{issuance_id}/certificates/

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

Request

Parameter Type Position # Description
Authorization string Header Required Should be of the form: 'Token YOUR_API_TOKEN'.
issuance_id int URL Optional The ID of the issuance.

Response

All PDF documents as a ZIP file.

Revoke Issuance

DELETE/issuance/{issuance_id}/

Revokes the issuance (all of the certificates). As with issuing, the issuance status will be "REVOKED_PENDING" for an average of 10 minutes until the next block is mined on the bitcoin blockchain.

Request

Parameter Type Position # Description
Authorization string Header Required Should be of the form: 'Token YOUR_API_TOKEN'.
issuance_id int URL Optional The id of the issuance to be revoked.

Response

On success empty response with status 204

Download certificate

GET/certificate/{certificate_id}/

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

Request

Parameter Type Position # Description
Authorization string Header Required Should be of the form: 'Token YOUR_API_TOKEN'.
certificate_id int URL Required The id of the certificate to be downloaded

Response

The PDF file as an attachment

Revoke certificate

DELETE/certificate/{certificate_id}/

Revokes the specified certificate. The certificate's status will be "REVOKED_PENDING" for an average of 10 minutes until the next block is mined on the bitcoin blockchain.

Request

Parameter Type Position # Description
Authorization string Header Required Should be of the form: 'Token YOUR_API_TOKEN'.
certificate_id int URL Required The id of the certificate to be revoked

Response

On success an empty response with status 204

Validate Certificates

POST/validate-certificates/

Check the validity of a certificate or a batch of certificates (up to 10 certificates).

This request's Content-Type should be multipart/form-data. The "file" field contains a list of PDFs that are to be validated.

Request

Parameter Type Position # Description
Authorization string Header Required Should be of the form: 'Token YOUR_API_TOKEN'.
file file FormData Required A list of the PDF(s) to be validated. Example: S0001-John_Smith.pdf, S0002-Robert_Plant.pdf

Response

    On success a response with status 200 and a dict with certificate'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

Request

Parameter Type Position # Description
Authorization string Header Required Should be of the form: 'Token YOUR_API_TOKEN'.

Response

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

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

Request

Parameter Type Position # Description
Authorization string Header Required Should be of the form: 'Token YOUR_API_TOKEN'.
name string Body Required Organization name of the sub-client. Example: University of Nicosia`
domain string Body Required URL of the sub-client's domain. Example: https://example.org

Response

{ "sub_client_id": 28 }