Signing API¶

The Signing API (also called the Integration API) lets your app embed signing in its own workflow. You provide the document and identify the signer; esigna has the signer approve the signature with their electronic ID from Auðkenni and returns the signed document to you.

How it works¶

Signing is asynchronous: the signer approves the request on their phone, which takes as long as it takes. The flow is:

1. (Optional) Create a busy signal if several signers will sign the same file.
2. Start a signing request. esigna asks the signer to approve it and returns a pollingId.
3. Poll with the pollingId until the signed document comes back or the request ends.

Step 1: Create a busy signal¶

POST /api/v1/signing/busy-signal

If several signers sign the same file one after another, use a busy signal so that two signings can't run on the file at once: a second signature started before the first is applied would invalidate it.

Create one busy signal per document and pass its ID with every signing request for that document. A signing request holds the signal from its start call until polling for it ends (signed or failed), and for at most 5 minutes.

You don't need one if each signer signs their own copy of the file.

Response¶

1
2
3

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

If a signing request starts while the signal is held, the start call answers 423 Locked:

1
2
3
4
5

{
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "blockedBy": "user-id-from-your-system",
    "blockedUntil": "2026-10-09T12:05:00Z"
}

A busy signal ID that doesn't exist gives 404 Not Found.

Step 2: Start a signing request¶

POST /api/v1/signing

Request body¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
    "file": {
        "type": "Pdf",
        "name": "contract.pdf",
        "contentB64": "JVBERi0xLjQK..."
    },
    "signer": {
        "kennitala": "0101302989",
        "signingMethod": "AudkenniApp"
    },
    "signatureImage": {
        "alignment": "BottomLeft",
        "positioning": "Auto"
    }
}

Response: 200 OK¶

1
2
3
4
5
6

{
    "pollingId": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "expiresIn": 300,
    "interval": 2,
    "verificationCode": null
}

With AudkenniApp, as here, verificationCode is null: the code arrives in a poll response. With AudkenniSim it is in this response. See Verification code.

File¶

Signer¶

Signing methods¶

Signature image¶

For PDFs you can show the signature as a stamp on the page. Without signatureImage the signature is still in the document and valid, but nothing is drawn.

The simplest form lets esigna do everything: set positioning to Auto and leave out the image. esigna then draws its standard stamp (the signer's name from their certificate, kennitala, signing time and reason) and puts it in the first free spot on the page, starting from the chosen corner and avoiding existing signatures and the page's content. With several signers, each stamp lands in the next free spot.

The offsets are measured on the page as it is displayed, so a page rotated in the PDF is handled for you and the stamp is drawn upright. With Manual positioning, stamps on the same page must not overlap.

Advanced signature settings¶

These control the signature's cryptographic properties. Most integrations leave them out.

Busy signal¶

Errors¶

An Auðkenni refusal looks like this. errorCode is esigna's code; errorDescription carries Auðkenni's own code:

1
2
3
4
5

{
    "error": "access_denied",
    "errorCode": "UserNotFound",
    "errorDescription": "audkenni_404"
}

Step 3: Poll for the signed document¶

GET /api/v1/signing/{pollingId}

Poll until the signer finishes or the request ends. Wait at least interval seconds between polls.

Signed: 200 OK¶

1
2
3

{
    "signedFileB64": "JVBERi0xLjQK..."
}

signedFileB64 is the signed document in Base64. Polling is finished.

Not finished, or failed: 400 Bad Request¶

1
2
3
4
5
6

{
    "error": "authorization_pending",
    "errorCode": "AuthorizationPending",
    "errorDescription": "The end user has not authenticated.",
    "verificationCode": "1234"
}

Gone: 404 Not Found¶

A pollingId answers 404 once its request has finished (signed or failed). An abandoned one is cleared by the next start call made after it is 15 minutes old; until then, polling it gives a 400 such as ExpiredToken.

Verification code¶

The signer's phone shows a 4-digit code that your app must also show, so the signer can check they are approving the right request.

• AudkenniSim: the code is in the start response (step 2).
• AudkenniApp: the code only exists once the signer's phone answers, so it appears in a poll response.

Check both: show the start response's code if it isn't null, otherwise show the code as soon as a poll response has one.

Polling¶

Error codes¶

errorCode is esigna's code for what Auðkenni answered. It can be null when Auðkenni gives an error esigna doesn't know.

Testing in the sandbox¶

The sandbox, https://sandbox-api.esigna.is, runs the Signing API without Auðkenni. Nobody signs with a real electronic ID: you create sandbox users to stand in for signers, and choose how each one answers.

Sandbox credentials are separate from production ones. Contact us and we email you a client ID and secret for the sandbox. Get tokens from the sandbox itself, POST https://sandbox-api.esigna.is/api/v1/auth/token, as described in Authorization.

Documents signed in the sandbox carry self-signed test certificates, so no validator accepts their signatures.

Sandbox users¶

These endpoints exist only in the sandbox: production answers 404 Not Found and leaves them out of its API reference. They take the same token as the signing endpoints and need no scope of their own.

POST /api/v1/sandbox/users

Request body¶

1
2
3
4
5
6
7

{
    "fullName": "Jón Jónsson",
    "kennitala": "0101302989",
    "phone": "6101234",
    "delayInSecondsBeforeAction": 0,
    "action": "Success"
}

Response: 200 OK¶

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

{
    "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "fullName": "Jón Jónsson",
    "kennitala": "0101302989",
    "phone": "6101234",
    "delayInSecondsBeforeAction": 0,
    "action": "Success",
    "createdAt": "2026-10-12T12:00:00Z",
    "updatedAt": "2026-10-12T12:00:00Z"
}

Each of your sandbox users needs its own kennitala and phone number.

GET /api/v1/sandbox/users lists your sandbox users, with the same fields except createdAt and updatedAt.

PUT /api/v1/sandbox/users/{uuid} changes one and returns 204 No Content. Send only the fields you want to change; a field left out or null keeps its value. The test certificates keep the name the user was created with, so a new fullName doesn't change the name on the stamp.

How a sandbox user answers¶

Start and poll as in step 2 and step 3. The sandbox picks the sandbox user by signer.kennitala with AudkenniApp, and by signer.phone with AudkenniSim; with AudkenniSim, signer.kennitala is not compared with the user's. The verification code is always 1234.

With no delay and action: Success, the calls answer:

With AudkenniApp the first poll always answers AuthorizationPending, and the code first appears there, as in production.

The user's settings change what comes after the start call:

• Delay: until delayInSecondsBeforeAction seconds have passed since the start call, polls answer AuthorizationPending. Use it to test your polling loop and how your app shows the code.
• Cancel: once the delay has passed, the poll answers 400 with UserCancelled. Polling is over; the next poll answers 404.

1
2
3
4
5
6

{
    "error": "access_denied",
    "errorCode": "UserCancelled",
    "errorDescription": "mssp_401",
    "verificationCode": null
}

If none of your sandbox users matches, the request ends with UserNotFound, from the start call or the first poll. No other errorCode occurs in the sandbox.