...
No | Changes | Date |
1 | Remove membership payment and active membership payment entity messages from section Entities Posted to Queue Remove payment entity JSON schema for membership payment and active membership payment in section Entities JSON schema | 6. February 2020 |
2 | In POST Membership, SSN would not be mandatory. In POST Membership, NationalityID would be used to decide is membership request for Norwegian or Foreign member. List of Membership Status IDs updated with descriptions. ToOrgtype JSON added | 11. March 2020 |
3 | Added description of how to generate developerUserID Updated simplified flow for the membership Updated person merge with all messages related to person merge | 22. May 2020 |
4 | Updated person merge message sequence as per new implementation | 23. June 2020 |
5 | Specify MembershipRequest-guidelines for 3.party Remove SSN in MembershipRequest | 14. October 2020 |
6 | Added sections for Corporate Sports APIs | 11. December 2020 |
7 | Added support for Allidrett | 5. March 2021 |
8 | Extended response in PaymentDetails | 1. April 2022 |
9 | Extended response in POST Membership (add). Response contains Email address and MobilePhone number the UserVerification is sent to. | 14. March 2023 |
10 | Removed trailing spcae from Email address in response from POST Membership (add). Bug fix. | 14. April 2023 |
11 | Both Email address and MobilePhone number required in POST Membership (add) | 14. April 2023 |
Introduction
This document covers the API definitions developed by Norges idrettsforbund og olympiske og paralympiske komité (NIF). NIF API products consists of a set of RESTful services.
...
For any 3. party to connect to and consume NIF APIs, the request must go through the following stages:
Identification
Authentication
Authorization
Identification
A 3.party must be registered with NIF to be correctly identified. When registered, the main contact person at the 3.party receives an invitation email to the NIF API developer portal.
...
Property | Type | Value |
ObjectId | int | Id of the entity |
EntityName | string | Name of the entity. |
ChangeType | Change type enumeration | 1 - Added 2 - Modified 3 - Deleted 9 - Informational |
Note:
Messages with change types ‘Added’ or ‘Modified’ have delta object schema and data.
Informational messages will always have a full object schema and data.
Message Body
The message body contains the JSON message defined in Queue Message Structure.
...
Method | API Endpoint | Description |
GET | api/v{version}/auth/token/{clubId} | Allows 3.partiesr to get authorization token to be used for subsequent API requests. This API must can be called from the Developer portal of Azure API Management. |
...
Method | API Endpoint | Description |
GET | /api/v{version}/organization/structure | Gets the organization structure (branches) of club along with its details. Allidrett: |
Resource Information
Response Format | JSON |
Requires Authentication | Yes |
...
| Code | Type | Text | Description |
1 | 200 | Success |
| Clubs, groups and branch(es) |
Response Example
| Code Block |
|---|
{
"clubId": "1111111",
"clubName": "Heming Idrettslaget",
"describingName": "Heming Idrettslaget",
"email": "office@mailinator.no",
"city": "Oslo",
"county": "Norway",
"longitude": "72.5714° E",
"latitude": "23.0225° N",
"groups": [
{
"groupId": "221333",
"groupName": "Heming, IL - Alpint",
"describingName": "Heming, IL - Alpint",
"sportId": "32",
"sportName": "Ski",
"branches": [
{
"describingName": "Heming, IL - Alpint",
"sportId ": "132",
"sportName": "Alpint",
"branchId": "221333",
"branchName": "Heming, IL - Alpint"
},
{
"branchId": "211424",
"branchName": "Heming, IL - Hopp",
"describingName": "Heming, IL - Hopp",
"sportId": "129",
"sportName": "Hopp"
}
]
}
]
} |
Company
Request Headers
...
...
Name
...
Required
...
Description
...
Example
...
Company Sports API
Overview
Method | API Endpoint | Description |
GET | /api/v{version}/organization/structure | Gets the organization structure (branches) of Corporate Sports Club’s along with its details. |
Resource Information
Response Format | JSON |
Requires Authentication | Yes |
Request Headers
| Name | Required | Description |
1 | ClubId | Yes | Club Id for which API is being requested. Pass Corporate Sport club’s ID here to get the org structure for Corporate Sport club. |
2 | Authorization | Yes | This will be the token defining access for the on-boarded club. |
3 | Ocp-Apim-Subscription-Key | Yes | API management’s subscription key. Each |
3.party is provided a separate and unique key. |
Response Codes
| Code | Type | Text | Description |
1 | 200 | Success |
| Clubs, groups and branch(es) |
Response Example
{
...
| Code Block |
|---|
{ "clubId": 16235, |
...
"clubName": "PetrOl B.I.L.", |
...
"describingName": "PetrOl B.I.L.", |
...
"email": " |
...
franziska. |
...
blystad@npd. |
...
no", |
...
"city": |
...
External Membership API
Overview
...
Method
...
API Endpoint
...
Description
...
POST
...
/api/v{version}/membership
Allows adding a membership for Norwegian or foreign persons using POST Membership.
Membership represents the connection of a person with a club and/or its branch for a specific sport.
If a person´s nationality is Norwegian, membership request would be considered as Norwegian person request, otherwise request would be considered as a foreign person request.
The API adds branch level membership data. It will also add club level membership.
If clubId is passed in the request the API adds club level membership. If a branchId is passed, the request adds branch level membership.
Allidrett:
For allidrett, a groupId has to be passed. The accepted groups for allidrett can be fetched using the GetOrgStructure API. When allidrett groupId is passed, the request will add group level membership for allidrett.
If the Person already exists in the third party membership solution, the PersonId should be sent in the AddMembership-request.
When the membership request contains PersonId then all the information is fetched from NIF by using PersonId.
If PersonId is not passed in the request, the person is searched for, based on first name, last name, date of birth, gender, postal code and nationality.
If no result in this search, a new person will attempt to be created. If the data is imprecise or wrong, and the person most likely already exists, a failure in user verification will arise when end user tries to validate with SSN.
If the PersonId is sent and the response is “invalid person id”, the third party is not synchronized correctly. Work around is to send exact person information, according to entry in The National Population Register (Folkeregisteret).
Club level membership requests are subject to a two-phase verification active for 24 hours. The verification link is sent to the user via email and SMS. This must be passed for request to be fulfilled. After user verification an OTP code is sent by SMS and must be entered to the two-phase temporary site. Once completed request is passed on.
If a person is already validated in NIFs database, no OTP is required, and the person will not be able to change any personal information in the verification form. All personal information is kept updated by the person itself in Min idrett, by logging in with Idrettens ID.
As soon as two-phase verification is completed successfully, person club and branch level membership are added.
This API will respond with traceId along with other needed parameters. This traceId will be used to trace the request response with messages received in enterprise service bus queue.
After two-phase verification, person and membership records in queue has traceId. In case the person is already validated there is no traceId in the message in the queue or the response.
If Membership at Club or Branch level system will respond with existing MembershipId/ActiveMembershipId.
Entities to get affected by this API:
Tp_Person
Tp_Membership
Tp_ActiveMembership
Resource Information
...
Response Format
...
JSON
...
Requires Authentication
...
Yes
Request Headers
...
...
Name
...
Required
...
Description
...
1
...
ClubId
...
Yes
...
ClubId for which API is being requested.
...
2
...
Authorization
...
Yes
...
This is the token to define access for on-boarded club.
...
3
...
Ocp-Apim-Subscription-Key
...
Yes
...
API management’s subscription key. There will be separate key for each 3.party.
Request Parameters
...
...
Name
...
Required
...
Description
...
Example
...
1
...
IsClubLevel
...
Optional
...
True in case of Club level membership request, false in case of only branch level membership.
...
true/false
...
2
...
StartDate
...
Optional
...
StartDate for membership is required if ClubId is not provided, the system will ignore this field when ClubId is provided.
Possible Value
Must be of today’s date year. For example, if today’s date is 19-Sep-2019. Then start date must be in between 1-Jan-2019 to 31-Dec-2019.
...
"2019-06-07"
...
3
...
Person
...
Mandatory
...
...
...
4
...
PersonId
...
Optional
...
If PersonId is already present at 3.party´s database, and person is validated
...
1234567
...
5
...
FirstName
...
Optional
Max Length 50
...
Required if PersonId is not provided. Ignored it if PersionId is provided.
...
"Ola"
...
6
...
LastName
...
Optional
Max Length 50
...
Required if PersonId is not provided.
Ignored if PersonId is provided.
...
"Dunk"
...
7
...
BirthDate
...
Optional
...
Required if PersonId is not provided.
Ignored if PersionId is provided
...
"1980-07-05"
...
8
...
PostCode
...
Optional
Max Length 50
...
Required if PersonId is not provided
Ignored if PersionId is provided
...
"879534"
...
9
...
...
Required
Min Length 8
Max Length 100
...
Either email or mobile is required
Ignored if PersionId is provided
...
email@email.com
...
10
...
MobilePhone
...
Required
Min Length 8
Max Length 12
...
Either Email or Mobile is required
Ignored if PersionId is provided
...
"90909090"
...
11
...
CountryCode
...
Optional
Min Length 2
Max Length 6
...
CountryCode is required in the case MobilePhone is provided, and if PersonId is not provided.
Ignored if PersionId is provided.
...
+47 , +91
...
12
...
GenderId
...
Optional
...
Required if PersonId is not provided.
Ignored if PersionId is provided.
Possible Value
1 - Mann (male)
2 - Kvinne (female)
5 - Ukjent (unknown)
...
2
...
14
...
CountryId
...
Optional (when PersonId is supplied/Membership is being added for a Norwegian citizen)
...
Required if PersonId is not provided, Ignored if PersionId is provided.
...
1500152
...
15
...
NationalityId
...
Required
...
Nationality of person is required. (Pass the countryId from getCounties-API)
...
1500152
...
16
...
AddressLIne1
...
Optional
Max Length 50
...
First line of address
...
"Addressline 1”
...
17
...
AddressLIne2
...
Optional
Max Length 50
...
Second line of address
...
"Addressline 2"
...
18
...
City
...
Optional
Max Length 50
...
City of residence
...
"Oslo"
...
19
...
PrivatePhone
...
Optional
Min Length 8
Max Length 18
...
Private phone number
...
"78965872"
...
20
...
WorkPhone
...
Optional
Min Length 8
Max Length 18
...
Work phone number
...
"78965872"
...
21
...
IsSecretAddress
...
Optional
...
If the person has configured to hide their address from viewership on the UI, this flag will be set to true.
When set to true, it is the responsibility of the 3.party to hide this information from viewership on their UI.
...
true/false
...
22
...
IsSecretPrivatePhone
...
Optional
...
Similar to aforementioned scenario, if the person’s private phone is marked as secret, the 3.party must also hide it from their UI.
...
true/false
...
23
...
IsSecretWorkPhone
...
Optional
...
Similar to aforementioned scenario, if the person’s work phone is marked as secret, the 3. party must also hide it from their UI.
...
true/false
...
24
...
IsSecretMobilePhone
...
Optional
...
Similar to aforementioned scenario, if the person’s mobile phone is marked as secret, the 3.party must also hide it from their UI.
...
true/false
...
25
...
IsSecretEmail
...
Optional
...
Similar to aforementioned scenario, if the person’s email is marked as secret, the 3.party must also hide it from their UI.
...
true/false
...
26
...
Sports
...
Optional
...
Branch level Membership
...
[]
...
27
...
BranchId
...
Mandatory
...
...
1238
...
28
...
SportId
...
Mandatory
...
(Pass the sport id from getSports API)
...
...
29
...
StartDate
...
Mandatory
...
StartDate for branch level Membership
Possible Value
Must be of today’s date year. For example, if today’s date is 19-Sep-2019. Then start date must be in between 1-Jan-2019 to 31-Dec-2019
Must be greater than Club level membership start date.
Must be of Club level membership’s start date year. For example, if Club level membership’s start date is 19-Sep-2019. Then start date must be in between 1-Jan-2019 to 31-Dec-2019.
...
...
30
...
EndDate
...
Optional
...
Possible Value
Must be greater than today’s date.
...
OBSOLETE?
Two-phase verification link and One Time Password (OTP) matrix
...
...
Cases
...
Send two-phase link
...
OTP SMS Code
...
Note
...
1
...
Add Club level membership with new person (Norwegian)
...
Yes
...
Yes
...
...
2
...
Add Club level membership with new person (Foregin)
...
Yes
...
No
...
...
3
...
Add Club level membership with validated existing person
...
Yes
...
No
...
...
4
...
Add Club level membership with unvalidated existing person (Norwegian)
...
Yes
...
Yes
...
...
5
...
Add Club level membership with unvalidated existing person (Non-Norwegian)
...
Yes
...
No
...
...
6
...
Add Club level and Branch level membership with new person (Norwegian)
...
Yes
...
Yes
...
...
7
...
Add Club level and Branch level membership with new person (Non-Norwegian)
...
Yes
...
No
...
...
8
...
Add Club level and Branch level membership with validated existing person
...
Yes
...
No
...
...
9
...
Add Club level and Branch level membership with unvalidated existing person (Norwegian)
...
Yes
...
Yes
...
...
10
...
Add Club level and Branch level membership with unvalidated existing person (Non-Norwegian)
...
Yes
...
No
...
...
11
...
Add Branch level membership unvalidated existing person
...
No
...
No
...
...
12
...
Add Branch level membership with validated existing person
...
No
...
No
...
...
13
...
Add Branch level membership without club level membership with new Person
...
No
...
No
...
Branch level membership cannot be added without club level membership. Hence two-phase verification would not be initiated.
...
14
...
Add Branch level membership without club level membership for validated existing person
...
No
...
No
...
Branch level membership cannot be added without club level membership. Hence two-phase verification would not be initiated.
...
15
...
Add Branch level membership without club level membership for unvalidated existing person (Norwegian)
...
No
...
No
...
Branch level membership cannot be added without club level membership. Hence two-phase verification would not be initiated.
...
16
...
Add Branch level membership without club level membership for unvalidated existing person (Non-Norwegian)
...
No
...
No
...
Branch level membership cannot be added without club level membership. Hence two-phase verification would not be initiated.
Simplified add member flow
...
Response codes
...
...
Code
...
Text
...
Description
...
1
...
200
...
Success
...
...
2
...
1001
...
Either PersonId or a combination of (FirstName, LastName, BirthDate, PostCode, NationalityId) must be supplied.
...
...
3
...
1002
...
Invalid Person Id
...
...
4
...
1006
...
Invalid Branch Id
...
...
5
...
1007
...
Start date cannot be past/future year date.
...
...
6
...
1010
...
Either Email or MobilePhone and CountryCode must be supplied.
...
...
7
...
1013
...
Branch level membership information missing.
...
...
8
...
1018
...
Invalid club Id.
...
...
9
...
1034
...
Person not found.
...
...
10
...
1036
...
Start date is required.
...
...
11
...
1038
...
Branch start date must be grater then membership start date.
...
...
12
...
1039
...
Invalid request parameters.
...
...
13
...
1042
...
Group level membership for Club is not allowed.
...
...
14
...
3001
...
Membership not found for specific period from date.
...
Membership Request Example
| Code Block | ||
|---|---|---|
| ||
{
"startDate": "2019-08-27",
"isClubLevel": true,
"person": {
"personId": 8756934, -- NB: If personId is provided, all person properties ignored.
"firstName": "Ola",
"lastName": "Dunk",
"birthDate": "1980-07-05",
"postCode": "0010",
"email": "helge.carter@nic.com",
"mobilePhone": "85569745",
"genderId": 2,
"countryId": 1500152,
"nationalityId": 1500152,
"addressLine1": "Blålyngveien 89",
"addressLine2": "",
"city": "Oslo",
"privatePhone": "78553987",
"workPhone": "78553977",
"isSecretAddress": true,
"isSecretWorkPhone": true,
"isSecretMobilePhone": false,
"isSecretEmail": true,
"countryCode": "+47",
"isSecretPrivatePhone": true
},
"sports": [
{
"branchId": 827527,
"sportId": 220,
"startDate": "2019-08-27",
"endDate": "2019-09-26"
},
{
"branchId": 819760,
"sportId": 207,
"startDate": "2019-08-27",
"endDate": "2019-09-26"
}
]
} |
Membership Response Example
| Code Block |
|---|
{
"personId": 8756934,
"membershipId": 0,
"clubId": 19428,
"clubName": "Gjermundsen Auto B.I.L.",
"startDate": "2019-08-27",
"traceId": "7AC07206-471E-4015-9ED7-E6DB55ED7201",
"sports”: [
{
"branchId": 819760,
"sportId": 207,
"branchName": "Berg IL",
"activeMembershipId": 0
},
{
"branchId": 827527,
"sportId": 220,
"branchName": "Berg IL",
"activeMembershipId": 0
}
],
"responseMessage": "Membership request is accepted at Club Level.
It is pending for two phase verification."
} |
| Note |
|---|
NOTE: If response contains personId and no membershipId, NEVER use this personId until the two phase verification is done by the end user, and the information is provided on the 3. party´s subscription queue. |
Allidrett request example
| Code Block |
|---|
{
"startDate": "2019-08-27",
"isClubLevel": true,
"person": {
"personId": "",
"firstName": "Dolly",
"lastName": "Duck",
"birthDate": "1980-07-05",
"postCode": "0010",
"email": "dd@mailinator.com",
"mobilePhone": "85569745",
"genderId": 2,
"countryId": 1500152,
"nationalityId": 1500152,
"addressLine1": "Blålyngveien 8",
"addressLine2": "",
"city": "Oslo",
"privatePhone": "78553987",
"workPhone": "78553977",
"isSecretAddress": true,
"isSecretWorkPhone": true,
"isSecretMobilePhone": false,
"isSecretEmail": true,
"countryCode": "+47",
"isSecretPrivatePhone": true
},
"sports": [
{
"branchId": 827527,
"sportId": 220,
"startDate": "2019-08-27",
"endDate": "2019-09-26"
}
],
"groups": [
{
"sportId": 0,
"groupId": 544901,
"startDate": "2019-08-27",
"endDate": "2019-09-26"
}
]
} |
Allidrett response example
| Code Block |
|---|
{ "personId": 8756934, "membershipId": 0, "clubId": 19428, "clubName": "Gjermundsen Auto "STAVANGER", "county": "Norge", "longitude": null, "latitude": null, "groups": [ { "groupId": 766441, "groupName": "PetrOl B.I.L.", "startDate "describingName": "2019-08-27PetrOl B.I.L. - Curling", "traceId": "7AC07206-471E-4015-9ED7-E6DB55ED7201", "sports": [], "sportId": 204, "groupssportName": []"Curling", "person": null, "responseMessage": "Membership request is accepted at Club Level."branches": [] It is pending for two phase} verification."] } |
Endpoints
Annet
Table of Content
...
7.8.1 External Membership API 60
...