Introduktion

Avidentifiera API tar emot text, PDF eller DOCX (Word) och returnerar en avidentifierad version baserat på regelstyrd behandling av personuppgifter som namn, adress, personnummer, telefonnummer och e-postadress.

API:et har två huvudsakliga endpoints:

• /v1/redact/file – tar emot en PDF eller DOCX (Word) och returnerar direkt en avidentifierad PDF/DOCX eller ett JSON-objekt som innehåller den avidentifierade filen som Base64. Svarsformatet beror på hur du skickade in filen.
• /v1/redact/text – tar rå text och returnerar avidentifierad text som JSON.

Bas-URL för alla anrop:

https://api.avidentifiera.se

Direkt in, direkt ut – inga känsliga dokument lagras

Många liknande tjänster arbetar asynkront: du laddar upp ett dokument, får tillbaka ett jobb-ID och behöver anropa en andra endpoint för att hämta resultatet när bearbetningen är klar. Den modellen innebär nästan alltid att din ursprungliga fil mellanlagras på leverantörens servrar.

Vi har valt en annan modell av två skäl: datasäkerhet och enkelhet.

• Ingen lagring av din fil. Dokumentet skickas i din begäran, bearbetas i minnet och det avidentifierade resultatet skickas tillbaka i samma HTTP-svar. Vi behåller inte filen hos oss som del av ett köat jobb.
• Ingen polling, inget jobb-ID. Du behöver inte bygga logik för att vänta, fråga om status, ladda ner senare, hantera tidsfönster eller städa bort resultatfiler.
• Mindre informationsspridning. Eftersom vi inte skriver upp dina dokument i bestående lagring minskar risken för att sekretessbelagt material ligger kvar på en server efteråt.

För verksamheter som hanterar patientuppgifter, personalakter eller andra sekretessreglerade handlingar betyder detta: du skickar ett dokument och får tillbaka en avidentifierad version direkt – utan att vi behöver spara ditt original.

Autentisering

Varje anrop måste innehålla en giltig API-nyckel i headern Authorization: Bearer <din-nyckel>. Om nyckeln saknas eller är ogiltig returneras 401 Unauthorized.

Du kan skapa och hantera din API-nyckel under api-nycklar i portalen. Hantera nyckeln som ett lösenord och exponera den inte i publik klientkod.

Exempel (cURL)

curl -X POST "https://api.avidentifiera.se/v1/redact/text" \
  -H "Authorization: Bearer live_xxx..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-binary @- << 'JSON'
{
  "text": "Mitt namn är Anna Andersson och mitt personnummer är 850612-1234.",
  "options": {
    "entities": ["name","personalNumber"],
    "rules": {
      "name": { "method": "replaceWithInitials" },
      "personalNumber": { "method": "remove" }
    }
  }
}
JSON

Avidentifiera fil

POST /v1/redact/file

Endpointen tar emot ett dokument (PDF eller DOCX/Word), avidentifierar innehållet och returnerar resultatet i samma svar. Resultatets format bestäms av hur du skickade in filen.

Följande varianter stöds:

• multipart/form-data
  Du laddar upp dokumentet som ett formulärfält (PDF eller DOCX). Svaret är en binär avidentifierad PDF/DOCX och metadata skickas i headern Redaction-Result. Du kan skicka egna options.
• application/json
  Du skickar filen Base64-kodad i fältet fileBase64 (PDF eller DOCX). Svaret är application/json och innehåller bland annat den avidentifierade filen som Base64, samt metadata. Du kan skicka egna options.
• application/pdf eller application/vnd.openxmlformats-officedocument.wordprocessingml.document
  Du skickar filens bytes som request body. Svaret är en binär avidentifierad fil (PDF respektive DOCX) och metadata skickas i headern Redaction-Result. I detta läge kan du inte ange options; standardprofilen används (namn, adress och personnummer maskeras).

Sammanfattande metadata beskriver vilka entiteter som hittades och hur de hanterades. Informationen skickas antingen i headern Redaction-Result (binärt filsvar), eller i JSON-svaret (vid application/json).

Vid fel returneras Problem Details enligt RFC 7807 (se Felhantering).

Headers

Tre varianter

1. Multipart (multipart/form-data)
2. JSON med Base64 (application/json)
3. Rå fil i request body (application/pdf eller application/vnd.openxmlformats-officedocument.wordprocessingml.document)

Metod 1: Multipart-uppladdning (multipart/form-data)

# 1. Förbered options
cat > options.json << 'JSON'
{
  "entities": ["name","address","personalNumber"],
  "rules": {
    "name": {
      "method": "replaceWithInitials",
      "minNameParts": 2,
      "redactPersonNamedCompanies": true
    },
    "address": {
      "method": "mask",
      "mode": "fullAddress"
    },
    "personalNumber": {
      "method": "remove"
    }
  }
}
JSON

# 2a. Skicka PDF som multipart/form-data
curl -X POST "https://api.avidentifiera.se/v1/redact/file" \
  -H "Authorization: Bearer live_xxx..." \
  -H "Idempotency-Key: 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" \
  -H "Accept: application/pdf" \
  -F "file=@/path/to/dokument.pdf;type=application/pdf" \
  -F "options=@options.json;type=application/json" \
  --output redacted-dokument.pdf

# 2b. Skicka DOCX (Word) som multipart/form-data
curl -X POST "https://api.avidentifiera.se/v1/redact/file" \
  -H "Authorization: Bearer live_xxx..." \
  -H "Idempotency-Key: 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" \
  -H "Accept: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  -F "file=@/path/to/dokument.docx;type=application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  -F "options=@options.json;type=application/json" \
  --output redacted-dokument.docx

Svar (200 OK): binär PDF eller DOCX. Servern bifogar metadata i headern Redaction-Result.

Metod 2: JSON med Base64 (application/json)

curl -X POST "https://api.avidentifiera.se/v1/redact/file" \
  -H "Authorization: Bearer live_xxx..." \
  -H "Idempotency-Key: 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  --data-binary @- << 'JSON'
{
  "fileBase64": "UEsDBBQACAAI... (base64 för DOCX eller PDF)",
  "options": {
    "entities": ["name","phoneNumber"],
    "rules": {
      "name": {
        "method": "replaceWithInitials",
        "minNameParts": 2,
        "redactPersonNamedCompanies": true
      },
      "phoneNumber": {
        "method": "replaceWith",
        "replacementText": "TELEFON"
      }
    }
  }
}
JSON

Svar (200 OK): application/json.

{
  "took": 42,
  "result": {
    "redactedFileBase64": "UEsDBBQACAAI... (base64 för avidentifierad PDF/DOCX)",
    "entities": {
      "name": [
        "Anna Andersson",
        "Erik Sandström"
      ],
      "address": [
        "Storgatan 12, 123 45 Stockholm"
      ],
      "personalNumber": [
        "850612-1234"
      ],
      "phoneNumber": [
        "070-1234567"
      ],
      "email": [
        "anna.andersson@example.se"
      ]
    }
  }
}

Metod 3: Rå fil i request-kroppen (application/pdf eller application/vnd.openxmlformats-officedocument.wordprocessingml.document)

Request body är filens bytes och Content-Type sätts till antingen PDF eller DOCX. Här kan du inte skicka options. Servern använder då standardprofilen: namn, adress och personnummer maskeras.

# PDF
curl -X POST "https://api.avidentifiera.se/v1/redact/file" \
  -H "Authorization: Bearer live_xxx..." \
  -H "Idempotency-Key: 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" \
  -H "Content-Type: application/pdf" \
  --data-binary @/path/to/dokument.pdf \
  --output redacted-dokument.pdf

# DOCX (Word)
curl -X POST "https://api.avidentifiera.se/v1/redact/file" \
  -H "Authorization: Bearer live_xxx..." \
  -H "Idempotency-Key: 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" \
  -H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  --data-binary @/path/to/dokument.docx \
  --output redacted-dokument.docx

Svar (200 OK): binär PDF eller DOCX. Servern bifogar metadata i headern Redaction-Result.

Exempel på svarshuvuden (gäller svar som är binär fil, dvs. multipart/form-data och rå bytes):

HTTP/1.1 200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="dokument-redacted.pdf"
Redaction-Result: {
  "took":42,
  "entities":{
    "name":["Anna Andersson","Erik Sandström"],
    "address":["Storgatan 12, 123 45 Stockholm"],
    "personalNumber":["850612-1234"]
  }
}

HTTP/1.1 200 OK
Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document
Content-Disposition: attachment; filename="dokument-redacted.docx"
Redaction-Result: {
  "took":42,
  "entities":{
    "name":["Anna Andersson","Erik Sandström"],
    "address":["Storgatan 12, 123 45 Stockholm"],
    "personalNumber":["850612-1234"]
  }
}

Fel

400 / 413 / 415 / 422 / 5xx
Content-Type: application/problem+json
Kroppen är Problem Details (se Felhantering).

Avidentifiera text

POST /v1/redact/text

Skicka text och få tillbaka en avidentifierad version som JSON. Lyckade svar returneras som application/json. Vid fel returneras Problem Details som application/problem+json.

Headers

Body (JSON)

Requestexempel (cURL)

curl -X POST "https://api.avidentifiera.se/v1/redact/text" \
  -H "Authorization: Bearer live_xxx..." \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Idempotency-Key: 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" \
  --data-binary @- << 'JSON'
{
  "text": "Namn: Erik Lars Martin Sandström, Personnummer: 850612-1234, Tel: 070-1234567, Adress: Storgatan 12, 123 45 Stockholm, E-post: erik@example.se.",
  "options": {
    "entities": ["name","personalNumber","phoneNumber","address","email"],
    "rules": {
      "name": {
        "method": "replaceWithInitials",
        "minNameParts": 2,
        "redactPersonNamedCompanies": true
      },
      "personalNumber": {
        "method": "remove"
      },
      "phoneNumber": {
        "method": "replaceWith",
        "replacementText": "TELEFON"
      },
      "address": {
        "method": "mask",
        "mode": "fullAddress",
        "maskingCharacter": "█"
      },
      "email": {
        "method": "replaceWith",
        "replacementText": "E-POST"
      }
    }
  }
}
JSON

Svarsexempel (200 OK)

Ett lyckat svar innehåller alltid svarstiden i millisekunder (took) och ett result-objekt. Den avidentifierade texten ligger i redactedText. Notera: method: "remove" tar bort värdet helt utan markör.

{
  "took": 42,
  "result": {
    "redactedText": "Namn: E.L.M.S. Personnummer: . Tel: TELEFON. Adress: █████████████████████████████████. E-post: E-POST.",
    "entities": {
      "name": [
        "Erik Lars Martin Sandström"
      ],
      "personalNumber": [
        "850612-1234"
      ],
      "phoneNumber": [
        "070-1234567"
      ],
      "address": [
        "Storgatan 12, 123 45 Stockholm"
      ],
      "email": [
        "erik@example.se"
      ]
    }
  }
}

Regelkonfiguration (options)

options är valfri. Om du hoppar över den används standardläget: namn, adress och personnummer maskeras. Telefonnummer och e-post lämnas som de är.

Strukturen i options består av två delar:

• entities – en lista över vilka typer av känslig information API:t ska leta efter och behandla. Exempel: ["name","address","personalNumber"]. Bara entiteter som finns med här kommer att avidentifieras.
• rules – ett objekt där varje nyckel motsvarar en entitet (t.ex. "name", "address" osv). För varje entitet anger du exakt hur den ska avidentifieras: maskas, tas bort, ersättas med statisk text, ersättas med initialer, etc.

entities svarar på frågan “vilken typ av data ska skyddas?”, medan rules svarar på “hur ska just den typen behandlas?”.

Övergripande struktur

{
  "entities": ["name","address","email","personalNumber","phoneNumber"],
  "rules": {
    "name": { ... },
    "address": { ... },
    "email": { ... },
    "personalNumber": { ... },
    "phoneNumber": { ... }
  }
}

Om du väljer method: "replaceWith" för en entitet måste du ange replacementText.

I dokumentresultat (PDF/DOCX) används textColor och fillColor för att täcka originalvärdet visuellt och ersätta det direkt i dokumentet. Färger kan skilja sig per entitet.

name (personnamn)

address

personalNumber (personnummer)

phoneNumber (telefonnummer)

email (e-postadress)

Idempotens (Idempotency-Key)

För att undvika dubbeldebitering och dubbla jobb vid retries kan du skicka headern Idempotency-Key: <unik-nyckel>. Headern är valfri men rekommenderad.

En idempotency-nyckel är ett unikt värde (oftast en slumpad UUID) som du väljer för ett specifikt anrop. Om du skickar identisk indata igen med samma Idempotency-Key inom giltighetstiden behandlas det som samma jobb, inte som ett nytt. Svaret (t.ex. avidentifierad PDF/DOCX eller avidentifierad text) återanvänds.

Om du inte skickar någon Idempotency-Key genererar servern en åt dig och returnerar den i svaret som header. Du kan logga den om du vill kunna göra säkra retries efteråt.

En idempotency-nyckel är giltig i 15 minuter. Inom det fönstret kommer samma nyckel + samma indata att räknas som samma operation. Efter 15 minuter behandlas anropet som nytt.

curl -X POST "https://api.avidentifiera.se/v1/redact/file" \
  -H "Authorization: Bearer live_xxx..." \
  -H "Idempotency-Key: 1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed" \
  -H "Content-Type: application/pdf" \
  --data-binary @/path/to/dokument.pdf \
  --output redacted-dokument.pdf

Rekommendation: använd en ny idempotency-nyckel per unikt dokument eller textinnehåll. Återanvänd inte samma nyckel för olika data.

Felhantering

API:t använder standardiserade HTTP-statuskoder. Vid fel returneras Problem Details med Content-Type: application/problem+json.

Exempel på fel (Problem Details)

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Ogiltig begäran. / Bad Request.",
  "status": 400,
  "errors": {
    "options.rules.name1": [
      "Ogiltigt entitetsnamn 'name1'. Menade du 'name'? / Invalid entity name 'name1'. Did you mean 'name'?"
    ],
    "options.rules.default.maskingCharacter": [
      "'maskingCharacter' får endast anges när 'method' är 'Mask'. / 'maskingCharacter' may only be set when 'method' is 'Mask'."
    ]
  },
  "traceId": "00-dbf294725c4da476d045a74f7d3ffe92-8b94063d7b09e5e6-00"
}