These pages contain detailed technical information about the Altinn 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 here.

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. Sample request headers are shown below.

Sample request with API-key

GET https://www.altinn.no/api/my/messages HTTP/1.1
Host: www.altinn.no
Accept: application/hal+json
ApiKey: myKey
For any additional questions regarding the API-key see Altinn docs.

Supported content types

The recommended content types for the Altinn API are application/hal+xml or application/hal+json. 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

+ Message

Name Type Description
MessageId String Id of the Message. The id prefix indicates wether this is an active (a), archived (b) or Altinn1 element (c).
MessageLink Uri Link to the Message.
Subject String Subject of the Message.
Status String Status of the Message, for example "Sent and archived" or "Active".
CreatedDate DateTime Timestamp indicating when this Message was created
LastChangedDateTime DateTime Timestamp indicating when this Message was last modified
LastChangedBy String Value indicating who last changed this Message.
ServiceOwner String The Message service owner.
Type String Type of the Message. The types currently supported are FormTask and Correspondence.
MessageSender(5) String The name of the creator of the message.
Summary(1) String Message summary.
Body(1) String Message body.
ServiceCode String ServiceCode of the Message.
ServiceEdition Int ServiceEdition of the Message.
DueDate DateTime The date when a Message of type FormTask must be submitted, or when a message of type Correspondence must be confirmed. Only used for GET.
Forms(2)(3) List<Form> List of forms associated with the Message.
Attachments(2) List<Attachment> List of attachments associated with the Message.
SignatureSpec(4) SignatureSpecification Container object for the list of Forms and Attachments that should be signed.
AvailableAction(2)(3) AvailableAction The action which the currently logged in user can perform on this message. Possible values: 0 = NoAction, 1 = Sign, 2 = FormFilling, 3 = SendIn, 4 = SignAndSendIn, 5 = DoSignDelegation, 6 = Pay, 7 = PayAndSendIn
ArchiveReference String A reference provided by the service owner to a previous connected message.
ReplyOptions(6) Array Collection of reply options. One record for each reply option specified by the Service Owner. Every Reply Option includes a Type (One of "Service", "ArchiveReference" or "URL"), a URL and a URL Text. Reply options of type "Service" also includes the ServiceCode and ServiceEditionCode of the referenced service.

(1) Only added for Messages with of Type Correspondence.

(2) Only added when an individual Message is opened with a request to /api/{who}/messages/{messageId}.

(3) Only added for Messages with of Type FormTask.

(4) This is currently used only for input during POST or PUT of Message. The parameter is optional and if it is omitted the logic will sign all forms and attachments associated with the Message.

(5) Only added for Messages with of Type Correspondence or for Reporting elements that was not created by the reportee.

+ SignatureSpecification

Name Type Description
FormIds int[] Array list with formids that should be signed.
AttachmentIds int[] Array list with attachmentids that should be signed.

+ Attachment

Name Type Description
FileName String Filename of the Attachment.
Data Byte[] The Attachment data (base64 encoded).
AttachmentLink Uri Download link for the Attachment.
AttachmentType String Attachment type name.
AttachmentTypeLocalized String Attachment type name localized to the current language.
Encrypted Boolean Flag indicating if this is an encrypted Attachment.
SigningLocked Boolean Value indicating whether the user should be allowed to change signing selection of the attachment. If both SigningLocked and SingedByDefault are true, then signing is required.
SignedByDefault Boolean Value indicating whether the service owner wants the attachment to be signed. If both SigningLocked and SingedByDefault are true, then signing is required.
FileSize Int The file size of the attachment in bytes, or -1 if the file size is unknown to the API.

+ Form

Name Type Description
FormId Int The id of the form.
Type String Form type, e.g. subform or mainform.
FormData String The Form data. This is currently only used when the client wants to POST or PUT a form. A client that wants to retrieve the form data must use a separate operation. See actions for Forms below.
DataFormatId String DataFormatId of the Form.
DataFormatVersion Int DataFormatVersion of the Form.
ValidationStatus String Value indicating the current validation status of the Form.
Name String Name of the Form.
SigningLocked Boolean Value indicating whether the user should be allowed to change signing selection of the form. If both SigningLocked and SingedByDefault are true, then signing is required.
SignedByDefault Boolean Value indicating whether the service owner wants the form to be signed. If both SigningLocked and SingedByDefault are true, then signing is required.

+ Reportee

Name Type Description
ReporteeId String A unique id representing the reportee in Altinn.
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.

+ Organization

Name Type Description
OrganizationNumber String Organization number.
Name String Name of the Organization.
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.

+ UserProfile

Name Type Description
Name String Name of the user.
AddressLine1 String Address line number 1.
AddressLine2 String Address line number 2.
AddressLine3 String Address line number 3.
UserName String User name of the user.
MobileNumber String Mobile number registered to be used for pin code on SMS.
PreferredLanguage String User preferred language.
ShowClientUnits Boolean Flag indicating whether to show client units.
PrivateConsent Boolean Flag indicating whether this user has given private consent in Altinn.
ProfessionalConsent Boolean Flag indicating whether this user has given professional consent in Altinn.
ContactInformation ContactInformation Contact information from the private consent profile of the user.

+ ContactInformation (private)

Name Type Description
Email String The email address registered as private consent contact address.
Mobile String The mobile number registered as private consent contact number.
RequestsEmailReceipts Boolean A flag indicating if this user wants to receive receipts when new elements are added to the message box.

+ ContactInfo (organization)

Name Type Description
Id Integer The Id of the address. This field should be empty (+) when submitting new contact information via a POST request.
Name String The name of the address. This is usually the same as the email/mobile number. This field should be empty (null) when submitting new contact information via a POST request.
Email String The email address registered as an official contact address for the organization.
MobileNumber String The mobile number registered as an official contact address for the organization.
IsSelectedForNotification Boolean (Deprecated)A flag indicating if this address should receive notifications. Will always be true. This field should be empty/default (false)

+ UnitProfile

Name Type Description
Entity String Name of the organization.
Email String Email address.
OrganizationNumber String The representing organization number.
MobileNumber String Mobile number registered.
Type String Type of Unit
LastModifiedBy String The name of the person who did the last change to the unit profile.
Address String Organization postal address
PostCode String Organization postal code
City String Organization city name
BusinessAddress String Organization business address
BusinessPostCode String Organization business postal code
BusinessCity String Organization business city name
LastModifiedDate DateTime The date and time for the last change to the unit profile.
IsSelectedForNotification Boolean Flag indicating whether is Selected For Notification.

+ ServiceMetaData

Name Type Description
ServiceOwnerCode String The id of the owner of the service.
ServiceOwnerName String The name of the owner of the service.
ServiceName String The name of the service.
ServiceCode String Part 1 of the unique id of the service.
ServiceEditionCode Int Part 2 of the unique id of the service.
ValidFrom DateTime The date from when the service is valid to be used.
ValidTo DateTime The date till when the service is valid to be used.
ServiceType String The type of service.
RestEnabled Boolean Flag indicating if the service can be used through the REST Api.
AttachmentRules List<AttachmentRule> List of attachment rules associated to the service.
FormsMetaData List<FormMetaData> List of form meta data elements associated with the service.
EUSEnabled Boolean Flag indicating if the service is enabled for end user system.
EnterpriseUserEnabled Boolean Flag indicating if the service is enabled for enterprise users.
ProcessSteps List<ProcessStep> List of process step elements associated with the service.

+ FormMetaData

Name Type Description
FormID Int Logical Form ID in the Form Set Collection.
FormName String Logical Form Name in the Form Set Collection.
DataFormatProviderType String Logical form Data Format Provider.
DataFormatID String Part 1 of the unique id of the form definition.
DataFormatVersion Int Part 2 of the unique id of the form definition.
IsOnlyXsdValidation Boolean Flag indicating if a submission is validated with more than the XSD.
FormType String Logical form type.

+ ProcessStep

Name Type Description
SequenceNumber Int The numerical order of each step in the work flow.
Name String Name of the process step.
SecurityLevel Int Required security level of the process step.

+ AttachmentRule

Name Type Description
AttachmentRuleId Int Id of the Attachment Rule.
AllowedFileTypes String A list of file extensions that are accepted.
AttachmentTypeName String The name of the attachment rule/type.
AttachmentTypeNameLanguage String Attachment Type Name Language.
IsCheckSumAllowed Boolean Flag indicating whether check sum can be used.
IsXSDValidationRequired Boolean Flag indicating whether xml attachments will be validated with an XSD.
MaxAttachmentCount Int The maximum number of allowed attachments.
MaxFileSize Int The maximum allowed file size.
MinAttachmentCount Int The minimum number of attachments required.

+ Codelist

A Codelist is a list of tuples where each tuple can hold one code and three values. Each list have a name, version number and a language in addition to the actual codes.

Name Type Description
Name String The name of the codelist.
Version Int The version number of the codelist. Services can use a spesific version of a codelist.
Language Int The language used in the codelist.
Codes List<CodelistItem> The actual list of codes. See CodelistItem.

+ CodelistItem

A CodelistItem is a tuple that can hold one code and three values. The CodelistItem model is used by the Codelist model to describe each item in the list.

Name Type Description
Code String The code value of the item.
Value1 String Item value number one.
Value2 String Item value number two.
Value3 String Item value number three.

+ Role

Name Type Description
RoleId Int Unique id of the role.
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.
Delegator String Specifies who has delegated this role.
DelegatedTime DateTime The date and time when the role was delegated.

+ Right

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.

+ RoleDefinition

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. Leave out when creating a new role.
RoleName String A descriptive name for the role. Limited to 50 characters.
RoleDescription String A complementary description of the role. Limited to 255 characters.
Rights List<Right> A list of the rights associated with the role.

+ RightHolder

Name Type Description
RightHolderId String The ID of the user holding the rights. The value is globally unique in Altinn and represents a person, organization or enterprise user.
Name String The name of the right holder. Person name, name of organization or username of an enterprise user.
LastName String The surname of the reportee. Visible only for persons. Required input when performing delegation.
UserName String The username of an enterprise user or person with a username. Not visible in output, but required input when delegating a right to an enterprise user.
Email String Required input when performing delegation. The value is used to notify the entity receiving the new rights.
SocialSecurityNumber String The social security number of the reportee if a person. This is in most cases hidden. Can be used in place of username when delegating rights to a person.
OrganizationNumber String The organization number of the reportee. This is required input when delegating rights to an organization.
Roles List<Role> A list of existing roles given to the rights holder.
Rights List<Right> A list of existing rights given to the rights holder. (Most rights in this list has been given through a role.)
Name Type Description
ServiceCode String The external service code of the related service.
ServiceEditionCode Integer The external service edition code of the related service.
UsageDateTime Datetime The date and time for when the consent was used. Optional.

+ ConsentRequest

Name Type Description
AuthorizationCode Guid The AuthorizationCode of a valid ConsentRequest. Only in return.
RequestStatus String The status of an ConsentRequest. Only in return.
Created DateTime DateTime when the request was created. Only in return.
LastChanged DateTime DateTime when the request was last changed. Only in return.
CoveredBy String Norwegian organization number or SSN of CoveredBy.
OfferedBy String Norwegian organization number or SSN of OfferedBy.
OfferedByName String Last name of person or name of organization.
HandledBy String Norwegian organization number or SSN of HandledBy. Optional if not required by SRR.
RequiredDelegator String Norwegian organization number or SSN of RequiredDelegator. Optional.
RequiredDelegatorName String Last name of person. Optional, but required if RequiredDelegator is present.
ValidTo DateTime The DateTime to which the consent will last, if granted.
RedirectUrl String The redirectUrl where the user should be redirected after the consent is given.
RequestResources List<ConsentRequestResource> Array containing Requested Services
RequestMessage Dictionary<Language, string> Dictionary containing the request message specified in different languages.
Errors List<ConsentRequestError> An array with errorMessages if validation of request failed. Only on return.

+ ConsentRequestResource

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. Only in return.
Metadata Dictionary<string, string> Metadata properties for the specified service. Optional.

+ ConsentRequestError

Name Type Description
ErrorCode String An id of the error that occured in the request.
ErrorMessage String A detailed description of what is wrong with the request.

+ ValidationResult

Name Type Description
Success bool Value indicating whether there were any hard errors found during validation
ValidationErrors List<ValidationError> List of validation errors
ValidationWarnings List<ValidationError> List of validation warnings

+ ValidationError

Name Type Description
FieldName String Name of the field that failed validation.
FieldXPath String XPath of the field that failed validation.
ErrorMessage String Validation error message.

Actions

+ Token

+ RoleDefinitions

+ Rights

+ Roles

+ Reportee

+ Authentication

+ Profile

+ LookUp

+ Metadata

+ Organizations

+ Attachments

+ Messages

+ Forms

+ Delegations

+ BrokerService

+ ConsentRequest

Portal integrations

There are still a few tasks and technical aspects that requires the use of the Altinn portal. In these cases the API will attempt to make the transition between the API and the portal as smooth as possible.

Integration Description
Payment

The goal of this integration is to get the user directly to the correct payment page in the portal and back to the API with minimal impact on user experience.

Flow:

  1. Perform GET of the element that are ready for payment.
  2. Find the link with the name "payment".
  3. (optional) Append a "returnUrl" parameter to the url. The user will be redirected to the web address given in the parameter when the payment is complete. The domain of the address must have been approved for the use of the API (API key of type "Web").
  4. Open the URL in a browser or web view. The user completes the payment process.
  5. There are two ways to return to the API:
    1. With returnUrl - The last step in the process will be a redirect to the return address. The URL will have a new parameter named "resource". This will be the URI to the element. (Elements that are archived will get a new messageId.)
    2. Without returnUrl - The last response in the process will have status 204 and the Location field in the header will contain the URI to the element.(Elements that are archived will get a new messageId.)
External authentication

The goal with this integration is to have the user authenticated with Altinn without too many steps. This can be used for users that have browsers with settings that prevent the IDPorten SSO solution from working correctly as well as for those web applications that do not have any integration with IDPorten.

Flow:

  1. Send a request to "https://{env}/Pages/ExternalAuthentication/Redirect.aspx?returnUrl={address}". The value of requestUrl must be the address of the resource the user should go to when authentication is complete. The domain of the address must have been approved for the use of the API (API key of type "Web").
  2. Possible situations:
    1. The user is already authenticated with IDPorten or directly in Altinn. No actions from the user will be needed.
    2. The user is not authenticated and Altinn displays the authentication options. The user authenticates themselves.
  3. Possible outcomes:
    1. The user is successfully authenticated. Altinn proceeds and prepare to return the user to the provided address.
    2. The user is not authenticated. The user must remain on the authentication page.
  4. Authenticated users are given an authentication cookie called .ASPXAUTH with session data. This cookie must be included in all REST API requests that requires authentication.
  5. Altinn creates a response with a redirect to the address given in the requestUrl parameter in step one.

OData filtering

OData can be used to enable filtering, paging and ordering of lists of elements returned by all methods returning a list. The filter option of Odata makes it possible to filter the resultlist based on the properties of the model returned. For example by applying the following parameter when requesting all messages for a given user: $filter=ServiceOwner eq 'Skatteetaten'.

Operations with support for OData queries will be set to a maximum page size of 50 elements, and to display all elements the external application using the api must enable paging. Paging in OData is done by passing the parameter $skip={number of elements to skip}.

The OData options supported so far are:

For more information about OData see OData.

Note: All requests to the REST API are currently subject to set limitations in the underlying platform with regards to how many messages can be fetched and authorized from the database. These limitations are applied before any OData filtering takes place, so in cases where there is a large number of active and/or archived messages, the returned list may be incomplete. When this occurs, an additional HTTP header X-Warning-LimitReached will be added to the response.

To work around this, you may supply additional query parameters to the request: dateFrom and dateTo, which both takes a datetime value in the form YYYY-MM-DDTHH:MM:SS. This dates will be applied to the underlying database query before any OData filtering occurs, enabling access to messages that would otherwise be unavailable due to the aforementioned limitations. (See example below; both parameters are optional, and may include an optional time specification)

https://www.altinn.no/api/my/messages?dateFrom=2018-01-20&dateTo=2018-01-20T23:59:59&$filter=...