Table of contents
Requesting information about the family status
The “Certification- Family Status” e-service published in the catalog offers a service through which it is possible to verify the correctness of the information related to a family status, simulating an institution that has the updated and centralized information related to the family status.
This tutorial shows an actual case of using this service.
The use case
As a user, I need to verify the information present in my database and related to the family status of the subjects. To do so, I must subscribe to the “Certification - Family Status” e-service, which makes it possible to recover this data through the invocation of the following API:
POST /family-status
Data Preparation
The first thing to do, as we have seen, is to configure the data. Therefore we will proceed, for the first time, with the Data Preparation phase.
In reference to the problem indicated above, in this example we have the following database in our application
| ID | Name | Surname | Civil status | Relationship start date | Relationship end date |
|---|---|---|---|---|---|
| RSSMRA80A01H501U | Mario | Rossi | MARRIED | 01/01/2022 | NULL |
| LGUBCH80A01H501B | Luigi | Bianchi | SINGLE | 01/06/1988 | NULL |
Based on this, data preparation is performed by simulating the following scenario:
● The ID RSSMRA80A01H501U is a subject for which the family status is known as MARRIED
● The ID LGUBCH80A01H501B is a subject for which the family status is known as SINGLE
We can replicate the desired configuration as follows:
POST /family-status
Header:
1Content-Type: application/json
2Authorization: Bearer {{bearerToken}}
3x-correlation-id: {{myUniqueCorrelationId}}
4Payload:
1application/json
2{
3 "subject": {
4 "subjectId": "RSSMRA80A01H501U",
5 "id": "123",
6 "surname": "Rossi",
7 "name": "Mario",
8 "gender": "M",
9 "birthDate": {
10 "eventDate": "1970-11-15",
11 "placeOfBirth": {
12 "municipality": {
13 "nameMunicipality": "Roma",
14 "istatCode": "123456",
15 "acronymIstatProvince": "RM",
16 "placeDescription": "N/D"
17 },
18 "place": {
19 "placeDescription": "N/D",
20 "countryDescription": "N/D",
21 "codState": "ITA",
22 "provinceCounty": "N/D"
23 }
24 }
25 }
26 },
27 "subjectLink": {
28 "relationshipType": "Spouse",
29 "startDate": "2021-11-15",
30 "relationshipCode": "SPOUSE",
31 "memberSequence": "01",
32 "startDateRelationship": "2022-01-01"
33 }
34}
35Response:
1application/json
2{
3 "uuid": "2c41e733-e9ae-4b69-9243-6217d4cf26e3"
4}
5Status codes:
● 200 - Configuration saved successfully
The second subject can now be registered, simulating that the provider knows the address.
Header:
1Content-Type: application/json
2Authorization: Bearer {{bearerToken}}
3x-correlation-id: {{myUniqueCorrelationId}}
4Payload:
1application/json
2{
3 "subject": {
4 "subjectId": "LGUBCH80A01H501B",
5 "id": "1234",
6 "surname": "Luigi",
7 "name": "Bianchi",
8 "gender": "M",
9 "birthDate": {
10 "eventDate": "1988-06-01",
11 "placeOfBirth": {
12 "municipality": {
13 "nameMunicipality": "Roma",
14 "istatCode": "123456",
15 "acronymIstatProvince": "RM",
16 "placeDescription": "N/D"
17 },
18 "place": {
19 "placeDescription": "N/D",
20 "countryDescription": "N/D",
21 "codState": "ITA",
22 "provinceCounty": "N/D"
23 }
24 }
25 }
26 },
27 "subjectLink": {
28 "relationshipType": "Spouse",
29 "startDate": "2023-07-01",
30 "relationshipCode": "SPOUSE",
31 "memberSequence": "01",
32 "startDateRelationship": "1988-06-01"
33 }
34}
35Response:
1application/json
2{
3 "uuid": "2456398c-e932-4e97-a7b9-f9f15e9c343f"
4}
5Status codes:
● 200 - Configuration saved successfully
Given our scenario, we have completed the configuration phase.
At this point we can invoke the APIs provided by the e-service.
E-service invocation
Once the completion phase is completed, proceed with the invocation of the service performing the verification for the two subjects in my database.
Specifically, we will verify the correctness of the information by invoking the following API
POST /family-status
that allows us to recover the information using the ID of the subject.
Before invoking the above, it is important to know that the e-service in question requires another level of security. The APIs require in fact two additional headers to be sent:
After correctly generating the above tokens and the voucher, we can proceed with the following requests.
First of all we will invoke the e-service for the subject “Mario Rossi”
1curl --location '{host}/family-status' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'x-correlation-id: 123' \
5--header 'agid-jwt-signature: zzz' \
6--header 'agid-jwt-trackingevidence: yyy' \
7--header 'Authorization: Bearer xxx' \
8--data '{
9 "operationId": "001",
10 "criteria": {
11 "subjectId": "RSSMRA80A01H501U"
12 },
13 "requestData": {
14 "dateOfRequest": "2024-11-13",
15 "useCase": "Verification motivation",
16 "motivation": "Verification information"
17 }
18}'
19Response:
1application/json
2{
3 "idOp": "001",
4 "subjects": {
5 "subject": [
6 {
7 "generality": {
8 "subjectId": {
9 "subjectId": "RSSMRA80A01H501U",
10 "subjectIdValidity": "",
11 "dataAttributionValidity": ""
12 },
13 "surname": "Rossi",
14 "noSurname": "false",
15 "name": "Mario",
16 "noName": "false",
17 "gender": "M",
18 "birthDate": "1970-11-15",
19 "noDay": "",
20 "noMonth": "",
21 "placeOfBirth": {
22 "municipality": {
23 "nameMunicipality": "Roma",
24 "istatCode": "123456",
25 "acronymIstatProvince": "RM",
26 "placeDescription": "N/D"
27 },
28 "place": {
29 "placeDescription": "N/D",
30 "countryDescription": "N/D",
31 "codState": "ITA",
32 "provinceCounty": "N/D"
33 }
34 },
35 "AIRESubject": "",
36 "yearExpatriation": "",
37 "idSubjectData": "",
38 "note": ""
39 },
40 "subjectLink": {
41 "relationshipType": "Spouse",
42 "startDate": "2021-11-15",
43 "relationshipCode": "SPOUSE",
44 "memberSequence": "01",
45 "startDateRelationship": "2022-01-01"
46 }
47 }
48 ]
49 }
50}
51Status codes:
● 200 - Request made successfully
Now we will proceed with “Luigi Bianchi”
1curl --location '{host}/family-status' \
2--header 'Content-Type: application/json' \
3--header 'Accept: application/json' \
4--header 'x-correlation-id: 123' \
5--header 'agid-jwt-signature: zzz' \
6--header 'agid-jwt-trackingevidence: yyy' \
7--header 'Authorization: Bearer xxx' \
8--data '{
9 "operationId": "002",
10 "criteria": {
11 "subjectId": "LGUBCH80A01H501B"
12 },
13 "requestData": {
14 "dateOfRequest": "2024-11-13",
15 "useCase": "Verification motivation",
16 "motivation": "Verification information"
17 }
18}'
19Response:
1application/json
2{
3 "idOp": "002",
4 "subjects": {
5 "subject": [
6 {
7 "generality": {
8 "subjectId": {
9 "subjectId": "LGUBCH80A01H501B",
10 "subjectIdValidity": "",
11 "dataAttributionValidity": ""
12 },
13 "surname": "Luigi",
14 "noSurname": "false",
15 "name": "Bianchi",
16 "noName": "false",
17 "gender": "M",
18 "birthDate": "1988-06-01",
19 "noDay": "",
20 "noMonth": "",
21 "placeOfBirth": {
22 "municipality": {
23 "nameMunicipality": "Roma",
24 "istatCode": "123456",
25 "acronymIstatProvince": "RM",
26 "placeDescription": "N/D"
27 },
28 "place": {
29 "placeDescription": "N/D",
30 "countryDescription": "N/D",
31 "codState": "ITA",
32 "provinceCounty": "N/D"
33 }
34 },
35 "AIRESubject": "",
36 "yearExpatriation": "",
37 "idSubjectData": "",
38 "note": ""
39 },
40 "subjectLink": {
41 "relationshipType": "Spouse",
42 "startDate": "2023-07-01",
43 "relationshipCode": "SPOUSE",
44 "memberSequence": "01",
45 "startDateRelationship": "1988-06-01"
46 }
47 }
48 ]
49 }
50}
51Status codes:
● 200 - Request made successfully
The received responses allow us to coherently update our database.
Final result
After querying the e-service, we can update our database based on the information we recovered.
An overview of the situation following the update is shown below
| ID | Name | Surname | Civil status | Relationship start date | Relationship end date |
|---|---|---|---|---|---|
| RSSMRA80A01H501U | Mario | Rossi | MARRIED | 01/01/2022 | NULL |
| LGUBCH80A01H501B | Luigi | Bianchi | MARRIED | 01/07/2023 | NULL |
Our database was updated correctly. Specifically, it was confirmed that the information for the subject RSSMRA80A01H501U is correct, whereas for the second subject the relationship related to their family status was updated.
