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)

Listing of all services with basic information

get

/services

Query parameters

namestring

Example: Register Mother and Child

Responses

application/json

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/services'

200

500

200

[
  {
    "id": "f7d33db0-2809-484e-a780-76b7ccd4ecbf",
    "name": "Mother and Child Registration",
    "version": "123",
    "isExecutable": true,
    "isClosed": true,
    "description": "text",
    "serviceBody": [
      {
        "code": "text",
        "value": "text"
      }
    ],
    "type": "None"
  }
]

list of services or an empty array if none are available

returns detailed information about a service

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

get

/services/{serviceId}

Path parameters

serviceIdstring · uuidrequired

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

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

Responses

application/json

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/services/{serviceId}'

200

404

500

200

{
  "id": "f7d33db0-2809-484e-a780-76b7ccd4ecbf",
  "name": "Mother and Child Registration",
  "version": "123",
  "isExecutable": true,
  "isClosed": true,
  "description": "text",
  "serviceBody": [
    {
      "code": "text",
      "value": "text"
    }
  ],
  "type": "None"
}

Service found and representation returned

Retrieve all available e-forms

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

get

/services/{serviceId}/eForms

Path parameters

serviceIdstring · uuidrequired

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

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

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/services/{serviceId}/eForms'

200

200

[
  {
    "eFormId": "d98a205a-679b-485b-823d-7a32a391e744",
    "name": "FORM",
    "description": "text",
    "version": "1",
    "latest": true
  }
]

list of eForms or an empty array if none are available

Retrieve a specific e-form by ID

get

/eForms/{eFormId}

Path parameters

eFormIdstringrequired

The ID of the e-form to retrieve

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/eForms/{eFormId}'

200

404

200

{
  "eFormId": "d98a205a-679b-485b-823d-7a32a391e744",
  "name": "A1",
  "description": "text",
  "version": "1",
  "latest": true,
  "schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

OK

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

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

post

/services/{serviceId}/applications

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

applicationNamestring

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-time

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

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

formDataobject

documentUrlsstring[]

Responses

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/services/{serviceId}/applications' \
  --header 'Information-Mediator-Client: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "applicationName": "Amya Yuko",
    "applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "created": "2000-10-23T00:00:00.000Z",
    "formData": {
      "eFormId": "42962de0-bdb2-11ed-9397-0242ac120004",
      "data": {
        "ANY_ADDITIONAL_PROPERTY": {}
      }
    },
    "documentUrls": [
      "text"
    ]
  }'

200

404

500

200

{
  "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": {
    "title": "Pending",
    "code": "PENDING"
  },
  "ended": "false",
  "applicationData": {
    "applicationName": "Amya Yuko",
    "applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "created": "2000-10-23T00:00:00.000Z",
    "formData": {
      "eFormId": "42962de0-bdb2-11ed-9397-0242ac120004",
      "data": {
        "ANY_ADDITIONAL_PROPERTY": {}
      }
    },
    "documentUrls": [
      "text"
    ]
  }
}

Returns started application file ID

Upload a required document

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

post

/documents

Query parameters

additionalMetadatastring

Additional Metadata

Body

filestring · base64[]

Responses

*/*

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/documents' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file=V2UgbG92ZSBqc29uIQ=='

200

400

500

200

{
  "code": 1,
  "type": "text",
  "message": "text",
  "url": "text"
}

File successfully uploaded

8.2 Processing of Registrations

Operators can access and process existing application files:

Retrieve all 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)

get

/applications

Query parameters

serviceIdstring · uuid

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

applicantIdstring

Applicant user ID

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

firstResultinteger

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

Example: 1

maxResultinteger

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

Example: 10

sortBystring

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

sortOrderstring

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

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/applications' \
  --header 'Information-Mediator-Client: text'

200

200

[
  {
    "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": {
      "title": "Pending",
      "code": "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": {}
      }
    }
  }
]

list of applications or an empty array if none are available

Get application file by ID

Returns application file

get

/applications/{fileId}

Path parameters

fileIdstringrequired

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

Header parameters

Information-Mediator-Clientstringrequired

Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM

Example: eGovStack/GOV/90000009/digitalregistries

Responses

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/applications/{fileId}' \
  --header 'Information-Mediator-Client: text'

200

404

200

{
  "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": {
    "title": "Pending",
    "code": "PENDING"
  },
  "ended": "false",
  "applicationData": {
    "applicationName": "Amya Yuko",
    "applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "created": "2000-10-23T00:00:00.000Z",
    "formData": {
      "eFormId": "42962de0-bdb2-11ed-9397-0242ac120004",
      "data": {
        "ANY_ADDITIONAL_PROPERTY": {}
      }
    },
    "documentUrls": [
      "text"
    ]
  }
}

Returns application file by id

Update service application file with operator's form data

Returns updated service application file ID

put

/applications/{fileId}

Path parameters

fileIdstringrequired

Header parameters

Information-Mediator-Clientstringrequired

Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM

Example: eGovStack/GOV/90000009/digitalregistries

Body

applicationNamestring

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-time

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

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

formDataobject

documentUrlsstring[]

Responses

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request PUT \
  --url '/applications/{fileId}' \
  --header 'Information-Mediator-Client: text' \
  --header 'Content-Type: application/json' \
  --data '{
    "applicationName": "Amya Yuko",
    "applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "created": "2000-10-23T00:00:00.000Z",
    "formData": {
      "eFormId": "42962de0-bdb2-11ed-9397-0242ac120004",
      "data": {
        "ANY_ADDITIONAL_PROPERTY": {}
      }
    },
    "documentUrls": [
      "text"
    ]
  }'

200

404

500

200

{
  "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": {
    "title": "Pending",
    "code": "PENDING"
  },
  "ended": "false",
  "applicationData": {
    "applicationName": "Amya Yuko",
    "applicantId": "42962de0-bdb2-11ed-9397-0242ac120004",
    "created": "2000-10-23T00:00:00.000Z",
    "formData": {
      "eFormId": "42962de0-bdb2-11ed-9397-0242ac120004",
      "data": {
        "ANY_ADDITIONAL_PROPERTY": {}
      }
    },
    "documentUrls": [
      "text"
    ]
  }
}

Returns updated application file

Retrieve all tasks

Returns task list

get

/tasks

Query parameters

mainTaskIdstring

fileIdstring

assigneeIdstring

firstResultinteger

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

maxResultinteger

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

sortBystring

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.

sortOrderstring

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

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/tasks'

200

200

[
  {
    "taskId": "text",
    "mainTaskId": "text",
    "name": "text",
    "assigneeId": "text",
    "roleId": "text",
    "created": "2025-02-28T12:05:36.450Z",
    "description": "text",
    "serviceId": "123e4567-e89b-12d3-a456-426614174000",
    "serviceName": "text",
    "fileId": "text",
    "eFormId": "text",
    "status": {
      "title": "Pending",
      "code": "PENDING"
    }
  }
]

list of tasks or an empty array if none are available

Get task by id

Returns task by id

get

/tasks/{taskId}

Path parameters

taskIdstringrequired

Responses

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/tasks/{taskId}'

200

404

200

{
  "taskId": "text",
  "taskName": "text",
  "assigneeId": "text",
  "roleId": "42962de0-bdb2-11ed-9397-0242ac120004",
  "created": "2025-02-28T12:05:36.450Z",
  "description": "text",
  "fileId": "text",
  "serviceId": "123e4567-e89b-12d3-a456-426614174000",
  "serviceName": "text",
  "eFormId": "text",
  "status": {
    "title": "Pending",
    "code": "PENDING"
  },
  "formVariables": {
    "ANY_ADDITIONAL_PROPERTY": {}
  },
  "data": {
    "ANY_ADDITIONAL_PROPERTY": {}
  }
}

Returns task by id

Complete task by id

post

/tasks/{taskId}/complete

Path parameters

taskIdstringrequired

Body

dataobject

Responses

*/*

*/*

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url '/tasks/{taskId}/complete' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": {
      "ANY_ADDITIONAL_PROPERTY": {}
    }
  }'

200

404

500

200

{
  "taskId": "text",
  "fileId": "text",
  "serviceId": "123e4567-e89b-12d3-a456-426614174000",
  "status": {
    "title": "Pending",
    "code": "PENDING"
  },
  "variables": {
    "ANY_ADDITIONAL_PROPERTY": {
      "data": {
        "ANY_ADDITIONAL_PROPERTY": {}
      }
    }
  }
}

Task successfully completed

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

get

/data/statistics

Query parameters

startDatestring · date

Start date of statistics

Example: 2021-01-30

endDatestring · date

End date of statistics

Example: 2021-01-30

registrationNamestring

Name of registration

Example: MCTS

operatorstring

Name of operator

Example: Ingmar Vali

rolestring

Role of the operator

Example: Handler

timeframestring · enum

Timerame:

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

Options: day, week, month, year

Header parameters

Information-Mediator-Clientstringrequired

Format is: INSTANCE/CLASS/MEMBER/SUBSYSTEM

Example: eGovStack/GOV/90000009/eregistrations-dev

Responses

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --url '/data/statistics' \
  --header 'Information-Mediator-Client: text'

200

400

404

200

[]

Success Response