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:

returns a list of services (Services available to use)

get

Listing of all services with basic information

Query parameters

namestringOptionalExample: Register Mother and Child

Responses

200

list of services or an empty array if none are available

application/json

idstring · uuidRequired

unique identifier (serviceId)

Example: f7d33db0-2809-484e-a780-76b7ccd4ecbf

namestringRequired

name of a service

Example: Mother and Child Registration

versionstringRequired

service version number

Example: 123

typestring · enumRequiredPossible values:

isExecutablebooleanOptional

Specifies whether the service is executable

isClosedbooleanOptional

whether Messages and Events, not modeled in Service, can occur when the service is executed or performed

descriptionstringOptional

500

Internal server error, please contact administrator

*/*

get

/services

HTTPcURLJavaScriptPython

GET /services HTTP/1.1
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"
      }
    ]
  }
]

returns detailed information about a service

get

Pass in the ID of the service and it will return all information about that service

Path parameters

serviceIdstring · uuidRequired

The id for a defined service in the registration BB workflow engine.

Example: f7d33db0-2809-484e-a780-76b7ccd4ecbf

Responses

200

Service found and representation returned

application/json

idstring · uuidRequired

unique identifier (serviceId)

Example: f7d33db0-2809-484e-a780-76b7ccd4ecbf

namestringRequired

name of a service

Example: Mother and Child Registration

versionstringRequired

service version number

Example: 123

typestring · enumRequiredPossible values:

isExecutablebooleanOptional

Specifies whether the service is executable

isClosedbooleanOptional

whether Messages and Events, not modeled in Service, can occur when the service is executed or performed

descriptionstringOptional

404

service not found

500

Internal server error, please contact administrator

*/*

get

/services/{serviceId}

HTTPcURLJavaScriptPython

GET /services/{serviceId} HTTP/1.1
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"
    }
  ]
}

Retrieve all available e-forms

get

Get the list of all e-service forms with schema related to the given service

Path parameters

serviceIdstring · uuidRequired

The id for a defined service in the registration BB workflow engine.

Example: f7d33db0-2809-484e-a780-76b7ccd4ecbf

Responses

200

list of eForms or an empty array if none are available

application/json

eFormIdstringOptional

The unique identifier of the e-form

Example: d98a205a-679b-485b-823d-7a32a391e744

namestringOptional

The name of the e-form

Example: FORM

descriptionstringOptional

A description of the e-form

versionstringOptional

Version of the e-form

Example: 1

latestbooleanOptional

True if the last version

get

/services/{serviceId}/eForms

HTTPcURLJavaScriptPython

GET /services/{serviceId}/eForms HTTP/1.1
Accept: */*

200

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
  }
]

Retrieve a specific e-form by ID

get

Path parameters

eFormIdstringRequired

The ID of the e-form to retrieve

Responses

200

OK

application/json

eFormIdstringOptional

The unique identifier of the e-form

Example: d98a205a-679b-485b-823d-7a32a391e744

namestringOptional

The name of the e-form

Example: A1

descriptionstringOptional

A description of the e-form

versionstringOptional

Version of the e-form

Example: 1

latestbooleanOptional

True if the last version

404

Not Found

get

/eForms/{eFormId}

HTTPcURLJavaScriptPython

GET /eForms/{eFormId} HTTP/1.1
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:

Submit an application file as an applicant

post

Send an application file including all documents and form data to submit a registration request to be processed by operators.

Path parameters

serviceIdstring · uuidRequired

The id for a defined service in the registration BB workflow engine.

Example: f7d33db0-2809-484e-a780-76b7ccd4ecbf

Header parameters

Information-Mediator-ClientstringRequired

Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM

Example: eGovStack/GOV/90000009/digitalregistries

Body

application/json

applicationNamestringOptional

Free text application name

Example: Amya Yuko

applicantIdstringRequired

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.

Example: 42962de0-bdb2-11ed-9397-0242ac120004

createdstring · date-timeOptional

Time when the application file was created by the user- Draft

Example: 2000-10-23T00:00:00.000Z

documentUrlsstring[]Optional

Responses

200

Returns started application file ID

*/*

fileIdstringOptional

Application file identifier 81c4445c-bff6-11ed-afa1-0242ac120002

Example: 81c4445c-bff6-11ed-afa1-0242ac120002

registeredstring · date-timeOptional

Time when the application file was registered in the Registration BB system

Example: 2000-10-23T00:00:00.000Z

serviceIdstring · uuidRequired

id of the service this application relates to

serviceNamestringOptionalExample: Post partum registration service

endedbooleanOptional

True, if application file processing has ended

Example: false

404

Service was not found

500

Internal server error, please contact administrator

*/*

post

/services/{serviceId}/applications

HTTPcURLJavaScriptPython

POST /services/{serviceId}/applications HTTP/1.1
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 required document

post

Upload a document/attachment to receive a documentId that can be linked to applications when submitting a new registration

Query parameters

additionalMetadatastringOptional

Additional Metadata

Body

multipart/form-data

filestring · base64[]OptionalExample: V2UgbG92ZSBqc29uIQ==

Responses

200

File successfully uploaded

*/*

codeinteger · int32Optional

typestringOptional

messagestringOptional

urlstringOptional

400

Bad request, file upload failed

*/*

500

Internal server error, please contact administrator

*/*

post

/documents

HTTPcURLJavaScriptPython

POST /documents HTTP/1.1
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:

Retrieve all application files

get

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)

Query parameters

serviceIdstring · uuidOptional

id of a service to filter for applications of only this service

applicantIdstringOptional

Applicant user ID

Example: 42962de0-bdb2-11ed-9397-0242ac120004

firstResultintegerOptional

Pagination of results. Specifies the index of the first result to return.

Example: 1

maxResultintegerOptional

Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

Example: 10

sortBystringOptional

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.

Example: created

sortOrderstringOptional

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.

Example: asc

Header parameters

Information-Mediator-ClientstringRequired

Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM

Example: eGovStack/GOV/90000009/digitalregistries

Responses

200

list of applications or an empty array if none are available

*/*

fileIdstringOptional

Application file identifier 81c4445c-bff6-11ed-afa1-0242ac120002

Example: 81c4445c-bff6-11ed-afa1-0242ac120002

mainTaskIdstringOptionalExample: 42962de0-bdb2-11ed-9397-0242ac120004

taskTitlestringOptionalExample: Application xyz

roleIdstringOptionalExample: 42962de0-bdb2-11ed-9397-0242ac120004

roleNamestringOptionalExample: Registrar

assigneeIdstringOptional

operator ID who is processing the applicant file

Example: 42962de0-bdb2-11ed-9397-0242ac120004

operatorNamestringOptional

operator ID who has the task of processing the application file

Example: John Smith

applicantIdstringOptionalExample: 42962de0-bdb2-11ed-9397-0242ac120004

createdstring · date-timeOptional

Time when the application file was created by the user- Draft

Example: 2000-10-23T00:00:00.000Z

registeredstring · date-timeOptional

Time when the application file was registered in the Registration BB system

Example: 2000-10-23T00:00:00.000Z

descriptionstringOptionalExample: Any text.

serviceNamestringOptionalExample: Post partum registration service

serviceIdstring · uuidOptionalExample: 42962de0-bdb2-11ed-9397-0242ac120004

eformIdstringOptionalExample: 42962de0-bdb2-11ed-9397-0242ac120004

documentUrlsstring[]Optional

get

/applications

HTTPcURLJavaScriptPython

GET /applications HTTP/1.1
Information-Mediator-Client: text
Accept: */*

200

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": {}
      }
    }
  }
]

Get application file by ID

get

Returns application file

Path parameters

fileIdstringRequiredExample: 8a70cd6d-bdb2-11ed-9397-0242ac120004

Header parameters

Information-Mediator-ClientstringRequired

Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM

Example: eGovStack/GOV/90000009/digitalregistries

Responses

200

Returns application file by id

*/*

fileIdstringOptional

Application file identifier 81c4445c-bff6-11ed-afa1-0242ac120002

Example: 81c4445c-bff6-11ed-afa1-0242ac120002

registeredstring · date-timeOptional

Time when the application file was registered in the Registration BB system

Example: 2000-10-23T00:00:00.000Z

serviceIdstring · uuidRequired

id of the service this application relates to

serviceNamestringOptionalExample: Post partum registration service

endedbooleanOptional

True, if application file processing has ended

Example: false

404

Application file was not found

get

/applications/{fileId}

HTTPcURLJavaScriptPython

GET /applications/{fileId} HTTP/1.1
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"
    ]
  }
}

Update service application file with operator's form data

put

Returns updated service application file ID

Path parameters

fileIdstringRequired

Header parameters

Information-Mediator-ClientstringRequired

Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM

Example: eGovStack/GOV/90000009/digitalregistries

Body

application/json

applicationNamestringOptional

Free text application name

Example: Amya Yuko

applicantIdstringRequired

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.

Example: 42962de0-bdb2-11ed-9397-0242ac120004

createdstring · date-timeOptional

Time when the application file was created by the user- Draft

Example: 2000-10-23T00:00:00.000Z

documentUrlsstring[]Optional

Responses

200

Returns updated application file

*/*

fileIdstringOptional

Application file identifier 81c4445c-bff6-11ed-afa1-0242ac120002

Example: 81c4445c-bff6-11ed-afa1-0242ac120002

registeredstring · date-timeOptional

Time when the application file was registered in the Registration BB system

Example: 2000-10-23T00:00:00.000Z

serviceIdstring · uuidRequired

id of the service this application relates to

serviceNamestringOptionalExample: Post partum registration service

endedbooleanOptional

True, if application file processing has ended

Example: false

404

Application file was not found

500

Internal server error, please contact administrator

*/*

put

/applications/{fileId}

HTTPcURLJavaScriptPython

PUT /applications/{fileId} HTTP/1.1
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"
    ]
  }
}

Retrieve all tasks

get

Returns task list

Query parameters

mainTaskIdstringOptional

fileIdstringOptional

assigneeIdstringOptional

firstResultintegerOptional

Pagination of results. Specifies the index of the first result to return.

maxResultintegerOptional

Pagination of results. Specifies the maximum number of results to return. Will return less results if there are no more results left.

sortBystringOptional

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.

sortOrderstringOptional

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.

Responses

200

list of tasks or an empty array if none are available

*/*

taskIdstringOptional

mainTaskIdstringOptional

namestringOptional

assigneeIdstringOptional

roleIdstringOptional

createdstring · date-timeOptional

descriptionstringOptional

serviceIdstring · uuidOptional

serviceNamestringOptional

fileIdstringOptional

eFormIdstringOptional

get

/tasks

HTTPcURLJavaScriptPython

GET /tasks HTTP/1.1
Accept: */*

200

list of tasks or an empty array if none are available

[
  {
    "taskId": "text",
    "mainTaskId": "text",
    "name": "text",
    "assigneeId": "text",
    "roleId": "text",
    "created": "2026-03-14T08:31:18.662Z",
    "description": "text",
    "serviceId": "123e4567-e89b-12d3-a456-426614174000",
    "serviceName": "text",
    "fileId": "text",
    "eFormId": "text",
    "status": {
      "code": "PENDING",
      "title": "Pending"
    }
  }
]

Get task by id

get

Returns task by id

Path parameters

taskIdstringRequired

Responses

200

Returns task by id

*/*

taskIdstringOptional

taskNamestringOptional

assigneeIdstringOptional

roleIdstringOptionalExample: 42962de0-bdb2-11ed-9397-0242ac120004

createdstring · date-timeOptional

descriptionstringOptional

fileIdstringOptional

serviceIdstring · uuidOptional

serviceNamestringOptional

eFormIdstringOptional

404

Task hasn't found

get

/tasks/{taskId}

HTTPcURLJavaScriptPython

GET /tasks/{taskId} HTTP/1.1
Accept: */*

{
  "taskId": "text",
  "taskName": "text",
  "assigneeId": "text",
  "roleId": "42962de0-bdb2-11ed-9397-0242ac120004",
  "created": "2026-03-14T08:31:18.662Z",
  "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": {}
  }
}

Complete task by id

post

Path parameters

taskIdstringRequired

Body

application/json

Responses

200

Task successfully completed

*/*

taskIdstringOptional

fileIdstringOptional

serviceIdstring · uuidOptional

404

Task was not found

500

Internal server error, please contact administrator

*/*

post

/tasks/{taskId}/complete

HTTPcURLJavaScriptPython

POST /tasks/{taskId}/complete HTTP/1.1
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):

get

API endpoint that allows anyone to see service statistics

Query parameters

startDatestring · dateOptional

Start date of statistics

Example: 2021-01-30

endDatestring · dateOptional

End date of statistics

Example: 2021-01-30

registrationNamestringOptional

Name of registration

Example: MCTS

operatorstringOptional

Name of operator

Example: Ingmar Vali

rolestringOptional

Role of the operator

Example: Handler

timeframestring · enumOptional

Timerame:

• day - timeframe value = day
• week - timeframe value = week
• month - timeframe value = month
• year - timeframe value = year

Possible values:

Header parameters

Information-Mediator-ClientstringRequired

Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM

Example: eGovStack/GOV/90000009/eregistrations-dev

Responses

200

Success Response

application/json

Array of found person data requests

processedintegerOptional

How many applications was processed

Example: 100

approvedintegerOptional

How many applications was approved

Example: 90

sentBackintegerOptional

How many applications was sent back

Example: 3

rejectedintegerOptional

How many applications was rejected

Example: 7

400

Invalid input supplied

404

Requests not found

get

/data/statistics

HTTPcURLJavaScriptPython

GET /data/statistics HTTP/1.1
Information-Mediator-Client: text
Accept: */*

[]