# @taktikal/core-api > Functions for working with the Core API Latest version **4.3.0** (published 2026-03-18) · ISC license · 0 weekly downloads ## Install ```sh npm install @taktikal/core-api pnpm add @taktikal/core-api yarn add @taktikal/core-api bun add @taktikal/core-api ``` ## Health **Score 60/100 (C)** — status: stable. Positive: has types; esm support; no vulnerabilities; high quality score. Warnings: low downloads. ## Facts | | | |---|---| | Version | 4.3.0 | | Published | 2026-03-18 | | First published | 2020-01-31 | | Weekly downloads | 0 | | License | ISC | | TypeScript types | bundled | | Module format | ESM + CommonJS | | Dependencies | 2 | | Unpacked size | 124.4 KB | | Known vulnerabilities | 0 (+29 in 1 direct dependencies) | | Install scripts | no | | Author | Taktikal | | Maintainers | bjark, alexharri | ## Links - npm: https://www.npmjs.com/package/@taktikal/core-api - Repository: https://github.com/TaktikalTeam/npm-coreApi - Homepage: https://taktikal.com - Issues: https://github.com/TaktikalTeam/npm-coreApi/issues - npm.io page: https://npm.io/package/@taktikal/core-api ## Dependencies (2) - [yup](https://npm.io/package/yup.md) 1.3.2 - [axios](https://npm.io/package/axios.md) 1.6.2 ## Recent versions - 4.3.0 (latest) — 2026-03-18 - 4.2.2 — 2025-04-04 - 4.2.1 — 2024-05-16 - 4.2.0 — 2023-11-28 - 4.1.1 — 2022-04-05 - 4.1.0 — 2022-01-24 - 4.0.0 — 2021-12-06 - 3.6.1 — 2021-11-04 - 3.6.0 — 2021-10-29 - 3.5.0 — 2021-06-24 - 3.4.0 — 2021-06-24 - 3.3.2 — 2021-06-16 - 3.2.0 — 2021-05-31 - 3.1.3 — 2021-03-11 - 3.1.2 — 2021-03-11 - … 22 more at https://npm.io/package/@taktikal/core-api/versions ## README # Config ## `setCoreApiUrl()` Sets the default Core API URL that will be used by fns. ```ts setCoreApiUrl(apiUrl): Promise; ``` - `apiUrl (string)` # Functions ## `processSignDocument()` High level function that deals with signing a document for a Signee in a SigningProcess. ```ts processSignDocument(startSignOptions, [options]): Promise; ``` - `startSignOptions (ProcessStartSignOptions)` - `options ({ apiUrl?: string })` The `ProcessStartSignOptions` look like so: ```ts interface ProcessStartSignOptions { signeeKey: string; processKey: string; onStartSign: { success: (controlCode: string) => void; certificateNotActive: () => void; locked: (lockedBy?: string) => void; pinBlocked: () => void; error: (e: any) => void; }; onSign: { success: (signedDocument: CoreApiSignedDocument) => void; userCancelled: () => void; timeout: () => void; error: (e: any) => void; }; onComplete?: () => void; } ``` The optional `onComplete` fn can be used for state cleanup. It is called: - When creating the signing request fails - When signing fails - When signing is successful ### Signing a document The process of signing a document goes along these lines: #### 1. The user clicks the "Sign document" button When the button is clicked, we send a request to the Core API to start signing the document. A "pending" state of some sort should be shown to the user. #### 2. We receive a response The response we are hoping for is a `token` and `controlCode`. - The `token` is a unique token that can be used to check the status of the signing request. - The `controlCode` is a 4 digit code that will be shown on the user's phone. It should be shown in the UI as well so the user can confirm that the signing request came from you. We can receive a few types of errors when starting signing: - `pinBlocked` means that the users has entered the PIN for his eID incorrectly too many times and it has been blocked. The user will have to visit the bank or Auðkenni to get this resolved. - `locked` means that another user is currently signing the same document. - `certificateNotActive` means that the users eID exists but is not active. - `error` is an unexpected error. May be a network connectivity issue or any other issue that happens from time to time. #### 3. Wait until document has been signed We periodically check whether or not the document has been signed. The result can be one of the following: - `success` means that we successfully signed the document! - `userCancelled` means that the user received the signing request but cancelled it manually. - `timeout` means that the user did not respond to the signing request in time. - `error`, like before, is an unexpected error. ### Dealing with different errors When starting signing the `certificateNotActive` and `pinBlocked` errors are, for the time being, irrecoverable. The user should not be prompted to retry signing, he should instead be moved to an "error" state that instructs him to go fix the issue with his eID. After signing has successfully started, the user should be moved to a new step where the `controlCode` is shown in big and bold letters. It should also be made clear to the user that he should check his phone for the signing request, since users may or may not be familiar with how signing documents takes place. Errors that are encountered during signing (`userCancelled`, `timeout`) are temporary so the user should be promted to retry signing. ### Error messages We suggest the following error messages: #### PIN blocked ``` Pin númer hefur verið slegið inn of oft rangt og hefur verið læst. Þú þarft að fara í eina af skráningarstöðvum Auðkennis hjá t.d. banka eða fjarskiptafyrirtæki til að virkja skilríkið. Framvísa þarf ökuskírteini eða vegabréfi. ``` #### Certificate not active ``` Skilríki á síma er ógilt. Þú þarft að fara í eina af skráningarstöðvum Auðkennis hjá t.d. banka eða fjarskiptafyrirtæki til að endurnýja skilríkið. Framvísa þarf ökuskírteini eða vegabréfi. ``` #### Locked With `lockedBy`: ``` ${lockedBy} er að undirrita skjalið, prófaðu aftur eftir augnablik ``` Without: ``` Annar undirritandi er að undirrita skjalið, prófaðu aftur eftir augnablik ``` #### User cancelled ``` Þú virðist hafa hætt við undirritun ``` #### Timeout ``` Undirritun rann út á tíma. Gleymdirðu nokkuð að athuga símann? ``` ## `authenticate()` Takes in a flow key and a user's phone number and authenticates the user via eID. ```ts authenticate(flowKey, phoneNumber, [options]): Promise; ``` - `flowKey (string)` - `phoneNumber (string)` - `options ({ apiUrl?: string, type: "name" | "name_and_address" })` Returns a `Promise` that resolve to `CoreApiNameAuthResponse` if the type is `"name"` and `CoreApiNameAddressAuthResponse` if the type is `"name_and_address"`. ```ts export interface CoreApiNameAuthResponse { name: string; ssn: string; phoneNumber: string; token: string; flowKey: string; meta: {}; } export interface CoreApiNameAddressAuthResponse { name: string; ssn: string; phoneNumber: string; address: string; postalCode: string; city: string; token: string; flowKey: string; meta: { GenderCode: NationalRegistryGenderCode; }; } ``` ## `getFlow()` Gets a flow by flow key. ```ts getFlow(flowKey, [options]): Promise; ``` - `flowKey (string)` - `options ({ apiUrl?: string })` Returns a `GetFlowResponse`. ```ts export type GetFlowResponse = | { status: "ok"; flow: T; } | { status: "not_found"; flow: null; } | { status: "flow_key_not_valid"; flow: null; }; ``` The flow's type will be one of `RenderFlow`, `DropAndSign` and `FillAndSign`. If you want a specific type of flow, consider using one of the more specific "get flow by type" functions in the next section. ## `getDropAndSignFlow()`, `getFillAndSignFlow()` and `getRenderFlow()` Gets a flow of a specific type by flow key. ```ts getDropAndSignFlow(flowKey, [options]): Promise>; getFillAndSignFlow(flowKey, [options]): Promise>; getRenderFlow(flowKey, [options]): Promise>; ``` - `flowKey (string)` - `options ({ apiUrl?: string })` The return type is the same as from `getFlow()`, except an additional `status` is added to the `GetFlowResponse` called `"not_of_type"`. ```ts export type GetFlowByTypeResponse = | GetFlowResponse | { status: "not_of_type"; }; ``` ## `getSigningProcessBySignee()` Gets a signing process for a signee. ```ts getSigningProcessBySignee(processKey, signeeKey, [options]): Promise; ``` - `processKey (string)` - `signeeKey (string)` - `options ({ apiUrl?: string })` Returns a `GetSigningProcessResponse`. ```ts export type GetSigningProcessResponse = | { status: "ok"; signingProcess: CoreApiSigningProcess; } | { status: "error"; type: "process_not_found"; } | { status: "error"; type: "not_signee_of_process"; }; ``` ## `getSigningProcessList()` Gets a list of signing processes that all have a single signee. ```ts getSigningProcessList(keyString, [options]): Promise; ``` - `keyString (string)` - `options ({ apiUrl?: string })` The `keyString` is a list of process and signee key pairs: ``` sp00000:si0000000000,sp11111:si1111111111,sp33333:si3333333333 ``` It is expected that: - All processes were created by flows in the same company - All processes only have a single signee - All signees have the same `ssn` Returns a `GetSigningProcessListResponse`. ```ts export type GetSigningProcessListResponse = | { status: "ok"; processes: CoreApiSigningProcess[]; allSigned: boolean; companyName: string; companyKey: string; } | { status: "error"; type: "process_not_found"; processKey: string; signeeKey: string; } | { status: "error"; type: "not_signee_of_process"; processKey: string; signeeKey: string; } | { status: "error"; type: "not_single_signee_in_process"; processKey: string; } | { status: "error"; type: "different_signees_in_processes"; } | { status: "error"; type: "flows_from_different_companies"; }; ``` ## `processStartSignDocument()` Starts signing a document for a Signee in an existing Signingprocess. The returned `controlCode` should be shown to the user in the UI. The `token` should be passed to `processGetSignedDocument` which will get the result of the signing. ```ts processStartSignDocument(processKey, signeeKey, [options]): Promise; ``` - `processKey (string)` - `signeeKey (string)` - `options ({ apiUrl?: string })` Returns a `StartSignDocumentResponse`: ```ts export type StartSignDocumentResponse = | { status: "ok"; controlCode: string; token: string; } | { status: "error"; type: "locked"; lockedBy?: string; } | { status: "error"; type: "pin_blocked"; } | { status: "error"; type: "certificate_not_active"; }; ``` ## `processGetSignedDocument()` Should be called right after starting signing for a Signee in a SigningProcess. Waits until the signee has finished signing and returns the signed document. ```ts processGetSignedDocument(processKey, token, [options]): Promise; ``` - `processKey (string)` - `token (string)` - Token from `processStartSignDocument` - `options ({ apiUrl?: string })` Returns a `GetSignedDocumentResponse`: ```ts export type GetSignedDocumentResponse = | { status: "signed"; signedDocument: CoreApiSignedDocument; } | { status: "error"; type: "user_cancelled" | "timeout"; message: string; }; ``` ## `createSigningProcess()` Creates a SigningProcess that supports multiple Signees. ```ts createSigningProcess(companyKey, apiKey, createSigningProcessBody, [options]): Promise; ``` - `companyKey (string)` - `apiKey (string)` - The API key for the company - `createSigningProcessBody (CoreApiCreateSigningProcessBody)` - `options ({ apiUrl?: string })` Returns a `CoreApiSigningProcess`. ```ts export interface CoreApiCreateSigningProcessBody { flowKey: string; meta: Meta; createSignees: CoreApiCreateSigningProcessCreateSignee[]; pdfDocument?: string; pdfFileName?: string; requiresAuth?: boolean; attachments?: CoreApiSigningProcessAttachment[]; signInOrder?: boolean; signatureLocation?: CoreApiSignatureLocation; user?: string; activityDisplayName?: string; flattenDocument?: boolean; reminderRule?: `${number}:${number}`; } ``` The `pdfDocument` and `pdfFileName` are optional for `RenderFlow`s. ### `requiresAuth` Having the signee key for a signee in a SigningProcess acts as a form of authentication. This means that if a malicious third party obtains a signing URL with both the process key and signee key, he will be able to view the document to be signed. This does not let the third party sign the document, for that they would need the signee's eID. But the document may contain sensitive information. If that is the case, the `requiresAuth` option will send the user to `${url}${processKey}` instead of `${url}${processKey}/${signeeKey}`. If the signing front end only receives the process key, it should make the user `authenticate` into the SigningProcess before showing him the document (sending him to `${processKey}/${signeeKey}`). Note: Only the `app.taktikal.is/s/` signing page currently supports authenticating into a SigningProcess. Authenticating into a SigningProcess is currently not in the `@taktikal/core-api` package. Expect it to be added soon. ### `attachments` The `attachments` will be sent via email. This option is currently only used by Fill & Sign. ### `user` The email of the user that is creating the SigningProcess. This is only required for `DropAndSign` flows. ### `activityDisplayName` The `Activity Log` display name ### `flattenDocument` If documents include input fields we recommend flattening the document. This prevents the information in the input fields from being changed after signing. ### `reminderRule` Sends reminders, leave empty or null for no reminders. The format should be "{DAYS_AFTER_INITIAL_REMINDER}:{DAYS_BETWEEN_RECURRING_REMINDERS}". e.g. "1:3" will send one reminder after 1 day and then every three days after that. Valid values will be for first reminder to be sent between 0-30 days (0 means no reminder) and then send every 0-15 days. 0, again, meaning no reminders. f.e 0:10 would only send reminders every 10 days and 5:0 would only send one reminder after 5 days. ## `getSigneePdfBuffer()` Gets the PDF document for a Signee in a SigningProcess as a `Buffer`. ```ts getSigneePdfBuffer(processKey, signeeKey, [options]): Promise; ``` - `processKey (string)` - `signeeKey (string)` - `options ({ apiUrl?: string })` Returns a `Buffer`. Example usage: ```ts const buffer = await getSigneePdfBuffer(processKey, signeeKey); res.contentType("application/pdf"); res.send(buffer); ``` ## `nationalRegistryLookup()` Looks up a person in the Icelandic national registry. ```ts nationalRegistryLookup(type, flowKey, ssn, [options]): Promise>; ``` - `type ("name" | "name_and_address")` - `flowKey (string)` - `ssn (string)` - 10 digit kennitala - `options ({ apiUrl?: string })` Returns a `NationalRegistryLookupResponse` that contains a `CoreApiNationalRegistryNameResponse` if the `type` is `"name"` and contains a `CoreApiNationalRegistryNameAddressResponse` if the `type` is `"name_and_address"`. ```ts export interface CoreApiNationalRegistryNameAddressResponse { name: string; ssn: string; // 10 digits address: string; postalCode: string; // 3 digits city: string; } export interface CoreApiNationalRegistryNameResponse { ssn: string; name: string; } export type NationalRegistryLookupResponse = | { status: "ok"; data: T; } | { status: "not_found"; }; ``` ## `companyRegistryLookup()` Looks up a person in the Icelandic national company registry. ```ts companyRegistryLookup(flowKey, ssn, [options]): Promise; ``` - `flowKey (string)` - `ssn (string)` - 10 digit kennitala - `options ({ apiUrl?: string })` Returns a `CompanyRegistryLookupResponse` that contains a `CoreApiCompanyRegistryResponse`. ```ts export interface CoreApiCompanyRegistryResponse { name: string; ssn: string; address: string; postalCode: string; city: string; industryCodeIs: string; leagalIdentityType: string; municipalityCode: string; vat: number; } export type CompanyRegistryLookupResponse = | { status: "ok"; data: CoreApiCompanyRegistryResponse; } | { status: "not_found"; }; ``` ## `getHasCertificate()` Checks whether or not a user has a valid eID certificate. ```ts getHasCertificate(flowKey, ssn, phoneNumber, [options]): Promise; ``` - `flowKey (string)` - `ssn (string)` - 10 digit kennitala - `phoneNumber (string)` - `options ({ apiUrl?: string })` Returns a `HasCertificateResponse`. ```ts export type HasCertificateResponse = | { status: "has_certificate"; name: string; // Name of the person in the national registry } | { status: "no_certificate"; }; ``` # Types The types that are used by this package are accessible as named exports: ``` AuthResponse GetFlowByTypeResponse GetFlowResponse GetSignedDocumentResponse NationalRegistryLookupResponse StartSignDocumentResponse HasCertificateResponse ``` The Core API types that this package makes use of are also accessible as named exports. ``` CoreApiFillAndSignFlow CoreApiSignedDocument CoreApiNationalRegistryNameResponse CoreApiNameAuthResponse CoreApiSigningProcessAttachment CoreApiNameAddressAuthResponse CoreApiGetSignedDocumentResponse CoreApiErrorResponseData CoreApiCustomer CoreApiCreateSigningProcessBody CoreApiDropAndSignFlow CoreApiFlow CoreApiFlowProductType CoreApiHasCertificateResponse CoreApiNationalRegistryNameAddressResponse CoreApiRenderFlow CoreApiSignee CoreApiSigningProcess CoreApiStartSignProcessDocumentResponse CoreApiSigneeSignatureType CoreApiAccessToken CoreApiLanguage CoreApiCommunicationDeliveryType CoreApiNullableLanguage CoreApiCreateSigningProcessCreateSignee ``` --- _Source: https://npm.io/package/@taktikal/core-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._