link
Developer Pages

# Extra information and addons

Our signature API allows you to seamlessly integrate extra information into the response, please see the available types below.

# PAdES file configuration

You can configure the look of the PAdES files that are generated after signing. Follow these steps:

  1. Open the developer dashboard (opens new window).
  2. Open your account and go to Settings > Signature PAdES settings.
  3. In the "Add data" field, select the information that must be included in the PAdES files.
  4. In the "Signature Details Page" field, select where you want the information to appear.

click-to-zoom PAdES file configuration

# When is the information ready?

There are multiple ways to get notified when the extra information is ready to be downloaded.

# Asynchronously

If you can support it, our recommendation is to subscribe to the ResourceCreatedEvent which will be triggered when the information is ready.

You can read more about webhooks and events in the Events documentation.

# Synchronously

If you need the information immediately after the signer has completed the signature, the easiest way to collect the information is to let the signer wait a few seconds while the requested information is processed.

First, log in to the Dashboard and complete the following steps:

  1. Find your account: Account -> View account.
  2. Find "Settings API" on the account menu.
  3. Find the signature settings and click Override.
  4. Choose the desired success action:
    • "Continue when resources complete" if you don't need to wait on the file packaging right now (faster).
    • "Continue when all is complete" if you need both the signed files and the resources to be ready before the signer proceeds to your success page.
  5. Optional: Set max poll time in seconds (defaults to 30), if the files are not ready within this time the signer is sent to the error page.

Redirect: The signer is not redirected until everyting is ready

Webmessaging: When you recieve the sign_success webmessage, all the requested resources/files are ready for retrieval

Webhook/ Events: Listen for the resource created event as a webhook or in the .Net events client.

# Error handling

If you are using the webmessage/iframe approach, you should handle errors accordingly. The relevant error codes are:

SA-1030: The resources/files were not ready within the specified max poll time

SA-1031: A generic error occured when checking the signature status

SA-1032: The extra information / resource could not be fetched because of an error specific to this resource

# Extra info for a signer

If you add signer extra-info, the information will be retrieved for the specified signer.

# BankID API AML person sanction / PEP

Person screening with data enhancement enabled for nationalities where data enhancement is provided. For other nationalities, the data enhancement will be skipped.

# Step 1 - Create document

Note

If you also want a PDF report, you should add the bankIDApisAmlPersonSanctionPepReport addon in addition to bankIDApisAmlPersonSanctionPep. In the link array shown in step two below, a separate resource will be created for the report.

POST https://api.signicat.io/signature/documents

Request sample

{
    ....
    "signers": [{
        ...
            "extraInfo": {
                "types": ["bankIDApisAmlPersonSanctionPep"]                
            }

        ...        
    }]
    ....
}

# Step 2 - Retrieve document (after it is signed and the resources are ready)

GET https://api.signicat.io/signature/documents/{documentId}

Response sample

{
    ...
    "signers": [
        ...
        "links" : [{
            "href": "https://api.signicat.io/resources/...",
            "rel": "bankIDApisAmlPersonSanctionPep",
            "contentType": "application/json",
      "resourceStatus": "Success"
        }]
        ...
    ]
    ...   
}

# Step 3 - Retrieve resources

The URL can be found in the signer's link array.

GET https://api.signicat.io/resources/...

Response sample

{
  "nnin": "05297149484",
  "sanctionResults": [
    {
      "matchIndicator": 325,
      "comment": "(Mother’s name: Masouma Abd al-Rahman. Photo available for inclusion in the INTERPOL-UN Security Council Special Notice)",
      "aliasList": [
        "Najmuddin Faraj Ahmad",
        "Mullah Krekar",
        "Fateh Najm Eddine Farraj",
        "Faraj Ahmad Najmuddin"
      ],
      "addressList": [
        {
          "countryName": "Iraq",
          "countryCode": "IQ"
        },
        {
          "countryName": "Norway",
          "countryCode": "NO",
          "street": "10 Testesensgate",
          "postCode": "0101",
          "city": "Oslo"
        }
      ],
      "urlList": [
        "http://eur-lex.europa.eu/LexUriServ/LexUriServ.do?uri=OJ:L:2006:351:0009:0010:EN:PDF"
      ],
      "provider": "TRAPETS",
      "source": "EU_GLOBAL",
      "externalId": "3641",
      "lastUpdate": "2016-12-15T00:00:00",
      "firstUpdate": "2016-01-19T00:00:00",
      "name": "Najmuddin Faraj Ahmad"
    },
    {
      "matchIndicator": 325,
      "comment": "Mother’s name: Masouma Abd al-Rahman. Photo available for inclusion in the INTERPOL-UN Security Council Special Notice. Review pursuant to Security Council resolution 1822 (2008) was concluded on 20 May 2010.",
      "aliasList": [
        "Mullah Krekar",
        "Fateh Najm Eddine Farraj",
        "Faraj Ahmad Najmuddin",
        "NAJMUDDIN FARAJ AHMAD "
      ],
      "addressList": [
        {
          "countryName": "Iraq",
          "countryCode": "IQ"
        },
        {
          "countryName": "Iraq",
          "countryCode": "IQ",
          "street": "Olaqloo Sharbajer"
        },
        {
          "countryName": "Norway",
          "countryCode": "NO",
          "street": "Testesensgate 1",
          "postCode": "0101",
          "city": "Oslo"
        }
      ],
      "provider": "TRAPETS",
      "source": "UN_CONSOLIDATED_1",
      "externalId": "2762998",
      "lastUpdate": "2016-12-15T00:00:00",
      "firstUpdate": "2006-12-07T00:00:00",
      "name": "Mullah Krekar"
    }
  ],
  "pepResults": [
    {
      "matchIndicator": 500,
      "title": "Minister for Infrastructure",
      "aliasList": [
        "Anna Frida Wiktoria Johansson"
      ],
      "addressList": [
        {
          "countryName": "Sweden",
          "countryCode": "SE"
        }
      ],
      "urlList": [
        "http://www.government.se/government-of-sweden/ministry-of-enterprise-and-innovation/anna-johansson/",
        "https://sv.wikipedia.org/wiki/Anna_Johansson_(socialdemokrat)"
      ],
      "provider": "TRAPETS",
      "source": "PEP_Edge",
      "externalId": "SE.Government-372",
      "lastUpdate": "2016-12-15T00:00:00",
      "name": "Anna Frida Wiktoria Johansson"
    }
  ],
  "message": "NO MESSAGE"
}

# Full response model

The full response model can be found on the BankID website (opens new window)

# BankID API AML current address

Retrieves basic address information from the official address registry. Requires the signer's national ID number to be retrieved.

# Step 1 - Create document

POST https://api.signicat.io/signature/documents

Request sample

{
    ....
    "signers": [{
        ...
            "extraInfo": {
                "types": ["bankIDApisAmlCurrentAddress"]                
            }

        ...        
    }]
    ....
}

# Step 2 - Retrieve document (after it is signed and the resources are ready)

GET https://api.signicat.io/signature/documents/{documentId}

Response sample

{
    ...
    "signers": [
        ...
        "links" : [{
            "href": "https://api.signicat.io/resources/59219384eb3d4552889c554ab63c8468",
            "rel": "bankIDApisAmlCurrentAddress",
            "contentType": "application/json"
        }]
        ...
    ]
    ...   
}

# Step 3 - Retrieve resources

The URL can be found in the signer's link array.

{
  "CurrentAddress": {
    "Address": "Karl Johans gate 1B",
    "Postalcode": "0154",
    "City": "Oslo",
    "Country": "NO",
    "PersonStatus": "RESIDENT",
    "AddressStatus": "ORDINARY_RESIDENT",
    "RegisteredDate": "2015-06-06T14:34:58.3179726+02:00"
  }
}

# Full response model

The full response model can be found on the BankID website (opens new window)

# Addons

Our signature API allows you to seamlessly integrate addons into the response. Please see the available types below.

# Addons for a signer

If you add a signer addon, the addon will be added for this specific signer

# Secure share

If this addon is enabled, a background task will upload the signed files to a secure share bucket when the document has received all the required signatures. The signer will then recieve an email/SMS with a link to our secure share service to be able to retrieve the files securely.

You can configure how long the share should be available, which files to share, and more, in the Dashboard.

  • Find your account: Account
  • View account
  • Find "Settings API" on the account menu
  • Override the "Secure share for signature" setting set
# Step 1 - Create document
POST https://api.signicat.io/signature/documents

Request sample

{
    ....
    "signers": [{
        ...
            "addons": {
                "types": ["secureShare"]                
            }

        ...        
    }]
    ....
}
# Step 2 - Retrieve document (after it is signed and the resources are ready)

This step is optional, as the secure share link is shared by email/SMS unless otherwise specified in the account settings mentioned above.

A link is added in the response. This link points to the secure share api bucket, where you can modify the share job if you want to.

GET https://api.signicat.io/signature/documents/{documentId}

Response sample

{
    ...
    "signers": [
        ...
        "links" : [{
            "href": "https://api.signicat.io/share/buckets/{id}",
            "rel": "secureShare",
            "contentType": "application/json",
      "resourceStatus": "Success"
        }]
        ...
    ]
    ...   
}
# Screenshots

click-to-zoom

Signer logs in and is able to download the files: click-to-zoom

Last updated: 11/03/2022 13:43 UTC

← Demo →