8 Service APIs
This section provides a reference for APIs that should be implemented by this Building Block.
The APIs defined here establish a blueprint for how the Building Block will interact with other Building Blocks. Additional APIs may be implemented by the Building Block, but the listed APIs define a minimal set of functionality that should be provided by any implementation of this Building Block.
The GovStack non-functional requirements document provides additional information on how 'adaptors' may be used to translate an existing API to the patterns described here. This section also provides guidance on how candidate products are tested and how GovStack validates a product's API against the API specifications defined here.
The tests for the Registration Building Block can be found in this GitHub repository.
8.1 Online Registration e-services
The available services (i.e. registration processes) and form definitions within such a service can be accessed:
Listing of all services with basic information
Register Mother and Child
GET /services HTTP/1.1
Host:
Accept: */*
[
{
"id": "f7d33db0-2809-484e-a780-76b7ccd4ecbf",
"name": "Mother and Child Registration",
"version": "123",
"type": "None",
"isExecutable": true,
"isClosed": true,
"description": "text",
"serviceBody": [
{
"code": "text",
"value": "text"
}
]
}
]
Pass in the ID of the service and it will return all information about that service
The id for a defined service in the registration BB workflow engine.
f7d33db0-2809-484e-a780-76b7ccd4ecbf
GET /services/{serviceId} HTTP/1.1
Host:
Accept: */*
{
"id": "f7d33db0-2809-484e-a780-76b7ccd4ecbf",
"name": "Mother and Child Registration",
"version": "123",
"type": "None",
"isExecutable": true,
"isClosed": true,
"description": "text",
"serviceBody": [
{
"code": "text",
"value": "text"
}
]
}
Get the list of all e-service forms with schema related to the given service
The id for a defined service in the registration BB workflow engine.
f7d33db0-2809-484e-a780-76b7ccd4ecbf
GET /services/{serviceId}/eForms HTTP/1.1
Host:
Accept: */*
list of eForms or an empty array if none are available
[
{
"eFormId": "d98a205a-679b-485b-823d-7a32a391e744",
"name": "FORM",
"description": "text",
"version": "1",
"latest": true
}
]
The ID of the e-form to retrieve
GET /eForms/{eFormId} HTTP/1.1
Host:
Accept: */*
{
"eFormId": "d98a205a-679b-485b-823d-7a32a391e744",
"name": "A1",
"description": "text",
"version": "1",
"latest": true,
"schema": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
8.1.2 Generic Registration Steps
Going through the registration process as an applicant requires multiple steps available via API endpoints:
Send an application file including all documents and form data to submit a registration request to be processed by operators.
The id for a defined service in the registration BB workflow engine.
f7d33db0-2809-484e-a780-76b7ccd4ecbf
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
eGovStack/GOV/90000009/digitalregistries
Free text application name
Amya Yuko
Applicant is a user who submitted application, this id references the user account logged in on the system and submitting this request. The applicantId could also come from OAuth2 and OpenID Connect authentication. New applicant records are created by the system internally if necessary.
42962de0-bdb2-11ed-9397-0242ac120004
Time when the application file was created by the user- Draft
2000-10-23T00:00:00.000Z
POST /services/{serviceId}/applications HTTP/1.1
Host:
Information-Mediator-Client: text
Content-Type: application/json
Accept: */*
Content-Length: 245
{
"applicationName": "Amya Yuko",
"applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
"created": "2000-10-23T00:00:00.000Z",
"formData": {
"data": {
"ANY_ADDITIONAL_PROPERTY": {}
},
"eFormId": "42962de0-bdb2-11ed-9397-0242ac120004"
},
"documentUrls": [
"text"
]
}
{
"fileId": "81c4445c-bff6-11ed-afa1-0242ac120002",
"registered": "2000-10-23T00:00:00.000Z",
"serviceId": "123e4567-e89b-12d3-a456-426614174000",
"serviceName": "Post partum registration service",
"status": {
"code": "PENDING",
"title": "Pending"
},
"ended": "false",
"applicationData": {
"applicationName": "Amya Yuko",
"applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
"created": "2000-10-23T00:00:00.000Z",
"formData": {
"data": {
"ANY_ADDITIONAL_PROPERTY": {}
},
"eFormId": "42962de0-bdb2-11ed-9397-0242ac120004"
},
"documentUrls": [
"text"
]
}
}
Upload a document/attachment to receive a documentId that can be linked to applications when submitting a new registration
Additional Metadata
V2UgbG92ZSBqc29uIQ==
POST /documents HTTP/1.1
Host:
Content-Type: multipart/form-data
Accept: */*
Content-Length: 33
{
"file": [
"V2UgbG92ZSBqc29uIQ=="
]
}
{
"code": 1,
"type": "text",
"message": "text",
"url": "text"
}
8.2 Processing of Registrations
Operators can access and process existing application files:
Returns a list of application files the user has permission to access (i.e. either only the applicant's own applications or all applications for an operator to process)
id of a service to filter for applications of only this service
Applicant user ID
42962de0-bdb2-11ed-9397-0242ac120004
Pagination of results. Specifies the index of the first result to return.
1
Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
10
Sort the results lexicographically by a given criterion. Valid values are instanceId, caseInstanceId, dueDate, executionId, caseExecutionId,assignee, created, description, id, name, nameCaseInsensitive and priority. Must be used in conjunction with the sortOrder parameter.
created
Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
asc
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
eGovStack/GOV/90000009/digitalregistries
GET /applications HTTP/1.1
Host:
Information-Mediator-Client: text
Accept: */*
list of applications or an empty array if none are available
[
{
"fileId": "81c4445c-bff6-11ed-afa1-0242ac120002",
"mainTaskId": "42962de0-bdb2-11ed-9397-0242ac120004",
"taskTitle": "Application xyz",
"roleId": "42962de0-bdb2-11ed-9397-0242ac120004",
"roleName": "Registrar",
"assigneeId": "42962de0-bdb2-11ed-9397-0242ac120004",
"operatorName": "John Smith",
"status": {
"code": "PENDING",
"title": "Pending"
},
"applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
"created": "2000-10-23T00:00:00.000Z",
"registered": "2000-10-23T00:00:00.000Z",
"description": "Any text.",
"serviceName": "Post partum registration service",
"serviceId": "42962de0-bdb2-11ed-9397-0242ac120004",
"eformId": "42962de0-bdb2-11ed-9397-0242ac120004",
"documentUrls": [
"text"
],
"additionalMeta": {
"data": {
"ANY_ADDITIONAL_PROPERTY": {}
}
}
}
]
Returns application file
8a70cd6d-bdb2-11ed-9397-0242ac120004
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
eGovStack/GOV/90000009/digitalregistries
GET /applications/{fileId} HTTP/1.1
Host:
Information-Mediator-Client: text
Accept: */*
{
"fileId": "81c4445c-bff6-11ed-afa1-0242ac120002",
"registered": "2000-10-23T00:00:00.000Z",
"serviceId": "123e4567-e89b-12d3-a456-426614174000",
"serviceName": "Post partum registration service",
"status": {
"code": "PENDING",
"title": "Pending"
},
"ended": "false",
"applicationData": {
"applicationName": "Amya Yuko",
"applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
"created": "2000-10-23T00:00:00.000Z",
"formData": {
"data": {
"ANY_ADDITIONAL_PROPERTY": {}
},
"eFormId": "42962de0-bdb2-11ed-9397-0242ac120004"
},
"documentUrls": [
"text"
]
}
}
Returns updated service application file ID
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
eGovStack/GOV/90000009/digitalregistries
Free text application name
Amya Yuko
Applicant is a user who submitted application, this id references the user account logged in on the system and submitting this request. The applicantId could also come from OAuth2 and OpenID Connect authentication. New applicant records are created by the system internally if necessary.
42962de0-bdb2-11ed-9397-0242ac120004
Time when the application file was created by the user- Draft
2000-10-23T00:00:00.000Z
PUT /applications/{fileId} HTTP/1.1
Host:
Information-Mediator-Client: text
Content-Type: application/json
Accept: */*
Content-Length: 245
{
"applicationName": "Amya Yuko",
"applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
"created": "2000-10-23T00:00:00.000Z",
"formData": {
"data": {
"ANY_ADDITIONAL_PROPERTY": {}
},
"eFormId": "42962de0-bdb2-11ed-9397-0242ac120004"
},
"documentUrls": [
"text"
]
}
{
"fileId": "81c4445c-bff6-11ed-afa1-0242ac120002",
"registered": "2000-10-23T00:00:00.000Z",
"serviceId": "123e4567-e89b-12d3-a456-426614174000",
"serviceName": "Post partum registration service",
"status": {
"code": "PENDING",
"title": "Pending"
},
"ended": "false",
"applicationData": {
"applicationName": "Amya Yuko",
"applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
"created": "2000-10-23T00:00:00.000Z",
"formData": {
"data": {
"ANY_ADDITIONAL_PROPERTY": {}
},
"eFormId": "42962de0-bdb2-11ed-9397-0242ac120004"
},
"documentUrls": [
"text"
]
}
}
Returns task list
Pagination of results. Specifies the index of the first result to return.
Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.
Sort the results lexicographically by a given criterion. Valid values are instanceId, caseInstanceId, dueDate, executionId, caseExecutionId,assignee, created, description, id, name, nameCaseInsensitive and priority. Must be used in conjunction with the sortOrder parameter.
Sort the results in a given order. Values may be asc for ascending order or desc for descending order. Must be used in conjunction with the sortBy parameter.
GET /tasks HTTP/1.1
Host:
Accept: */*
list of tasks or an empty array if none are available
[
{
"taskId": "text",
"mainTaskId": "text",
"name": "text",
"assigneeId": "text",
"roleId": "text",
"created": "2025-06-25T07:46:14.052Z",
"description": "text",
"serviceId": "123e4567-e89b-12d3-a456-426614174000",
"serviceName": "text",
"fileId": "text",
"eFormId": "text",
"status": {
"code": "PENDING",
"title": "Pending"
}
}
]
Returns task by id
GET /tasks/{taskId} HTTP/1.1
Host:
Accept: */*
{
"taskId": "text",
"taskName": "text",
"assigneeId": "text",
"roleId": "42962de0-bdb2-11ed-9397-0242ac120004",
"created": "2025-06-25T07:46:14.052Z",
"description": "text",
"fileId": "text",
"serviceId": "123e4567-e89b-12d3-a456-426614174000",
"serviceName": "text",
"eFormId": "text",
"formVariables": {
"ANY_ADDITIONAL_PROPERTY": {}
},
"status": {
"code": "PENDING",
"title": "Pending"
},
"data": {
"ANY_ADDITIONAL_PROPERTY": {}
}
}
POST /tasks/{taskId}/complete HTTP/1.1
Host:
Content-Type: application/json
Accept: */*
Content-Length: 39
{
"data": {
"ANY_ADDITIONAL_PROPERTY": {}
}
}
{
"taskId": "text",
"fileId": "text",
"serviceId": "123e4567-e89b-12d3-a456-426614174000",
"status": {
"code": "PENDING",
"title": "Pending"
},
"variables": {
"ANY_ADDITIONAL_PROPERTY": {
"data": {
"ANY_ADDITIONAL_PROPERTY": {}
}
}
}
}
8.3 Development Platform
Currently there are no specifications for API endpoints to manage and design services and workflows.
Statistics
The statistics API gives Building Block operational statistics, that reference the number of processed applications (per operator, registration, service, date):
API endpoint that allows anyone to see service statistics
Start date of statistics
2021-01-30
End date of statistics
2021-01-30
Name of registration
MCTS
Name of operator
Ingmar Vali
Role of the operator
Handler
Timerame:
day
- timeframe value = dayweek
- timeframe value = weekmonth
- timeframe value = monthyear
- timeframe value = year
Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM
eGovStack/GOV/90000009/eregistrations-dev
GET /data/statistics HTTP/1.1
Host:
Information-Mediator-Client: text
Accept: */*
[]
Last updated
Was this helpful?