{
   "userInfoType":"User info type",
   "userInfo":"User information corresponding to user info type",
   "minRegistrationLevel":"Minimum required registration level of a user",
   "expiry":"Expiry time for the request",
   "organisationId":{
      "title":"Title of the Organisation ID to be displayed to the end user",
      "identifierName":"Name of specific organisation identifier",
      "identifier":"Value of specific organisation identifier",
      "identifierDisplayTypes": ["QR_CODE","TEXT"],
      "additionalAttributes": [{"key":"attribute_key",
                                "displayText":"attribute_display_name",
                                "value":"attribute_value"}
                              ]
   }
}

userInfoType: string, mandatory. Describes the type of user information supplied to identify the end user. Currently one of:

• PHONE (end user's telephone number)
• EMAIL (end user's email)
• SSN (end user's social security number)
• INFERRED (the user need not enter any identifier, their identity will be determined as a result of the authentication process). The INFERRED method is typically used in conjunction with QR codes. 

userInfo: string, mandatory, 256 characters maximum. If userInfoType is EMAIL or PHONE, interpreted as a string value of the email or telephone number of the end user, respectively. If userInfoType is SSN, then it must be a Base64 encoding of the ssnuserinfo JSON structure described below. 

{
   "country":"Country of SSN",
   "ssn":"Social security number of the end user"
}

country: string, mandatory. Contains the ISO-3166 two-alphanumeric country code of the country where the SSN is issued. In the current version of Freja eID, one of: ''SE'' (Sweden), ''NO'' (Norway), ''FI'' (Finland), ''DK'' (Denmark).
ssn: string, mandatory. Expected SSN of the end user as per pre-registration.

• If country equal to "SE", the value must be the 12-digit format of the Swedish "personnummer" without spaces or hyphens. Example: 195210131234.
• If country equal to ''NO'', the value must be the 11-digit format of the Norwegian "personnummer" without spaces or hyphens. Example: 13105212345.
• If country equal to ''FI'', the value must be the 10-characters format of the Finish ''koodi'', with the hyphen before the last four control characters. Hyphen can be replaced with the letter A. Example format: 131052-308T or 131052A308T.
• If country equal to ''DK'', the value must be the 10-digit format of the Danish "personnummer" without spaces or hyphens. Example: 1310521234.

minRegistrationLevel: string, optional. Minimum required registration level of a user in order to approve/decline transaction for adding Organisation eID. Can be EXTENDED or PLUS. If not present, default level will be EXTENDED.

expiry: long, optional. Describes the time until which the Relying Party is ready to wait for the user to confirm the initAddOrganisationId request. Expressed in milliseconds since January 1, 1970, 00:00 UTC. Minimum value is current time +2 minutes, maximum value is current time +30 days. If not present, defaults to current time +7 days.

organisationId

{
   "title":"Title of the Organisation ID to be displayed to the end user",
   "identifierName":"Name of specific organisation identifier",
   "identifier":"Value of specific organisation identifier",
   "identifierDisplayTypes": ["QR_CODE","TEXT"],
   "additionalAttributes":[{"key":"attribute_key",
                            "displayText":"attribute_display_name",
                            "value":"attribute_value"}
                          ]
}

title: string, mandatory, 64 characters maximum. The title of the Organisation ID which will be displayed to the end user in the app, on the Organisation ID card and the Organisation ID screen itself.

identifierName: string, mandatory, 30 characters maximum. The name of the specific organisation identifier to be set for the end user. 

identifier: string, mandatory, 128 characters maximum. The value of the specific organisation identifier to be set for the end user. Must be unique within the requesting relying party system inside the Freja eID service.

identifierDisplayTypes: identifierDisplayTypes: list of identifier types, optional. Can be QR_CODE or TEXT, both or neither. If QR_CODE value is provided in the list, the identifier in the Org ID screen in Freja app will be displayed as QR rather than as a text. Default value is TEXT.

additionalAttributes: list of Organisation ID attributes, optional. The maximum number of additional attributes is 10. One attribute contains the key (maximum 64 characters), displayText as friendly name (maximum 64 characters) and value (maximum 256 characters), displayTypes which are not supported yet.

If you wish to initiate an 'Add Organisation ID' request for a user with an email address joe.black@verisec.com, follow these steps:

1. Create the JSON structure {"userInfoType":"EMAIL","userInfo":"joe.black@verisec.com","minRegistrationLevel":"EXTENDED","expiry":1517526000000,"organisationId": { "title":"Verisec ID", "identifierName":"Domain name", "identifier":"vejodoe" }}
2. Encode the JSON structure to Base64.
3. Create the HTTP POST request with a POST parameter name initAddOrganisationIdRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following (compact format, line broken for clarity only):

initAddOrganisationIdRequest=eyJ1c2VySW5mb1R5cGUiOiJFTUFJTCIsInVzZXJJbmZvIjoi
am9lLmJsYWNrQHZlcmlzZWMuY29tIiwibWluUmVnaXN0cmF0aW9uTGV2ZWwiOiJFWFRFTkRFRCIsI
mV4cGlyeSI6MTUxNzUyNjAwMDAwMCwib3JnYW5pc2F0aW9uSWQiOiB7ICJ0aXRsZSI6IlZlcmlzZW
MgSUQiLCAiaWRlbnRpZmllck5hbWUiOiJEb21haW4gbmFtZSIsICJpZGVudGlmaWVyIjoidmVqb2R
vZSIgfX0=

{
   "orgIdRef":"Organisation ID reference"
}

orgIdRef: string, mandatory. The value must be equal to a reference previously returned from a call to the Initiate Add Organisation ID method. The time period during which a specific reference is available for checking will depend on the longevity of the operation (see the expiry parameter in the Initiate Add Organisation ID method) and is calculated as the expiry time plus 3 days.

{
   "orgIdRef":"Organisation ID reference",
   "status":"Status of Organisation ID transaction",
   "details":"Signed data, see below"
}

orgIdRef: string, mandatory. The reference of the Add Organisation ID request.

status: string, mandatory. One of:

• STARTED (the transaction has been started but not yet delivered to the user's Freja eID application),
• DELIVERED_TO_MOBILE (the Freja eID app has received the transaction),
• CANCELED (the end user declined the 'Add Organisation ID' request), 
• RP_CANCELED (the 'Add Organisation ID' request was sent to the user but cancelled by the Relying Party before the user could respond),
• EXPIRED (the 'Add Organisation ID' request was not approved by the user within the set time frame),
• APPROVED (the end user has approved the 'Add Organisation ID' request).
  

details: A signed object (see below), optional. Provides details and evidence of the signing if status was equal to APPROVED.

The content of this response element will contain a JWS in compact serialised form as following:

BASE64URL(UTF8(JWS Protected Header)) || ’.’ || BASE64URL(JWS Payload) || ’.’ || BASE64URL(JWS Signature)

JWS Protected Header

{
   "x5t":"SHA-1 digest of the signing certificate",
   "alg":"Algorithm used to secure the JWS"
}

x5t: mandatory, Base64URL encoding of the certificate's SHA-1 digest.
alg: mandatory, the value shall be RS256 which corresponds to 'RSA PKCS#1 signature with SHA-256'.

JWS Payload

{
   "orgIdRef":"Organisation ID reference",
   "status":"Status of Organisation ID transaction",
   "userInfoType":"User info type",
   "userInfo":"User information corresponding to user info type",
   "minRegistrationLevel":"Minimum required registration level of a user",
   "timestamp":"Time when transaction was approved by end user",
   "signatureType":"Signature type",
   "signatureData":{
      "userSignature":"The signature produced by the end user",
      "certificateStatus":"Evidence of end-users certificate status"
   }
}

orgIdRef: See orgIdRef above.

status: See status above.

userInfoType: See userInfoType as described in Initiate Add Organisation ID method.

userInfo: See userInfo as described in Initiate Add Organisation ID method.

minRegistrationLevel: See registrationLevel as described in Initiate Add Organisation ID method.

timestamp: long, mandatory. Describes the time when the confirmation by the end user was validated on Freja eID server side. Expressed in milliseconds, since January 1, 1970, 00:00 UTC.

signatureType: string, mandatory. For the Organisation ID service, this field has value SIMPLE. See signatureType as described in Signature Services.

signatureData: see fields below, mandatory.

userSignature: the produced signature, string, mandatory. Contains the user's signature in the requested format. The user's signature will implicitly contain the signed text which will contain Organisation ID identifier set to the user.

certificateStatus: Base64 string, mandatory. Contains the OCSP response regarding the state of the user certificate at the time of validating the signature.

{
   "orgIdRef":"Organisation ID reference"
}

orgIdRef: string, mandatory. The value must be equal to an Organisation ID reference previously returned from a call to the Initiate Add Organisation ID method.

If you wish to cancel an Add Organisation ID request, follow these steps:

1. Create the JSON structure {"orgIdRef":"TrLA9zdxCBlNOQNvkdhAM14mJmlL20digC7+QgEVRwmE7SH8Qm0swWIc6whfKm4Y"}
2. Encode the JSON structure to Base64.
3. Create the HTTP POST request with a POST parameter name cancelAddOrganisationIdRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following (line broken for clarity only):

cancelAddOrganisationIdRequest=eyJvcmdJZFJlZiI6IlRyTEE5emR4Q0JsTk9RTnZrZGhBTTE
0bUptbEwyMGRpZ0M3K1FnRVZSd21FN1NIOFFtMHN3V0ljNndoZkttNFkifQ==

If you wish to update an Organisation ID, follow these steps:

1. Create the JSON structure {"identifier": "vejodoe","additionalAttributes":[{"key": "exampleKey","displayText": "Example display text","value": "Value of attribute"}]} 
2. Encode the JSON structure to Base64.
3. Create the HTTP POST request with a POST parameter name updateOrganisationIdRequest and the Base64 encoded JSON structure from the step 2 as its value.

The HTTP body should be the following (line broken for clarity only):