Signing PDF documents

Upload a PDF document

The POST /v3/document endpoint is used to upload PDF documents before starting the signing process.

POST /v3/document
Authorization: Basic ${ base64(apiKey + ':' + secretKey) }
Content-Type: multipart/form-data; boundary=boundary

--boundary
Content-Disposition: form-data; name="my-file"; filename="my-file.pdf"
// File content

Response:

HTTP/2.0 201 Created

{
  "id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
  "hash": "..."
}

Start PDF sign

The POST /v3/bankid-no/sign endpoint is used to sign a document using BankID (NO).

POST /v3/bankid-no/sign
Authorization: Basic ${ base64(apiKey + ':' + secretKey) }

{
  "documents": ["1668b9da-bff1-4dfc-ad48-60507b5a8d12"],
  "refId": "12398698",
  "redirectUrl": "https://..."
}

Parameter	Required	Description
documents	Yes	An array of document ID's to sign.
refId	No	Reference ID which will be included in a Collect and in the redirect.
redirectUrl	No	Custom redirect URL, must be whitelisted.

Response:

IDkollen will respond with HTTP status 201 for successful request, or 4xx/5xx on errors. For more information about errors, please see the Errors section.

HTTP/2.0 201 Created

{
  "id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
  "refId": "12398698",
  "status": "PENDING",
  "url": "https://..."
}

Property	Description
id	Authentication id, used to cancel or get the status of this sign request.
refId	The refId given in the request, if any.
url	The URL where the end user can sign.

Fetch result

The GET /v3/bankid-no/sign/{{id}} endpoint is used to check the status of a sign request.

NOTE: This endpoint is rate limited to one request per second.

GET /v3/bankid-no/sign/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }

This endpoint will respond with a HTTP status of 404 if the sign session has expired.

The status of a sign can be either one of: PENDING, COMPLETED or FAILED.

Pending

{
  "id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
  "refId": "12398698",
  "status": "PENDING"
}

Parameter	Description
refId	The refId given in the request, if any.

Completed

{
  "id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
  "refId": "12398698",
  "status": "COMPLETED",
  "ssn": "YYYYMMDDXXXX",
  "name": "Firstname Lastname",
  "givenName": "Firstname",
  "surname": "Lastname",
  "birthDate": "1908-09-29",
  "signedDocuments": [
    {
      "id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
      "hash": "..."
    }
  ]
}

Parameter	Description
refId	The refId given in the request, if any.
ssn	The Norwegian personal identification number of the authenticated user. null if requestSsn was unset.
name	The full name of the signing user.
givenName	The given name of the signing user.
surname	The surname of the signing user.
birthDate	The birth date of the signing user.
signedDocuments	Present for signs, an array of document ID's.

Failed

{
  "id": "1668b9da-bff1-4dfc-ad48-60507b5a8d12",
  "refId": "12398698",
  "status": "FAILED",
  "error":  "INVALID_ID"
}

Parameter	Description
refId	The refId given in the request, if any.
error	An error code describing the reason for why the sign failed.

The error may be one of the following values:

Code	Description
AUTH_FAILED	A generic code for any kind of failure.
CANCELLED	The authentication was cancelled either by the user or the partner.
INVALID_ID	The ID has expired or is otherwise invalid.
INTERNAL_ERROR	An internal error occurred causing the authentication to fail.
SESSION_TIMEOUT	The authentication expired or timed out.
UNSUPPORTED_CLIENT	The client used for the authentication is not supported.

New error codes may be added in the future without prior notice. The partner should therefore handle unknown error codes in their implementations.

Fetch signed document

The GET /v3/document/{{id}} endpoint is used to receive a signed document.

GET /v3/document/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }

Cancel signing

The DELETE /v3/bankid-no/sign/{{id}} endpoint is used to cancel an ongoing BankID (NO) signing.

DELETE /v3/bankid-no/sign/{{id}}
Authorization: Basic ${ base64(accountId + ':' + secretKey) }

IDkollen will respond with HTTP status 204 for successful request, or 4xx/5xx on errors. For more information about errors, please see the Errors section.