These pages contain detailed technical information about the Altinn Service Owner API.
All operations and parameters are described and example responses are given. Further information
regarding authentication, usage and license requirements is available at Altinn docs.
Information and source code for the Altinn Reference App can also be found there.
Access and use
An API-key is required in order to use the Altinn API. (For information on obtaining an API-key see Altinn docs).
The API-key needs to be included as a header value in every request. The API-key must be authorized to access service owner resources.
For any additional questions regarding the API-key see Altinn docs.
The service owner API also requires an enterprise certificate issued by Commfides or Bypass. All requests must have a query parameter with the
name ForceEIAuthentication and contain the certificate. The certificate must be issued to the same organization number as the service owner registered
in Altinn.
GET https://www.altinn.no/api/serviceowner/organizations?ForceEIAuthentication HTTP/1.1
Host: www.altinn.no
Accept: application/hal+json
ApiKey: myKey
Supported content types
The recommended content types for the Altinn API are application/hal+json or application/hal+xml.
The hal content types describes how a client can interact with the available services.
When retrieving for instance a Message, this will contain links to available actions
for the given object. See the HAL specification
for more information about how this is implemented in the Altinn API.
Note:
The Altinn API currently also support the content types application/json and application/xml.
The support for these content types will be removed in a future release, so it is recommended to
use application/hal+json or application/hal+xml.
Models
| Name |
Type |
Description |
| Name |
String |
The organization name from the register of legal entities. |
| OrganizationNumber |
String |
The organization number. |
| Type |
String |
The organization type. This is a code from the register of legal entities. |
| LastChanged |
DateTime |
The date and time for when some data on the organization was changed. |
| LastConfirmed |
DateTime |
The date and time for the last time the data on the organiation was confirmed. This date is only set
if a user confirms the data on a special confirmation page in the portal. The page comes visible
automatically if the LastChanged value is of a set age. (Data is considered confirmed as long as it
is kept up to date.)
|
| OfficialContacts |
|
A list of official contacts. This list is not populated unless it is explicitly requested with the OData $expand parameter.
$expand=OfficialContacts (case sensitive).
|
| Name |
Type |
Description |
| MobileNumber |
String |
The registered mobile phone number on this contact point. |
| MobileNumberChanged |
DateTime |
The date and time for when the mobile phone number was added or changed. |
| EMailAddress |
String |
The registered email address on this contact point. |
| EMailAddressChanged |
DateTime |
The date and time for when the email address was added or changed. |
| Name |
Type |
Description |
| PersonalContactId |
String |
A unique id representing the contact in Altinn. |
| Name |
String |
The name of this contact. |
| SocialSecurityNumber |
String |
The social security number of this contact. |
| MobileNumber |
String |
The registered mobile phone number on this contact point. |
| MobileNumberChanged |
DateTime |
The date and time for when the mobile phone number was added or changed. |
| EMailAddress |
String |
The registered email address on this contact point. |
| EMailAddressChanged |
DateTime |
The date and time for when the email address was added or changed. |
| Name |
Type |
Description |
| Name |
String |
The name of the reportee. |
| Type |
String |
The type of reportee. Value depends on the language choice of the user.
English: Enterprise | Business | Person
Bokmål: Foretak | Bedrift | Person
Nynorsk: Føretak | Bedrift | Person
|
| Status |
String |
Indicates whether the organization is active or inactive. An organization can be inactive if it for some reason
(e.g. bankruptcy) has ceased. This is populated only if the reportee is an organization.
|
| OrganizationNumber |
String |
The organization number of the reportee. This is populated only if the reportee is an organization. |
| ParentOrganizationNumber |
String |
The parent organization number of the reportee. This is populated only if the reportee is an organization, and the organization is a suborganization. |
| TypeOfOrganization |
String |
The type of organization for the reportee. This is populated only if the reportee is an organization. E.g ENK, AS, ORGL. |
| SocialSecurityNumber |
String |
The social security number of the reportee. This is populated only if the reportee is a person. |
| Name |
Type |
Description |
| RightID |
Int |
A unique id for the specific right. |
| RightType |
String |
Specifies the type of right. Possible values are Message, Service and SystemResource. |
| SystemResourceID |
String |
Id of the system resource. Visible only for a right of type SystemResource. |
| ServiceCode |
String |
Part 1/2 of the id of a specific service. Visible only for a right of type Service. |
| ServiceEditionCode |
int |
Part 2/2 of the id of a specific service. Visible only for a right of type Service. |
| MessageID |
int |
Value used to identify a specific message. |
| Action |
String |
Action supported by the right. Possible values are Read, Write, Sign, ArchiveRead and ArchiveDelete. |
| RightSourceType |
String |
Specifies the way the right is given. Possible values are PartyRights, RoleTypeRights, ReporteeElementRights and DirectlyDelegatedRights. |
| Name |
Type |
Description |
| RuleGuid |
string |
A unique id for the specific right. |
| AltinnAppId |
String |
Specifies the appid on format org/app and reflects to the app definition where org is the owner of the app and app is the name of the app. |
| ResourceId |
String |
Id of the system resource. This will be Task or Event and possible more values in the future |
| ResourceValue |
String |
The name of the resource |
| Action |
String |
Action supported by the right. Possible values are anything defined as Action on the app but Read, Write is common values. |
| RightSourceType |
String |
Specifies the way the right is given. Possible values are DirectlyDelegated, InheritedViaKeyRole, InheritedAsSubunit, InheritedAsSubunitViaKeyrole, RoleTypeRight. |
| IsDelegatable |
bool |
Specifies if this right is delegatable or not. |
| Name |
Type |
Description |
| RoleType |
String |
Specifies the type of role this is. Possible values are Altinn, External and Local. |
| RoleDefinitionId |
int |
Unique id of the role definition. |
| RoleName |
String |
Name of the role. |
| RoleDescription |
String |
Description of the role. |
| RoleDefinitionCode |
String |
The short hand code for the role. |
| Name |
Type |
Description |
| RoleType |
String |
Specifies the type of role this is. Possible values are Altinn, External and Local. Can be left out when creating a new role. Value will be set to Local. |
| RoleDefinitionId |
Int |
Unique id of the role definition. |
| RoleName |
String |
A descriptive name for the role. |
| RoleDescription |
String |
A complementary description of the role. |
| RoleDefinitionCode |
String |
The short hand code for the role. |
| Name |
Type |
Description |
| EventId |
int |
Unique identifier for the event |
| EventType |
String |
Specifies the type of the event. Possible values are CorrespondenceCreated, CorrespondenceRead, CorrespondenceConfirmed, CorrespondenceArchived, CorrespondenceDeleted, CorrespondenceReserved, CorrespondenceNotificationCreated and CorrespondenceNotificationSent |
| EventTime |
DateTime |
Timestamp for when the event occured |
| EventDetails |
Dictionary |
A list of Key Value pairs representing the detail information for the event |
| Name |
Type |
Description |
| Id |
Int? |
A unique identifier for the SrrRight. This is given to all new and changed rights when using POST and PUT operations. |
| ServiceCode |
String |
The service code of the associated service. Together with ServiceEditionCode it uniquely identifies a service. |
| ServiceEditionCode |
String |
The service edition code of the associated service. Together with ServiceCode it uniquely identifies a service. |
| Reportee |
String |
The id of the legal entity that this right is given to. Valid values must be a social security number or organization number. |
| Operation |
String |
Defines which operation that the right covers. Valid values are Read, Write, Access, Sign, ArchiveRead and ArchiveDelete. |
| ValidTo |
DateTime |
Specify when a right will expire and the right is effectively lost. |
| Condition |
SrrRightCondition |
Entity containing the condition information. This involves a complex set of rules that will vary from service to service. |
| OperationStatus |
String |
Feedback field used in a response after a POST or PUT request. |
| Name |
Type |
Description |
| HandledBy |
String |
The organization number of an organization that has been given the right to act on the behalf of the reportee as a third party. Used by consent. |
| IsRecipient |
Boolean |
Flag to indicate whether the reportee is a recipient of a service payload. Can be set to true on Write rights. Used during authorization by broker service
to determine who the reportee can send payloads to. If the value is true, the reportee can only send payloads as a response to a separate service instance.
|
| IsSender |
Boolean |
Flag to indicate whether the reportee is a sender of a service payload. Can be set to true on Read rights. Used during authorization by broker service in combination with
the IsRecipient flag to determine who the reportee can send payloads to. A value of true means the reportee is marked as an organization that can start an exchange of payloads.
Organizations that has a Write right with the IsRecipient equal true can send payloads only to organizations marked in this way.
|
| KeepSessionAlive |
Boolean |
Flag to indicate whether the user should be signed out of Altinn again after visiting the consent page. If a consent involves multiple rights it is enough with
one right having this flag set to true and the user will remain signed in.
|
| AllowedRedirectDomain |
List of String |
List of domains that the consent page is allowed to redirect a user to after having visited the consent page. |
| Name |
Type |
Description |
| AuthorizationCode |
String |
The GUID for the authorization token for the consent. |
| Status |
String |
The status of the consent. It can be Active or Revoked. |
| OfferedBy |
Reportee |
The person or organization that has given a consent to CoveredBy. |
| CoveredBy |
Reportee |
The person or organization that can act upon the consent. |
| HandledBy |
Reportee |
(Optional) The person or organization that can act on behalf of CoveredBy. |
| Created |
DateTime |
The date and time for when the consent was initially processed by OfferedBy. |
| ValidTo |
DateTime |
The date and time for when the consent is no longer valid. Once it is no longer valid the consent cannot be acted on by CoveredBy or HandledBy. |
| LastChanged |
DateTime |
The date and time for when the status of the consent was last changed. If this is different from Created, it means that the Status has gone from Active to Revoked. |
| Name |
Type |
Description |
| RequestStatus |
String |
The status of the delegation request. (Only in response) |
| CoveredBy |
Reportee |
The person or organization that requests the rights. |
| OfferedBy |
Reportee |
The person or organization that can approve or decline the requested rights. |
| Created |
DateTime |
The date and time for when the request was initially created. (Only in response) |
| LastChanged |
DateTime |
The date and time for when the request was last changed. (Only in response) |
| RedirectUrl |
Uri |
The url where the user should be redirected to when the request has been submitted by the user. The url needs to be in the CORS whitelist. (Optional) |
| KeepSessionAlive |
Boolean |
A value indicating whether the session in altinn should be kept alive after the redirect. Can only be used in combination with RedirectUrl. (Optional) |
| RequestMessage |
String |
A message explaining why CoveredBy should get the rights specified in the request. This is to help the RoleAdministrator in OfferedBy to understand why this request is made. This is a draft of the message, and CoveredBy will be able to change the message before sending it to the RoleAdministrator. (Optional) |
| RequestResources |
List<DelegationRequestResource> |
Array containing the Requested Services |
| Name |
Type |
Description |
| ServiceCode |
String |
The external service code of the related service. |
| ServiceEditionCode |
Integer |
The external service edition code of the related service. |
| Operations |
List<OperationType> |
Array of operations (Read, Write, Sign, Access). If none is given, access to all available operations on the specified service will be requested. (Optional) |
Actions
Provides access to information about organizations/legal entities and their contact points.
| API | Description |
|---|
| GET serviceowner/organizations?email={email}&phoneNumber={phoneNumber} |
Get a list of organizations that match the provided filters.
The special email and phone number parameters can be used to search for all organizations that have those values as their official or personal
contact point.
There are support for OData, but with some limitations:
- $top - Number of organizations to retrieve. The value can be from 1 to 1000. Values outside this range will be adjusted automatically.
- $skip - Number of organizations to skip. (Use this together with $top to create paging functionality.) The value can be 0 or higher. Negative values will be ignored.
- $orderby - Can be used to change sorting. It is possible to sort by Name or OrganizationNumber. The default is OrganizationNumber.
- $filter - Can be used to filter the result. Currently limited to filtering on Type with exact value. Eg: $filter=Type eq 'ENK'
- $expand - Can be used to include official contacts of each organization in the list. Use: $expand=OfficialContacts
|
| GET serviceowner/organizations/{organizationNumber} |
Gets information about a single organization. The operation supports the OData keyword $expand. Example: "$expand=OfficialContacts".
|
| GET serviceowner/organizations/{organizationNumber}/officialcontacts |
Gets a list of official contacts for a specific organization.
|
| GET serviceowner/organizations/{organizationNumber}/personalcontacts?roleDefinitionCode={roleDefinitionCode}&serviceCode={serviceCode}&serviceEdition={serviceEdition} |
Gets a list of all personal contacts for an organization. If no parameters are given for filtering, all personal contacts will be returned.
- If roleTypeCode is set, the returned list will be filtered based on the role which the creators of the endpoints has.
- If serviceCode and serviceEdition is set, the returned list will be filtered based on whether the creator of the endpoint has access to the service identified by the parameters, and if the creator has opted to receive notification for it.
|
| GET serviceowner/organizations/{organizationNumber}/personalcontacts/{who}/roles |
Gets a list of all roles a given personal contact / reportee has on behalf of the given organization
|
Collection of actions that provides data about legal entities a user can represent.
Reportee is a term used to describe a legal entity that a user can represent and act on behalf of.
The actions provide data about the persons and organizations a user can represent.
| API | Description |
|---|
| GET serviceowner/reportees?subject={subject}&serviceCode={serviceCode}&serviceEdition={serviceEdition}&roleDefinitionId={roleDefinitionId}&showConsentReportees={showConsentReportees} |
Gets a list of entities that the current user can represent. The list can optionally be filtered to only display entities by a specific service (identified by ServiceCode and ServiceEdition) or role definition (identified by RoleDefinitionId).
|
Contains all actions related to authorization rights
| API | Description |
|---|
|
GET serviceowner/authorization/rights?subject={subject}&reportee={reportee}
|
Gets the rights the subject has for the specified reportee.
|
Contains all actions related to authorization apprights
| API | Description |
|---|
|
GET serviceowner/authorization/apprights?subject={subject}&reportee={reportee}
|
[Removed] Gets the apprights the subject has for the specified reportee.
|
Contains all actions related to authorization roles
Contains actions related to role definitions.
Actions for retrieving the status of Correspondence elements. The information is presented in a feed that holds all events related to Correspondece items. The users of this API are responsible
for keeping track of what events they have already read. If the id of the last read event is provided as an offset, the feed will return up to the 10 000 next events registered (the last read event will not be included).
| API | Description |
|---|
| GET serviceowner/events/feed?eventOffset={eventOffset}&fetch={fetch} |
Get all saved events for Correspondence items. The eventOffset parameter is used to offset the start of the feed. The feed will return up to 10 000 events starting with the first available event after the eventOffset.
If no eventOffset is provided, the feed will start from the first event available. The fetch parameter is used to limit the number of results. If no fetch parameter is provided, the feed returns up to 10 000 events. It is not possible to get more than 10 000 elements by setting a higher value for the fetch parameter
|
Contains all CRUD actions for the SrrRight resource.
| API | Description |
|---|
|
GET serviceowner/srr?serviceCode={serviceCode}&serviceEditionCode={serviceEditionCode}&reportee={reportee}
|
Gets all SRR rights for a specific service (specified by ServiceCode and ServiceEditionCode), with an optional parameter
of reportee. If OK this action returns a list with all SRR rights for the service.
Authenticated service owner must be the owner of the service.
|
|
GET serviceowner/srr/{id}
|
Gets the SRR rule with the specified id. If OK this action returns the specified SRR right.
Authenticated service owner must be the owner of the service.
|
| POST serviceowner/srr |
Creates one or more new SRR rights for a specific service. The service's ServiceCode and ServiceEditionCode are specified
as part of each SrrRight object in the input. If OK this action returns a list with of SrrRight objects with the added rights and the result
of the operation in the OperationStatus field for each object.
Authenticated service owner must be the owner of the service.
|
| PUT serviceowner/srr/{id} |
Updates an SRR rule based on the rule id. The id is specified as part of the url, and a SrrRight object with the changed value(s) is
passed in the request body. The response will indicate the result of the operation in the OperationStatus field.
Authenticated service owner must be the owner of the service.
|
| DELETE serviceowner/srr/{id} |
Deletes an SRR right based on the right id. The id is passed as part of the url.
Authenticated service owner must be the owner of the service.
|
Actions for retrieving the information and status of Consents given on a specific service. The information is presented in a list ordered by Last Changed timestamp, with the most recent change last.
After the first call to this endpoint, users of this API should use the Continuation parameter to only retrieve new and updated Consents. The argument for the Continuation parameter is provided in the previous response.
Users can also choose to only retrieve either Active or Revoked Consents, by supplying the desired status as an argument for the Status parameter. By default, both Active and Revoked Consents will be included in the list.
| API | Description |
|---|
|
GET serviceowner/consents?serviceCode={serviceCode}&serviceEditionCode={serviceEditionCode}&status={status[0]}&status={status[1]}&continuation={continuation}
|
Get all the consents for a service. The serviceCode and serviceEditionCode specifies which service to retrieve consents for.
It is possible to specify the consent status that should be included in the list. By default, both active and revoked status will be included.
The continuation parameter will allow user to only include new consents or consents that have changed status since last request.
|
Actions for retrieving the information of DelegationRequests created by ServiceOwner. The information is presented in a list ordered by Last Changed timestamp, with the most recent change last.
After the first call to this endpoint, users of this API should use the Continuation parameter to only retrieve new and updated DelegationRequests. The argument for the Continuation parameter is provided in the previous response.
| API | Description |
|---|
|
GET serviceowner/delegationRequests?serviceCode={serviceCode}&serviceEditionCode={serviceEditionCode}&status={status[0]}&status={status[1]}&continuation={continuation}
|
Get all the DelegationRequests created by the service owner. The serviceCode and serviceEditionCode specifies which service to retrieve consents for.
It is possible to specify the consent status that should be included in the list. By default, both active and revoked status will be included.
The continuation parameter will allow user to only include new consents or consents that have changed status since last request.
|
|
GET serviceowner/delegationRequests/{id}
|
Gets the DelegationRequest by its id. The authenticated service owner must be either the creator or listed as coveredBy in the request.
|
|
POST serviceowner/delegationRequests
|
Creating a new DelegationRequest with the status CREATED. The authenticated service owner must be the owner of the provided service(s).
|
|
DELETE serviceowner/delegationRequests/{id}
|
Deletes a DelegationRequest by its id. The authenticated service owner must be either the creator or listed as coveredBy in the request.
|
API operations allowing for service owner to perform delegations on behalf of third parties.
| API | Description |
|---|
|
POST serviceowner/delegations/roles/?onBehalfOf={onBehalfOf}
|
Allows for service owner to perform delegation of roles on behalf of a third party (onBehalfOf) to a person or an organization.
|
|
DELETE serviceowner/delegations/roles/{roleId}
|
Allows for service owner to delete a role they have delegated on behalf of a third party.
|
Actions for retrieving information about a user or organizations notification settings. Can also give information about a specific service with code and edition number parameters set.
OData filtering
OData can be used to enable filtering, paging and ordering of lists of elements returned by most methods returning a list.
The filter option of OData makes it possible to filter the result based on the properties of the model returned.
For example by applying the following parameter when requesting organizations that are sole proprietorship.
$filter=Type eq 'ENK'.
The OData options (with some limits) supported so far are:
- $filter
- $skip
- $top
- $orderby
- $expand
For more information about OData see OData.
