1 POST Membership (AddMembership)
- - 1.1.1 Overview
- 1.2 Endpoints
  - 1.2.1 Resource Information
  - 1.2.2 Request Headers
  - 1.2.3 Request Parameters
  - 1.2.4 Two phase verification link and One Time Password (OTP) matrix
  - 1.2.5 Simplified add member flow
  - 1.2.6 Response codes
  - 1.2.7 POST Membership Request Example
  - 1.2.8 POST Membership Response Example
  - 1.2.9 POST Membership Response Example - Existing person
  - 1.2.10 POST Allidrett Membership Request Example
  - 1.2.11 POST Allidrett Memberhsip Response Example

POST Membership (AddMembership)

Overview

Describing how to add a person as a member to a sports club and/or branch. (Idrettslag og/eller idrettsgren).

Applies to regular sports clubs (type 5), including group “Allidrett”, and corporate sports clubs (type 15).

Endpoints

Current API version is 1 (example URL: /api/v1/membership)

URL	Environment	Comment

URL	Environment	Comment
https://api-dst.nif.no/api/v1/membership	DST (Test)
https://api-dst.nif.no/api/v1/membership	PROD

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 (nationalityId: 1500152), membership request would be considered as “Norwegian person request”, and the person must enter his/hers social security number. Otherwise the 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 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 PersonId is provided	"1980-07-05"
8	PostCode	Optional Max Length 50	Required if PersonId is not provided Ignored if PersonId is provided	"879534"
9	Email	Required Min Length 8 Max Length 100	Email is required Ignored if PersonId is provided	email@email.com
10	MobilePhone	Required Min Length 8 Max Length 12	MobilePhone is required Ignored if PersonId 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 PersonId is provided.	+47 , +91
12	GenderId	Optional	Required if PersonId is not provided. Ignored if PersonId is provided. Possible Value 1 - Mann (male) 2 - Kvinne (female) 5 - Ukjent (unknown)	2
14	CountryId	Optional (but default value if NationalityId is norwegian)	Required if PersonId is not provided, Ignored if PersonId is provided. If CountryId is null, user must select from User Verification-application. Unless NationalityId (15) is set to 1500152, then default value will be Norway (1500152).	1500152
15	NationalityId	Required	Nationality of person is required. (Pass the countryId from GetCountries)	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 SportId from GetSports API-endpoint	Eg: 66
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.

POST Membership Request Example

{
  "startDate": "2023-03-01",
  "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": "ola.dunk@mailintator.com",
    "mobilePhone": "12345678",
    "genderId": 1,
    "countryId": 1500152,
    "nationalityId": 1500152,
    "addressLine1": "Blålyngveien 89",
    "addressLine2": "",
    "city": "Oslo",
    "privatePhone": "23456789",
    "workPhone": "34567890",
    "isSecretAddress": true,
    "isSecretWorkPhone": true,
    "isSecretMobilePhone": false,
    "isSecretEmail": true,
    "countryCode": "+47",
    "isSecretPrivatePhone": false
  },
  "sports": [
    {
      "branchId": 827527,
      "sportId": 220,
      "startDate": "2023-03-14",
      "endDate": ""
    },
    {
      "branchId": 819760,
      "sportId": 207,
      "startDate": "2023-03-01",
      "endDate": "2023-09-26"
    }
  ]
}

POST Membership Response Example

{
  "personId": null,
  "updatedPersonId": null,
  "membershipId": null,
  "clubId": 512430,
  "clubName": "Testklubb IR",
  "startDate": "2023-03-01T00:00:00",
  "traceId": "7AC07206-471E-4015-9ED7-E6DB55ED7201",
  "sports": [],
  "groups": [],
  "person": null,
  "responseMessage": "Membership request is accepted at Club Level. It is pending for two phase verification."
  sentToEmail: "ola.dunk@mailinator.com", 
  sentToPhone: "12345678"
}

March 2023 - Extended response

When adding a new member, an internal search for the person is done, to determine if the person is already present in ISD. This is to prevent duplicate persons in ISD.

If a person already exists, the two phase verification SMS and email will be sent to the existing persons contact details, and the response will also contain a personId.

The response will provide the contact detalis the information is sent to.
(See below example: “POST Membership Response Example - Existing person”)

POST Membership Response Example - Existing person

{
  "personId": 9302370,
  "updatedPersonId": null,
  "membershipId": null,
  "clubId": 512430,
  "clubName": "Testklubb IR",
  "startDate": "2023-03-01T00:00:00",
  "traceId": "7AC07206-471E-4015-9ED7-E6DB55ED7201",
  "sports": [],
  "groups": [],
  "person": null,
  "responseMessage": "Membership request is accepted at Club Level. It is pending for two phase verification."
  sentToEmail: "elias.håberg@testtest.com", 
  sentToPhone: "+4734567890"
}

NOTE: If response contains a 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.

Dokumentasjon digitale tjenester i Idretten

EMS - API Documentation - POST Membership (Add)