API-reference · v1

Sløring som et API-kald

Upload et dokument, læs hvad Northdocs fandt, beslut, anvend og hent den slørede fil. Ren JSON over HTTPS, bearer-nøgler, hostet i EU.

Kom i gang Reference

Basis-URL: https://northdocs.com/api/v1
Godkendelse: Bearer API-nøgle
Grænse: 120 kald/min pr. nøgle
Hosting: Kun EU

Introduktion

Northdocs API er et REST API med forudsigelige URL'er, JSON-kroppe og almindelige HTTP-statuskoder. Alle stier i denne reference er relative til basis-URL'en.

Dokumenter gemmes og behandles i EU, præcis som når de uploades i appen. Hvert kald kører med rollen hos det medlem, der oprettede nøglen, så en reviewer-nøgle kan beslutte fund, men ikke uploade eller anvende.

Basis-URL

https://northdocs.com/api/v1

Godkendelse

Godkend med en API-nøgle i Authorization-headeren. Administratorer og security-rollen opretter nøgler under Indstillinger, API-nøgler. En nøgle vises én gang: gem den i jeres hemmelighedsboks med det samme.

Authorization: Bearer bd_live_3f9c...e21a

Nøgler starter med bd_live_. Læg aldrig en nøgle i en browser eller mobilapp.

En nøgle holder op med at virke, når den tilbagekaldes, eller når medlemmet, der oprettede den, forlader organisationen. Kald svarer så 401 eller 403.

Kald

curl "https://northdocs.com/api/v1/documents" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY"

Scopes

Hver nøgle har scopes. Et kald uden det scope, det kræver, svarer 403. Giv hver integration det mindste sæt, den har brug for.

documents:readListe dokumenter og læse status, fund, tekst og downloads. Læser også sager og jobs.
documents:writeUploade dokumenter, beslutte eller omklassificere fund og anvende. Opretter også sager.
cases:readListe og læse sager.
cases:writeOprette sager.
jobs:readListe seneste behandlingsjobs.
outbound_guardTekstsløring og de Outbound Guard-endpoints, som Outlook-tilføjelsesprogrammet bruger.

Kom i gang

Fire kald fører en PDF fra upload til sløret download. Scriptet til højre er hele forløbet i bash med curl og jq.

1
Upload filen. Northdocs udtrækker tekst, kører OCR hvor det er nødvendigt og finder personoplysninger.
2
Spørg på status, indtil den er ready_for_review, eller send resultUrl med uploadet og vent på kaldet tilbage.
3
Anvend. acceptAll accepterer først alle ventende fund; beslut enkelte fund før dette kald for at beholde nogle.
4
Hent den slørede PDF, når status er completed.

bash

# 1. Upload
DOC=$(curl -s -X POST "https://northdocs.com/api/v1/documents" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY" \
  -F "file=@contract.pdf" | jq -r .id)

# 2. Wait for review
until [ "$(curl -s "https://northdocs.com/api/v1/documents/$DOC" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY" | jq -r .status)" = "ready_for_review" ]; do
  sleep 3
done

# 3. Accept every finding and redact
curl -s -X POST "https://northdocs.com/api/v1/documents/$DOC/apply" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"redact","acceptAll":true}'

# 4. Download when completed
curl -s "https://northdocs.com/api/v1/documents/$DOC/download" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY" -o contract-redacted.pdf

Dokumentets forløb

Et dokument går gennem disse statusser. Spørg på GET /documents/{id}, eller abonnér på webhooken document.completed.

uploadedextractingdetectingready_for_reviewapplyingcompleted

uploaded: Gemt og venter på en worker.
extracting: Læser tekst og kører OCR på scannede sider.
detecting: Finder personoplysninger.
ready_for_review: Fundene er klar til at blive læst og besluttet.
applying: Brænder sløringen ind i filen og verificerer resultatet.
completed: Det slørede resultat kan hentes.
failed: Behandlingen stoppede. Feltet error siger hvorfor.

Dokumenter

POST/documents

Upload et dokument

Uploader en fil og starter behandlingen. Send multipart/form-data med filen i feltet file. PDF, Office-dokumenter, billeder, e-mail og ren tekst understøttes.

Scopedocuments:write

Parametre

filefileformularpåkrævet
Filen, der skal behandles.
caseIdstringformular
Sagens id.
resultUrlurlformular
Offentlig HTTPS-URL, der modtager en signeret POST, når dokumentet er færdigt.
redirectUrlurlformular
Hvor gennemsynet i appen sender brugeren hen bagefter. Skal ligge på appens domæne.

Kald

curl -X POST "https://northdocs.com/api/v1/documents" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY" \
  -F "file=@contract.pdf" \
  -F "caseId=case_7Hq2"

Svar

201 Created

{
  "id": "doc_9fK3a",
  "status": "uploaded"
}

GET/documents

Liste dokumenter

Dokumenter, som nøglens ejer kan åbne, nyeste først. Filtrér på sag med caseId.

Scopedocuments:read

Parametre

caseIdstringquery
Kun dokumenter i denne sag.

Kald

curl "https://northdocs.com/api/v1/documents?caseId=case_7Hq2" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY"

Svar

200 OK

[
  {
    "id": "doc_9fK3a",
    "name": "contract.pdf",
    "status": "ready_for_review",
    "pageCount": 12,
    "caseId": "case_7Hq2"
  }
]

GET/documents/{id}

Hent et dokument

Status, sideantal, sag og fundet sprog for ét dokument. Spørg her, mens et dokument behandles.

Scopedocuments:read

Parametre

idstringstipåkrævet
Dokumentets id.

Kald

curl "https://northdocs.com/api/v1/documents/doc_9fK3a" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY"

Svar

200 OK

{
  "id": "doc_9fK3a",
  "name": "contract.pdf",
  "status": "ready_for_review",
  "pageCount": 12,
  "caseId": "case_7Hq2",
  "language": "da"
}

POST/documents/{id}/apply

Anvend sløring

Brænder accepterede fund ind i filen eller erstatter dem med konsekvente pseudonymer. Svarer 202 med det samme; status går til applying og derefter completed.

Scopedocuments:write

Parametre

idstringstipåkrævet
Dokumentets id.
mode"redact" | "pseudonymize"krop
redact (standard) sværter værdier; pseudonymize erstatter dem konsekvent.
acceptAllbooleankrop
Acceptér alle ventende fund, før der anvendes.

Kald

curl -X POST "https://northdocs.com/api/v1/documents/doc_9fK3a/apply" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"redact","acceptAll":true}'

Svar

202 Accepted

{
  "status": "applying"
}

GET/documents/{id}/download

Hent resultatet

Returnerer den slørede PDF. Med format=text returneres den slørede tekst pr. side som JSON i stedet. Svarer 409, indtil sløringen er anvendt.

Scopedocuments:read

Parametre

idstringstipåkrævet
Dokumentets id.
format"text"query
Returnér sløret tekst som JSON i stedet for PDF'en.

Kald

curl "https://northdocs.com/api/v1/documents/doc_9fK3a/download?format=text" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY"

Svar

200 OK

{
  "id": "doc_9fK3a",
  "pages": [{ "pageNumber": 1, "text": "Lejer: [REDACTED], Nørregade 12" }],
  "fullText": "Lejer: [REDACTED], Nørregade 12"
}

GET/documents/{id}/text

Læs udtrukket tekst

Rå tekst pr. side før sløring, til søgning og indeksering. Ikke en eksport, og afvist hvor organisationen begrænser adgang til uslørede dokumenter.

Scopedocuments:read

Parametre

idstringstipåkrævet
Dokumentets id.

Kald

curl "https://northdocs.com/api/v1/documents/doc_9fK3a/text" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY"

Svar

200 OK

{
  "pages": [
    { "pageNumber": 1, "text": "Lejer: Jens Hansen, Nørregade 12", "ocr": false }
  ]
}

Fund

GET/documents/{id}/detections

Liste fund

Alt hvad Northdocs fandt, med kategori, side, tekst og beslutning. Status possible er et usikkert forslag, der aldrig sløres, før det sættes til accepted. Værdier maskeres for roller, der ikke må se dem.

Scopedocuments:read

Parametre

idstringstipåkrævet
Dokumentets id.

Kald

curl "https://northdocs.com/api/v1/documents/doc_9fK3a/detections" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY"

Svar

200 OK

[
  {
    "id": "det_41xZ",
    "category": "person",
    "text": "Jens Hansen",
    "pageNumber": 1,
    "status": "pending",
    "entityGroupId": "ent_02",
    "pseudonym": null
  }
]

PATCH/documents/{id}/detections/{detectionId}

Opdatér et fund

Acceptér, spring over eller nulstil ét fund, eller flyt det til en anden kategori. Reviewer-nøgler må beslutte, men ikke omklassificere.

Scopedocuments:write

Parametre

idstringstipåkrævet
Dokumentets id.
detectionIdstringstipåkrævet
Fundets id fra Liste fund.
status"pending" | "accepted" | "skipped"krop
Beslutningen for dette fund.
categorystringkrop
Flyt fundet til en anden kategorinøgle.

Kald

curl -X PATCH "https://northdocs.com/api/v1/documents/doc_9fK3a/detections/det_41xZ" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"skipped"}'

Svar

200 OK

{
  "ok": true
}

Sager og jobs

POST/cases

Opret en sag

Opretter en sag, der samler dokumenter. Send dens id som caseId ved upload.

Scopecases:write

Parametre

namestringkroppåkrævet
Sagens navn, som vises i appen.
referencestringkrop
Jeres egen reference, for eksempel et journalnummer.
defaultMode"redact" | "pseudonymize"krop
Standardtilstand ved anvendelse for dokumenter i sagen.

Kald

curl -X POST "https://northdocs.com/api/v1/cases" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Aktindsigt 2026-114","reference":"J.nr. 2026-114"}'

Svar

201 Created

{
  "id": "case_7Hq2"
}

GET/cases

Liste sager

Sager, som nøglens ejer kan åbne.

Scopecases:read

Parametre

Ingen parametre.

Kald

curl "https://northdocs.com/api/v1/cases" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY"

Svar

200 OK

[
  {
    "id": "case_7Hq2",
    "name": "Aktindsigt 2026-114",
    "status": "open",
    "reference": "J.nr. 2026-114"
  }
]

GET/cases/{id}

Hent en sag

Én sag med status og reference.

Scopecases:read

Parametre

idstringstipåkrævet
Sagens id.

Kald

curl "https://northdocs.com/api/v1/cases/case_7Hq2" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY"

Svar

200 OK

{
  "id": "case_7Hq2",
  "name": "Aktindsigt 2026-114",
  "status": "open",
  "reference": "J.nr. 2026-114"
}

GET/jobs

Liste jobs

Seneste behandlingsjobs med type, status og fremdrift.

Scopejobs:read

Parametre

Ingen parametre.

Kald

curl "https://northdocs.com/api/v1/jobs" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY"

Svar

200 OK

[
  {
    "id": "job_k21P",
    "kind": "process",
    "status": "completed",
    "documentId": "doc_9fK3a",
    "progress": 100
  }
]

Tekst

POST/sanitize

Slør tekst

Finder og slører eller erstatter personoplysninger i ren tekst. Intet gemmes.

Scopeoutbound_guard

Parametre

textstringkroppåkrævet
Teksten, der skal sløres.
mode"redact" | "replace"krop
redact (standard) sværter værdier; replace indsætter en pladsholder.

Kald

curl -X POST "https://northdocs.com/api/v1/sanitize" \
  -H "Authorization: Bearer $NORTHDOCS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Ring til Jens Hansen på 20 30 40 50","mode":"redact"}'

Svar

200 OK

{
  "cleanText": "Ring til ███████████ på ███████████",
  "findings": [
    {
      "category": "person",
      "label": "Person name",
      "text": "Jens Hansen",
      "start": 9,
      "end": 20,
      "replacement": "███████████",
      "source": "regex"
    },
    {
      "category": "phone",
      "label": "Phone number",
      "text": "20 30 40 50",
      "start": 24,
      "end": 35,
      "replacement": "███████████",
      "source": "regex"
    }
  ],
  "byCategory": { "person": 1, "phone": 1 },
  "mode": "redact"
}

Hændelser og fejl

Webhooks

Tilføj et endpoint under Indstillinger, Webhooks. Northdocs sender en signeret POST med en JSON-krop til jeres offentlige HTTPS-URL, når en abonneret hændelse sker.

document.completedEt dokument er færdigt med at blive anvendt, og resultatet kan hentes.
outbound_guard.alertOutbound Guard stoppede eller advarede om en udgående mail.

Verificér hver levering. x-northdocs-signature er hex-HMAC SHA-256 af den rå krop med den signeringshemmelighed, der blev vist, da I tilføjede endpointet.

HTTP

POST /northdocs-hook HTTP/1.1
Content-Type: application/json
x-northdocs-event: document.completed
x-northdocs-signature: 5f2c8a...e91a

{
  "event": "document.completed",
  "data": { "documentId": "doc_9fK3a", "mode": "redact" },
  "timestamp": 1793500000000
}

verify.ts

import { createHmac, timingSafeEqual } from "node:crypto";

export function isFromNorthdocs(rawBody: string, signature: string, secret: string) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signature, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

Fejl

Fejl bruger almindelige HTTP-statuskoder og en JSON-krop med en fejlbesked. Nogle har også en maskinlæsbar code.

400Et felt mangler eller er ugyldigt.
401API-nøglen mangler, er forkert eller tilbagekaldt.
402Abonnementet eller kvoten dækker ikke kaldet.
403Scope mangler, eller ejerens rolle må ikke gøre dette.
404Findes ikke, eller nøglens ejer kan ikke åbne det.
409Forkert tilstand, for eksempel stadig under behandling.
413Filen er for stor.
415Filtypen understøttes ikke.
429For mange kald. Vent og prøv igen.

Svar

403 Forbidden

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": "api key missing documents:write scope"
}

Grænser

Hver nøgle må lave 120 kald i minuttet. Derover svarer API'et 429; vent et par sekunder og prøv igen. At spørge på ét dokument med få sekunders mellemrum ligger et godt stykke under grænsen.

Uploads tæller med i organisationens månedlige sidekvote, præcis som uploads i appen.

OpenAPI-specifikation

Hele API'et er beskrevet i et OpenAPI 3.1-dokument. Importér det i Postman eller Insomnia, eller generér en typet klient.

Åbn openapi.json

Mangler I et endpoint? Skriv til os fra Kontakt support i appen.

https://northdocs.com/api/v1

URL

https://northdocs.com/api/v1/openapi.json