Code examples

This page guides you through the steps to build a simple application to integrate with the Signicat Data Verification API using .NET 8.0.

The code examples show how to set up a minimal ASP.NET Core project to fetch basic information about persons and organisations from the API using token-based authentication.

Here are the steps that you will follow:

Prepare your development environment
Authenticate to the Data Verification API
Call the Organisation and Person Basic endpoints with test data
Review the API response

You can extend the code examples in this guide to cover other scenarios by using the test data and the sources documented respectively in the Test data and Data sources pages.

Prerequisites

To use the Data Verification services, you need to have configured at least:

Organisation and account in the Signicat Dashboard
API client credentials

The subsections below explain how to configure each requirement.

Configure the Signicat Dashboard

This guide assumes you have completed the following initial preparations:

Sign up to the Signicat Dashboard.
In the Signicat Dashboard, set up an organisation and an account. For instructions how to do this, see the Initial setup page. It is also possible to add a domain, but this is not required for this product.

Sandbox account

We recommend that you create a sandbox account to test our services before implementing them in production. Be aware that you must set up the sandbox and production accounts separately.

Set up an API Client

To use to the Data Verification API, you need to set up an API Client (with a secret) and configure the correct permissions.

Follow the instructions to:

Set up an API Client to obtain a Client ID and a Client secret.
Select the correct Permissions to connect to the Data Verification API.

Permissions for Data Verification

Data Verification for natural persons to connect to data sources about natural persons
Data Verification for organisations to connect to data sources about organisations

Then, return here and continue with the next steps of this guide.

Prepare your development environment

Before you begin, ensure that you have the following tools installed in your development machine:

.NET SDK 8.0

You will need the .NET CLI to run this example, read more about it at https://learn.microsoft.com/en-us/dotnet/core/tools/.

Clone and configure the project

Clone the code

Clone the repository to your local machine using the following command:

git clone https://github.com/signicat/sample-data-verification

Or, download the code compressed in a zip file:

Download full code example

The full code example includes all the files you need to run the sample application.

Preview application code

Program.cs
DataVerificationApiService.cs
TokenResponse.cs
TokenService.cs
TokenServiceConfig.cs

// Create a new WebApplication
var builder = WebApplication.CreateBuilder(args);

// Configure in-memory settings for TokenService
var inMemorySettings = new List<KeyValuePair<string, string?>> {
    new("TokenServiceConfig:GrantType", "client_credentials"),
    new("TokenServiceConfig:Scope", "signicat-api"),
    new("TokenServiceConfig:ClientId",  "<YOUR_CLIENT_ID>"),
    new("TokenServiceConfig:ClientSecret",  "<YOUR_CLIENT_SECRET>")
};

// Build configuration from in-memory settings
var configuration = new ConfigurationBuilder()
    .AddInMemoryCollection(inMemorySettings)
    .Build();

// Configure TokenServiceConfig using the built configuration
builder.Services.Configure<TokenServiceConfig>(
    configuration.GetSection("TokenServiceConfig"));

// Configure HttpClient for TokenService
builder.Services.AddHttpClient("TokenService", httpclient => {
    httpclient.BaseAddress = new Uri("https://api.signicat.com/auth/open/");
});
// Add TokenService as a singleton service
builder.Services.AddSingleton<TokenService>();

// Configure HttpClient for DataVerificationApiService
builder.Services.AddHttpClient("DataVerificationApiService", httpclient => {
    httpclient.BaseAddress = new Uri("https://api.signicat.com/info/lookup/");
});
// Add DataVerificationApiService as a singleton service
builder.Services.AddSingleton<DataVerificationApiService>();

// Build the application
var app = builder.Build();

// Set up a simple root route
app.MapGet("/", () => "Signicat Data Verification Sample App.");

// Set up routes for person and organization information
var person = app.MapGroup("/person");
person.MapGet("/basic/{country}/{source}/{id}", GetPersonBasic);

var organization = app.MapGroup("/organization");
organization.MapGet("/basic/{country}/{source}/{id}", GetOrganizationBasic);

// Run the application
app.Run();

// Handler for getting basic person information
static async Task<IResult> GetPersonBasic(string country, string source, string id, DataVerificationApiService dataVerificationApiService)
{
    var response = await dataVerificationApiService.GetPersonBasic(country, source, id);
    return TypedResults.Ok(response);
}

// Handler for getting basic organization information
static async Task<IResult> GetOrganizationBasic(string country, string source, string id, DataVerificationApiService dataVerificationApiService)
{
    var response = await dataVerificationApiService.GetOrganizationBasic(country, source, id);
    return TypedResults.Ok(response);
}

// DataVerificationApiService class to handle API requests for person and organization information
public class DataVerificationApiService(IHttpClientFactory httpClientFactory, TokenService tokenService)
{
    // Get basic person information from the API
    public async Task<string> GetPersonBasic(string country, string source, string id)
    {
        return await MakeRequest($"countries/{country}/persons?identityNumber={id}&source={source}");
    }

    // Get basic organization information from the API
    public async Task<string> GetOrganizationBasic(string country, string source, string id)
    {
        return await MakeRequest($"countries/{country}/organizations/{id}?source={source}");
    }

    // Helper method to make an authenticated API request
    private async Task<string> MakeRequest(string url)
    {
        var httpClient = httpClientFactory.CreateClient("DataVerificationApiService");
        
        // Get an authentication token from the TokenService
        TokenResponse? token;
        try
        {
            token = await tokenService.GetToken();

            if (token == null) return "Something went wrong fetching the authentication token";
        }
        catch (Exception ex)
        {
            return ex.Message;
        }
        
        // Set the authorization header with the access token
        httpClient.DefaultRequestHeaders.Authorization =
            new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", token.AccessToken);

        // Make the API request
        var httpResponseMessage = await httpClient.GetAsync(url);

        // Handle the API response
        if (!httpResponseMessage.IsSuccessStatusCode)
        {
            if (httpResponseMessage.StatusCode == System.Net.HttpStatusCode.NotFound)
                return "The entity you tried to look up was not found at the source.";
            else 
                return httpResponseMessage.StatusCode + ", " + httpResponseMessage.ReasonPhrase;
        }

        // Read and return the response content
        var responseContent = await httpResponseMessage.Content.ReadAsStringAsync();

        return responseContent;
    }
}

using System.Text.Json.Serialization;

// TokenResponse class representing the token response
public class TokenResponse
{
    [JsonPropertyName("access_token")]
    public string? AccessToken { get; set; }
}

using Microsoft.Extensions.Options;

// TokenService class to handle authentication token requests
public class TokenService(IHttpClientFactory httpClientFactory, IOptions<TokenServiceConfig> configuration)
{
    private readonly TokenServiceConfig _configuration = configuration.Value;

    // Get an authentication token from the token service
    public async Task<TokenResponse?> GetToken()
    {
        var httpClient = httpClientFactory.CreateClient("TokenService");

        // Prepare the request content with client credentials
        var requestContent = new List<KeyValuePair<string, string?>>
        {
            new("grant_type", _configuration.GrantType),
            new("scope", _configuration.Scope),
            new("client_id", _configuration.ClientId),
            new("client_secret", _configuration.ClientSecret)
        };

        // Make the token request
        var httpResponseMessage =
            await httpClient.PostAsync("connect/token", new FormUrlEncodedContent(requestContent));

        // Handle the token response
        if (!httpResponseMessage.IsSuccessStatusCode)
            throw new Exception(httpResponseMessage.StatusCode.ToString());

        // Read and deserialize the token response
        var responseContent = await httpResponseMessage.Content.ReadAsStringAsync();
        return System.Text.Json.JsonSerializer.Deserialize<TokenResponse>(responseContent);
    }
}

// TokenServiceConfig class representing configuration properties
public class TokenServiceConfig
{
    public string? GrantType { get; set; }
    public string? Scope { get; set; }
    public string? ClientId { get; set; }
    public string? ClientSecret { get; set; }
}

Limitations of the code example

The code used in this sample application is meant to be easy to understand and may not follow best practices. Make sure your code adheres to coding and security standards, when preparing your applications for production.

Configure the credentials

To make requests to the API endpoints, the application first needs to authenticate to the Signicat authorisation server using your API client credentials.

Edit the API client credentials, the client ID and the client secret, in the Program.cs file.

Replace <YOUR_CLIENT_ID> and <YOUR_CLIENT_SECRET> with the values of your API Client.

// Configure settings for TokenService
var inMemorySettings = new List<KeyValuePair<string, string?>> {
    new("TokenServiceConfig:GrantType", "client_credentials"),
    new("TokenServiceConfig:Scope", "signicat-api"),
    new("TokenServiceConfig:ClientId",  "<YOUR_CLIENT_ID>"),
    new("TokenServiceConfig:ClientSecret",  "<YOUR_CLIENT_SECRET>")
};

Authenticate to the API

To make requests to the API, you first need to obtain an access token.

To do this, you need to call the https://api.signicat.com/auth/open/connect/token address with your client credentials in the request content. Then, the authorisation server provides your application with a token that can be used to interact with the API.

The TokenService class handles the request to the Signicat API authorisation server, as shown below:

// TokenService class to handle authentication token requests
public class TokenService
{
    private readonly IHttpClientFactory _httpClientFactory;
    private readonly TokenServiceConfig _configuration;

    public TokenService(IHttpClientFactory httpClientFactory, IOptions<TokenServiceConfig> configuration)
    {
        _httpClientFactory = httpClientFactory;
        _configuration = configuration.Value;
    }

    // Get an authentication token from the token service
    public async Task<TokenResponse?> GetToken()
    {
        var httpClient = _httpClientFactory.CreateClient("TokenService");

        // Prepare the request content with client credentials
        var requestContent = new List<KeyValuePair<string, string?>>
        {
            new("grant_type", _configuration.GrantType),
            new("scope", _configuration.Scope),
            new("client_id", _configuration.ClientId),
            new("client_secret", _configuration.ClientSecret)
        };

        // Make the token request
        var httpResponseMessage =
            await httpClient.PostAsync("connect/token", new FormUrlEncodedContent(requestContent));

        // Handle the token response
        if (!httpResponseMessage.IsSuccessStatusCode)
            throw new Exception(httpResponseMessage.StatusCode.ToString());

        // Read and deserialize the token response
        var responseContent = await httpResponseMessage.Content.ReadAsStringAsync();
        return System.Text.Json.JsonSerializer.Deserialize<TokenResponse>(responseContent);
    }
}

The Signicat API authorisation server validates your client credentials and returns an access token that grants your application access to the Data Verification API.

Run the application

To run the application locally on your machine:

Open a terminal and go to the src folder.
Enter the dotnet run command.

Checkpoint

Now that you have configured the credentials and run your application, verify that:

Navigating to http://localhost:7650 in your browser, you can view the "Signicat Data Verification Sample App." text.

Retrieve data about an organisation

When calling the Basic endpoint of the Data Verification API, you can retrieve basic information about an organisation, such as name, address and contact.

In the API request, you need to specify:

Organisation ID
Country code
Data source

Data sources

Note that specifying a data source is optional when you use the Data Verification API outside the scope of this guide. By default, the API selects the best source available in your portfolio in the Dashboard.

Learn more about data sources in the Data sources page.

Build the API request

With the sample application running in the background, you can perform an API request using your browser.

When you navigate to a specific URL path, the application:

Makes a call to the API
Retrieves the data
Displays the response as a string

You can build your URL path using the following URL structure:

http://localhost:7650/organization/basic/{country}/{source}/{id}

Example

For example, you can look up information about Signicat in the Brønnøysundregistrene (business registry in Norway) using the Basic organisation endpoint in the background.

To do this, use the following values:

Country code	Organisation ID	Data source
`no`	`989584022`	`no-brreg`

and build the URL like:

http://localhost:7650/organization/basic/no/no-brreg/989584022

Checkpoint

Now, verify that:

Navigating to http://localhost:7650/organization/basic/no/no-brreg/989584022 in your browser you can view the response from the API.

Advanced code analysis

In this section, you can find additional details to help you understand how the application code works.

Click to expand

The application builds the URL routes with the following code:

src/Program.cs
... 
var organization = app.MapGroup("/organization");
organization.MapGet("/basic/{country}/{source}/{id}", GetOrganizationBasic);
... 

When you navigate to the organisation URL, the GetOrganizationBasic handler is called:

src/Program.cs
...
// Handler for getting basic organization information
static async Task<IResult> GetOrganizationBasic(string country, string source, string id, DataVerificationApiService dataVerificationApiService)
{
    var response = await dataVerificationApiService.GetOrganizationBasic(country, source, id);
    return TypedResults.Ok(response);
}
...

This triggers the DataVerificationApiService class, which contains the GetOrganizationBasic method:

src/DataVerificationApiService.cs
// DataVerificationApiService class to handle API requests for person and organization information
public class DataVerificationApiService(IHttpClientFactory httpClientFactory, TokenService tokenService)
{
    ...
    // Get basic organization information from the API
    public async Task<string> GetOrganizationBasic(string country, string source, string id)
    {
        return await MakeRequest($"countries/{country}/organizations/{id}?source={source}");
    }
    ...
}

The method receives the values country, source, id from the URL route and formats them into a request to the Data Verification API Basic organisation endpoint, using the following structure:

https://api.signicat.com/info/lookup/countries/{country}/organizations/{id}?source={source}

The complete cURL request with an access token would look like this:

curl -X GET https://api.signicat.com/info/lookup/countries/no/organizations/989584022?source=no-brreg
   -H "Accept: application/json"
   -H "Authorization: Bearer {token}"

Retrieve data about a person

To retrieve basic information about a person, you can use the Data Verification API Persons Basic endpoint.

Using the application, you can get this information using the URL route:

http://localhost:7650/person/basic/{country}/{source}/{id}

Substitute the {country}, {source}, and {id} variables with actual values.

You can browse synthetic test data for each data source in the Test data page.

Example

For example, you can use synthetic data provided by Tenor test data for the Norge Folkeregisteret (Norway National Registry):

Country code	Identity number	Data source
`no`	`13917099981`	`no-freg`

Checkpoint

Now, verify that:

Navigating to http://localhost:7650/person/basic/no/no-freg/13917099981 in your browser you can view the response from the API.

Next steps

Learn more about the Data Verification API to extend your application and integrate with more endpoints:

Data Verification API

Retrieve information about natural persons or organisations

API overview

Learn about the features of the Data Verification API

Questions, comments, or suggestions? Check out our community.

Code examples

Prerequisites​

Configure the Signicat Dashboard​

Set up an API Client​

Prepare your development environment​

Clone and configure the project​

Clone the code​

Configure the credentials​

Authenticate to the API​

Run the application​

Retrieve data about an organisation​

Build the API request​

Advanced code analysis​

Retrieve data about a person​

Next steps​

Prerequisites

Configure the Signicat Dashboard

Set up an API Client

Prepare your development environment

Clone and configure the project

Clone the code

Configure the credentials

Authenticate to the API

Run the application

Retrieve data about an organisation

Build the API request

Advanced code analysis

Retrieve data about a person

Next steps