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 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.
Request
Parameter | Type | Position | # | Description |
---|---|---|---|---|
Authorization | string |
Header |
Required |
Should be of the form: 'Token YOUR_API_KEY'. |
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 documents 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 document. This information will be injected into each document. 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 document when visited. Default: 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 document. This option needs certificates_public option to be enabled. Default: false
|
webhook | String |
FormData |
Optional |
If this is set to a URL, this URL will receive a POST request with body { issuanceId: XX } when the issuance with this ID is confirmed on the blockchain. Example https://example.org/issuance-ready
|
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 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.
Request
Parameter | Type | Position | # | Description |
---|---|---|---|---|
Authorization | string |
Header |
Required |
Should be of the form: 'Token YOUR_API_KEY'. |
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 documents 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 document. This information will be injected into each document. 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/{document.link_id}) will be created that will display and validate the document when visited. Default: 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 document. This option needs certificates_public option to be enabled. Default: false
|
webhook | String |
FormData |
Optional |
If this is set to a URL, this URL will receive a POST request with body { issuanceId: XX } when the issuance with this ID is confirmed on the blockchain. Example https://example.org/issuance-ready
|
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_KEY'. |
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 documents 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_KEY'. |
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 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).
Request
Parameter | Type | Position | # | Description |
---|---|---|---|---|
Authorization | string |
Header |
Required |
Should be of the form: 'Token YOUR_API_KEY'. |
issuance_id | int |
URL |
Optional |
The ID of the issuance. |
Response
All PDF documents as a ZIP file.
Download Issuance QR codes
GET/issuance/{issuance_id}/qr-codes/
Returns all the QR codes (in PNG format) of the requested issuance as a ZIP file. This is allowed even when the issuance's status is pending, but when the QR codes are scanned the corresponding documents will not be valid when validated until the next block is mined on the blockchain (average 10 minutes).
The QR code images will have the same filename as the corresponding document. When scanned they will take the user to the validation screen of the document.
Note:The issuance's documents must be public, otherwise this will return an error.
Request
Parameter | Type | Position | # | Description |
---|---|---|---|---|
Authorization | string |
Header |
Required |
Should be of the form: 'Token YOUR_API_KEY'. |
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 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.
Request
Parameter | Type | Position | # | Description |
---|---|---|---|---|
Authorization | string |
Header |
Required |
Should be of the form: 'Token YOUR_API_KEY'. |
issuance_id | int |
URL |
Optional |
The id of the issuance to be revoked. |
Response
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).
Request
Parameter | Type | Position | # | Description |
---|---|---|---|---|
Authorization | string |
Header |
Required |
Should be of the form: 'Token YOUR_API_KEY'. |
document_id | int |
URL |
Required |
The id of the document to be downloaded |
Response
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.
Request
Parameter | Type | Position | # | Description |
---|---|---|---|---|
Authorization | string |
Header |
Required |
Should be of the form: 'Token YOUR_API_KEY'. |
document_id | int |
URL |
Required |
The id of the document to be revoked |
Response
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.
Request
Parameter | Type | Position | # | Description |
---|---|---|---|---|
Authorization | string |
Header |
Required |
Should be of the form: 'Token YOUR_API_KEY'. |
file | file |
FormData |
Required |
The PDF to be validated. Example: S0001-John_Smith.pdf
|
Response
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
Request
Parameter | Type | Position | # | Description |
---|---|---|---|---|
Authorization | string |
Header |
Required |
Should be of the form: 'Token YOUR_API_KEY'. |
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. 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
Request
Parameter | Type | Position | # | Description |
---|---|---|---|---|
Authorization | string |
Header |
Required |
Should be of the form: 'Token YOUR_API_KEY'. |
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 }
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.
Request
Parameter | Type | Position | # | Description |
---|---|---|---|---|
Authorization | string |
Header |
Required |
Should be of the form: 'Token YOUR_API_KEY'. |
client_id | int |
URL |
Required |
The ID of the client. |
file | file |
FormData |
Required |
The file of the logo to be set, it should be in a picture format (jpeg,png...) |
Response
{"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).
Request
Parameter | Type | Position | # | Description |
---|---|---|---|---|
Authorization | string |
Header |
Required |
Should be of the form: 'Token YOUR_API_KEY'. |
Response
{ "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": { ... } } }