Introduction
In this example we will showcase how you can use the Accounton Developer API to navigate and retrieve the data in your backoffice. This example assumes you already have received your Authentication credentials with the appropriate scopes.
In this particular example we will select the currently active year, list the active checklists, select a checklist and list the transcripts for those checklists and retrieve the generated documents for those transcripts.
Step 1: Select the active financial year
First off, Accounton is organised per financial year. Every start of a new financial year, means that we archive any data from the previous year, and enable the system to start collecting and storing data in the new financial year. In order to retrieve the current financial year that is active in your backoffice, it suffices to perform the following call:
curl --location 'https://dev-api.accounton.io/financialyears/current' \
--header 'x-client-id: <client-id>' \
--header 'x-client-secret: <client-secret>'
A typical response looks like what follows:
{
"startDate": "2022",
"endDate": "2023",
"isCurrentYear": true,
"_id": "63e0fec7cba4472b20a00094"
}
This gives us the id (63e0fec7cba4472b20a00094) of the currently activated financial year, which we can use as a filter parameter on other REST API calls.
Step 2: Select the checklist
We move on to getting the identifier of the checklist for which we want to retrieve all completed transcripts. We start by listing all dutch checklists of the currently activated financial year:
curl --location 'https://dev-api.accounton.io/checklists?language=dutch&financialYear=63e0fec7cba4472b20a00094' \
--header 'x-client-id: <your-client-id>' \
--header 'x-client-secret: <your-client-secret>'
An example response, which retrieves the five active checklists:
{
"first_page": "/checklists?language=dutch&page=1&pageSize=100",
"last_page": "/checklists?language=dutch&page=1&pageSize=100",
"total": 5,
"count": 5,
"data": [
{
"_id": "604f3f79fad44962bf9e7fcf",
"name": "checklist van de personenbelasting",
"language": "dutch",
"authRequired": false,
"remindersEnabled": true
},
{
"_id": "607ef762571d3b7397df18d3",
"name": "vragenlijst personenbelasting",
"language": "dutch",
"authRequired": false,
"remindersEnabled": true
},
{
"_id": "60b5ed2a7ad35a256d417b99",
"name": "checklist van de personenbelasting - FR",
"language": "dutch",
"authRequired": false,
"remindersEnabled": true
},
{
"_id": "610017c3e936760894920309",
"name": "signing test",
"language": "dutch",
"authRequired": false,
"remindersEnabled": false
},
{
"_id": "6405f4540199a1927e8a1acd",
"name": "vragenlijst personenbelasting - Updated",
"language": "dutch",
"authRequired": false,
"remindersEnabled": true
}
]
}
Step 3: list transcripts of a selected checklist
Suppose we are interested in the transcripts (e.g., the filled-in questionnaires of the customers) of checklist with id 604f3f79fad44962bf9e7fcf and the current financial year:
curl --location 'https://dev-api.accounton.io/transcripts?checklist=604f3f79fad44962bf9e7fcf&financialYear=63e0fec7cba4472b20a00094' \
--header 'x-client-id: <your-client-id>' \
--header 'x-client-secret: <your-client-secret>'
This would result in the following (trimmed) response:
{
"first_page": "/transcripts?page=1&pageSize=100",
"last_page": "/transcripts?page=1&pageSize=100",
"total": 66,
"count": 66,
"data": [
{
"_id": "63e0fec8cba4472b20a0029a",
"status": "To Process",
"isCompleted": true,
"financialYear": "63e0fec7cba4472b20a00094",
"customVariables": {},
"documentGenerated": true,
"customer": "62751aa38aa8f04a7885c8a2"
},
{
"_id": "63e218b79f0f1bd4aa51cbbd",
"status": "Sent",
"isCompleted": false,
"financialYear": "63e0fec7cba4472b20a00094",
"customVariables": {},
"documentGenerated": false,
"customer": "63e218b09f0f1b141d51cba0"
},
{
"_id": "63e218fd9f0f1bc4a551cc09",
"status": "Sent",
"isCompleted": false,
"financialYear": "63e0fec7cba4472b20a00094",
"customVariables": {},
"documentGenerated": false,
"customer": "63e218b09f0f1b141d51cba0"
},
{
"_id": "63f384647af47b7a82aa50bc",
"status": "To Process",
"isCompleted": true,
"financialYear": "63e0fec7cba4472b20a00094",
"customVariables": {},
"documentGenerated": true,
"customer": "60fe72f99a56fe160ac3cbdf"
},
...
]
}
Every transcript has a documentGenerated property which indicates whether Accounton has generated a document for the filled in transcript.
Step 4: Download the generated document
For example, the transcript with id 63e0fec8cba4472b20a0029a has been completed and has documentGenerated true. This means that we can download the actual generated file:
curl --location 'http://dev-api.accounton.io/transcripts/download/63e0fec8cba4472b20a0029a/file' \
--header 'x-client-id: <your-client-id>' \
--header 'x-client-secret: <your-client-secret>'
In case you are only interested in the metadata of the file:
curl --location 'http://dev-api.accounton.io/transcripts/download/63e0fec8cba4472b20a0029a/metadata' \
--header 'x-client-id: <x-client-secret>' \
--header 'x-client-secret: <x-client-id>'
For which an example response looks like:
{
"contentType": "application/pdf",
"size": 76325,
"md5Hash": "hydBcIDy/U/mha5nZRKQlQ==",
"timeCreated": "2023-02-10T08:30:33.195Z"
}