Developer Pages

# 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:

  1. Prepare your development environment
  2. Authenticate to the Data Verification API
  3. Call the Organisation and Person Basic endpoints with test data
  4. 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.

Page contents

# 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:

  1. Sign up to the Signicat Dashboard (opens new window).
  2. 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:

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:

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

# 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

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:

  1. Open a terminal and go to the src folder.
  2. 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:

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

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

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 (opens new window).

Last updated: 11/04/2024 07:47 UTC

← API overview →