---
title: "Link Electronic ID to email"
slug: "link-electronic-id-to-email"
updated: 2025-02-26T12:49:38Z
published: 2025-02-26T12:49:38Z
canonical: "docs.connect.visma.com/link-electronic-id-to-email"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.connect.visma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Link Electronic ID to email

Visma Connect can link electronic IDs with email address. Applications that wants this feature can enable it in [Developer Portal](/v1/docs/developer-portal), and Visma Connect will require users that sign in with electronic ID to link it to an email address.

Some applications might require the user to link e-ID to a specific email address. Visma Connect supports an API lookup feature that will request email address based on e-ID and present this to user for linking.

Contact Visma Connect to set this up.

## Sequence diagram

```plaintext
title Link electronic ID and email
 
User->Application: Enter application as\nnot authenticated
Application->Visma Connect: Request authentication\n/connect/authorize
Visma Connect->e-ID Idp: Request authentication
e-ID Idp->e-ID Idp: Authenticates user
e-ID Idp->Visma Connect: User authenticated\nwith e-ID
alt Application require e-ID linked to email and user is not linked to an email
    alt Application has link email lookup enabled
        Visma Connect->Application API: Which email does e-ID have?
        alt Success response
            Application API->Visma Connect: Return email address
            Visma Connect->Visma Connect: Ask user to link e-ID to email address
        else Error response
            Visma Connect->Visma Connect: User have to enter email address to link to e-ID
        end
    else Application does not have lookup enabled
        Visma Connect->Visma Connect: User have to enter email address to link to e-ID
    end
    Visma Connect->Visma Connect: Send email to user to verify\nemail with security code
    Visma Connect->Visma Connect: Link email to NIN
end
Visma Connect->Application: Authentication completed
Application->User: Allow user into application
```

![](https://cdn.document360.io/0ec30182-e256-4eca-ab6a-d067d83d0895/Images/Documentation/IdentityProvider_LinkEIDToEmail.png)

## API implementation

You must implement your applications Link Electronic ID API method in a Public REST API endpoint that supports HTTP POST on the method.

This API must be exposed as a non-interactive API in the [Developer Portal](/v1/docs/developer-portal) that you make **Private** shared only with the team called **Identity (Connect)**.

For Authorization it must use Visma Connect OAuth 2.0 tokens. See: [Visma Connect OAuth 2.0 Bearer Token Authentication](/v1/docs/service-applications)

Your API base URI, e.g. [https://api.yourapplication.com/v1.0](https://api.yourapplication.com/v1.0) must be registered in Visma Developer Portal and this is the **aud** (audience) you must check in OAuth.

The POST endpoint must be exposed as a single method named specifically **LinkElectronicIdEmail** and be directly hosted under the base URI of your API.

E.g. if your API base URI is [https://api.yourapplication.com/v1.0](https://api.yourapplication.com/v1.0) then the method must be located at [https://api.yourapplication.com/v1.0/LinkElectronicIdEmail.](https://api.yourapplication.com/v1.0/LinkElectronicIdEmail.)

### Request

The bearer token (client_credentials) will contain the following information:

- aud: **your APIs base URL**
- client_id: **connectidp**
- scope: **<your_api_id>:linkelectronicid** → You need to register this scope beforehand in Developer Portal in order for Visma Connect’s backend to be able to integrate with your API.

**POST** [https://api.yourapplication.com/v1.0/LinkElectronicIdEmail](https://api.yourapplication.com/v1.0/LinkElectronicIdEmail)

**HTTP Headers**

- Authorization: **Bearer <client_credentials access token>**
- Content-Type: **application/json**

**HTTP POST body**

```json
{
  "national_identity_number": "12345678",
  "state": "abc123"
}
```

### Response

| HTTP status code | Body | Description |
| --- | --- | --- |
| 200 OK | ```json { "email": "user@example.com" } ``` | The email is found found on your side for the provided national identity number. This will force the user on Visma Connect side to link their email address to that identity. |
| 204 No Content | - | Return when you do not want the national identity number to be linked to an email. |
| 404 Not Found | - | Return if no email is found for national identity number; user must than write which email to link it to. |
| Everything else | We read and log the response body in this case | We treat this as an error on the client API side; user must than write which email to link it to. |

You must also in the Visma Developer Portal register an **API scope** which must be: **<resourceid>:linkelectronicid** where resourceid is the unique API ID you register in Visma Developer Portal; e.g. it will be named **myauthapi:linkelectronicid**. Ensure your API checks for presence of this scope in the access token.

After you have setup everything accordingly in Developer Portal, enabling this feature is still a manual process on Connect side.

You need to register a Jira ticket on the CONNECT components and specify 3 things:

1. The API ID → ID of the API that acts as the Link Electronic ID API on which Connect will call the **/LinkElectronicIdEmail** endpoint
2. The Application ID → the application for which Electronic ID linking should be activated on.
3. The environment where you want this activated (staging or production).

## API performance

Be sure you performance test your API to ensure it can take the onboarding volume caused by first-time sign in to your application by each user. **If a call takes more than 5 seconds, we will timeout the connection and consider it as an unsuccessful operation**.

Note that the electronic ID linking will only take place from your own sign in page registered with Visma Connect, so ensure all your users onboard from there.

E.g. A user signing in from [https://connect.visma.com](https://connect.visma.com), Visma Home landing page [http://home.visma.com](http://home.visma.com) or any other Application registered with Connect **WILL NOT** call your API and other authentication flows will be applied according to that application’s settings.

## Registering your API in Visma Developer Portal

Sign into Visma Developer Portal to register your API; then get in touch with the Identity team to have them enable this feature for your Application towards your API.

Give them the "client_id" (Application ID) and "resource_id" (API ID) from the Visma Developer Portal.

| Environment | Visma Developer Portal |
| --- | --- |
| Staging (default test env.) | [https://oauth.developers.stagaws.visma.com/](https://oauth.developers.stagaws.visma.com/) |
| Production | [https://oauth.developers.visma.com/](https://oauth.developers.visma.com/) |