/
Custodianship Service

Custodianship Service

Overview

Custodianship is a feature we facilitate for users who need to have a guardian oversee their online actions. Users under custodianship are not legally allowed to use our services.

Freja allows Relying parties (RP) to get custodianship information on users.

A typical use of this option would be to check whether or not a certain user is allowed to use their services before providing the service.

There is a possibility that the user has been given a custodian, but the custodianship has not been registered with Freja yet.

In order to be able to use this API, you must first get in touch with partnersupport@frejaeid.com

Get User Custodianship Status Method

This method is used by a relying party to check the custodianship status for a specific user. The existing user information for that user in the Freja eID system must be passed as a parameter of this method.

The method is called using HTTP POST through the URLs below:

System

Method endpoints

System

Method endpoints

Test

https://services.prod.frejaeid.com/custodianship/user/1.0/getCustodianshipStatus

Production

https://services.prod.frejaeid.com/custodianship/user/1.0/getCustodianshipStatus

JSON Example for setCustomIdentifierRequest

The parameter of the method is a Base64 UTF8-encoded JSON payload, according to the following:

{ "userCountryIdAndCrn":"SEYYYYMMDDXXXX" }

  • userCountryIdAndCrn: string, mandatory. String value is the user's registered Country ID and SSN (end user's social security number).

    • country ID: string, mandatory. Contains the ISO-3166 two-alphanumeric country code of the country where the SSN is issued. In the current version of Freja it must be "SE".

    • ssn: string, mandatory. Expected SSN of the end user as per pre-registration. If country is "SE", the value must be the 12-digit format of the Swedish "personnummer" without spaces or hyphens.

SSN userInfoType Example Request

If you wish to check the custodianship status for a user with an SSN YYYYMMDDXXXX, follow these steps:

  1. Create the JSON structure {"userCountryIdAndCrn":"SE199004101234"}

  2. Encode the JSON structure to Base64.

  3. Create the HTTP POST request with a POST parameter name getCustodianshipStatusRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following:

getCustodianshipStatusRequest=eyJ1c2VyQ291bnRyeUlkQW5kQ3JuIjoiU0UyMDIzMDQxMDM5MzYifQ==

Possible Errors

Return code

Explanation

Return code

Explanation

1002

Invalid or missing userInfo.

1008 

Unknown relying party.

1010

JSON request cannot be parsed.

1013

You are not allowed to request user custodianship information.

1014

Invalid user CRN, CRN missing or user country code is not SE. (The CRN is the equivalent of an SSN)

JSON Response Value

If HTTP 200 is returned from the method, the following return value will be present in the body of the response:

{ "custodianshipStatus":"Custodianship status value" }

  • custodianshipStatus: String, mandatory. User's current custodianship status.

    Can be value of: 

    • "UNKNOWN" 

    • "USER_UNDER_CUSTODIANSHIP"

    "UNKNOWN" value is returned if it is not known if there is a custodian registered for the user. As said before, there is still a possibility the user has been given a legal custodian that has not yet been registered with Freja at this time so we cannot guarantee the user's custodianship status.

    "USER_UNDER_CUSTODIANSHIP" is returned if we have a registered custodian for the user registered in Freja.