Partner API

Hämtar status för ett ärende, inklusive varje mottagares delstatus.

Sök på MySigns ID (returnerat vid skapandet), eller på er egen externalReference via query-parametern — praktiskt om ni bara sparar er egen referens. Referensen behöver inte vara unik: delar flera dokument samma referens returneras det senast skapade av dem, bland nyckelns företags dokument i nyckelns läge (live eller test).

curl "https://mysign.se/api/partner/v1/documents/lookup?externalReference=member-4711" \
  -H "Authorization: Bearer msk_live_xxxxxxxxxxxxxxxxxxxx"

(externalReference tar alltid företräde över {id} i sökvägen när den är angiven — vilket värde som helst, t.ex. lookup, fungerar då som platshållare.)

Svar — 200 OK

{
  "success": true,
  "livemode": true,
  "document": {
    "id": "1HBR5TuZb",
    "documentName": "Medlemsavtal 2026",
    "externalReference": "member-4711",
    "redirectUrl": "https://app.example.se/avtal/tack",
    "status": "COMPLETED",
    "revisionInProgress": false,
    "version": 1,
    "sentAt": "2026-09-15T12:50:39.584Z",
    "finalizedAt": "2026-09-15T13:11:33.580Z",
    "cancelledAt": null,
    "expiredAt": null,
    "createdAt": "2026-09-15T12:50:39.587Z",
    "recipients": [
      {
        "id": "y8gsm5YFt",
        "name": "Anna Andersson",
        "email": "anna@example.se",
        "role": "signer",
        "status": "SIGNED",
        "signedAt": "2026-09-15T13:11:25.390Z",
        "approvedAt": null,
        "changeRequestedAt": null,
        "invitationOrder": 1
      }
    ]
  }
}

En mottagares status är PENDING, OPENED, REVIEWED (har läst hela), SIGNED, APPROVED, CHANGES_REQUESTED eller DECLINED. En mottagare är klar när en signer är SIGNED, en approver är APPROVED och en reviewer är REVIEWED (eller SIGNED). revisionInProgress och version beskrivs under nya versioner.

status är ett av: DRAFT, PENDING, COMPLETED, DECLINED, EXPIRED, CANCELLED. Varje mottagares status: PENDING, OPENED, REVIEWED, SIGNED, APPROVED, CHANGES_REQUESTED, DECLINED. CHANGES_REQUESTED gäller bara en godkännare; en undertecknare eller läsare som begär ändring behåller sin status här. livemode är true för en live-nyckel och false för en testnyckel.

Strömmar den signerade PDF:en (application/pdf) när ärendet är COMPLETED.

curl https://mysign.se/api/partner/v1/documents/1HBR5TuZb/pdf \
  -H "Authorization: Bearer msk_live_xxxxxxxxxxxxxxxxxxxx" \
  -o medlemsavtal-signerat.pdf

Anropas innan dokumentet är klart svarar det 409 Conflict med koden NOT_COMPLETED — vänta på document.completed-webhooken eller polla statusendpointen istället för att gissa på en timing. Svaret innehåller dokumentets aktuella status i fältet status.

Kontrollerar att nyckeln fungerar och svarar med företaget den tillhör (company.name, company.organizationNumber) och med livemode — true för en live-nyckel, false för en testnyckel. Använd den som anslutningstest.

Prenumererar en URL på händelser, utöver företagets egen webhook-URL. Skicka JSON med url (https, max 2 000 tecken) och valfritt events — en lista med högst 20 händelsenamn; utelämnad eller tom betyder alla. En body som inte klarar detta avvisas med 400 INVALID_INPUT, och error säger vad som är fel. Svaret innehåller prenumerationens id och en secret som visas endast här och signerar varje leverans på samma sätt som under Verifiera signatur.

curl -X POST https://mysign.se/api/partner/v1/webhooks \
  -H "Authorization: Bearer msk_live_<nyckel>" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/hooks/mysign","events":["document.completed"]}'

Avsluta med DELETE /api/partner/v1/webhooks/{id}. En mottagare som svarar 410 Gone på en leverans avprenumereras automatiskt.

Returnerar företagets senaste händelser av en typ, nyast först, i samma form som en webhook-leverans — avsett som exempeldata när ni bygger ett flöde. Svaret är { "success": true, "events": [...] } med högst tre händelser, en per dokument (och mottagare för mottagarhändelser). Varje händelse har dessutom ett id, <documentId>:<recipientId>:<type> (tomt recipientId för dokumenthändelser). Finns ingen sådan händelse ännu returneras en exempelhändelse, som saknar livemode. Endast händelser i nyckelns läge (live eller test) visas. Saknas type eller är den okänd svarar API:et 400 UNKNOWN_EVENT.

Personnummer & BankID

Personnummer valideras mot svenskt format (ÅÅÅÅMMDD-NNNN eller ÅÅMMDD-NNNN, bindestreck valfritt) med Luhn-kontrollsiffra. Ett värde som skickas med men inte klarar valideringen avvisas med 400 INVALID_PERSONAL_ID.

idNumber kan lämnas tomt även när methods innehåller EID — MySign fångar då upp personnumret direkt från BankID-legitimeringen vid signeringstillfället. Om ni redan känner till mottagarens personnummer, skicka det ändå: det verifieras mot BankID-svaret vid signering, så en signering av fel person avvisas.

Undantaget är requireBankIdToView=true — då krävs personnumret redan vid skapandet (400 MISSING_PERSONAL_ID annars), eftersom identitetskontrollen sker innan dokumentet ens visas.

Händelser

Tretton händelsetyper i två grupper — dokumentnivå (hela ärendet) och mottagarnivå (en enskild mottagares framsteg, oberoende av om övriga mottagare är klara).

Dokumentnivå

Mottagarnivå — en per mottagare

Exempel — document.completed

{
  "event": "document.completed",
  "documentId": "1HBR5TuZb",
  "externalReference": "member-4711",
  "status": "COMPLETED",
  "signedPdfUrl": "https://mysign.se/api/partner/v1/documents/1HBR5TuZb/pdf",
  "occurredAt": "2026-09-15T13:11:33.580Z",
  "timestamp": "2026-09-15T13:11:33.581Z",
  "documentName": "Medlemsavtal 2026",
  "livemode": true
}

signedPdfUrl pekar på partner-API:et (kräver samma Authorization-header som alla andra anrop) — aldrig en bar lagringslänk. document.declined/.expired/.cancelled har samma form men saknar signedPdfUrl.

Exempel — recipient.signed

{
  "event": "recipient.signed",
  "documentId": "1HBR5TuZb",
  "recipientId": "y8gsm5YFt",
  "recipientName": "Anna Andersson",
  "recipientEmail": "anna@example.se",
  "externalReference": "member-4711",
  "status": "SIGNED",
  "occurredAt": "2026-09-15T13:11:25.390Z",
  "timestamp": "2026-09-15T13:11:25.390Z",
  "documentName": "Medlemsavtal 2026",
  "livemode": true
}

Nya versioner av ett skickat dokument

Avsändaren kan ändra ett dokument som redan är skickat genom att göra en ny version. Dokumentet behåller sitt documentId och sin externalReference, och dess status är PENDING hela vägen. Fältet version börjar på 1 och ökar med varje publicerad version, och revisionInProgress är true medan signeringen är pausad. Båda finns i händelserna nedan och i svaret från statusanropet.

Exempel — document.version_published

{
  "event": "document.version_published",
  "documentId": "1HBR5TuZb",
  "externalReference": "member-4711",
  "status": "PENDING",
  "revisionInProgress": false,
  "version": 2,
  "changeNote": "Betalningsvillkoren i punkt 4 är ändrade till 30 dagar",
  "changes": [
    "Dokumentets innehåll har ändrats",
    "Ny part: Bo Berg (godkännare)"
  ],
  "occurredAt": "2026-09-16T09:02:11.120Z",
  "timestamp": "2026-09-16T09:02:11.121Z",
  "documentName": "Medlemsavtal 2026",
  "livemode": true
}

changeNote är avsändarens egen notering (kan vara null) och changes en lista med vad som skiljer från versionen innan, en rad per ändring. document.revision_started och .revision_cancelled har samma form utan de två fälten.

obligatoriskmåste skickas med·villkoradkrävs bara i vissa fall·valfrikan utelämnas

Leverans & omförsök

Varje händelse levereras med POST, Content-Type: application/json, 5 sekunders timeout. Ett icke-2xx-svar (eller timeout) schemalägger ett omförsök med exponentiell backoff:

Omförsöken plockas upp av ett jobb som körs var femte minut, så fördröjningarna ovan är minimivärden — ett omförsök kan komma upp till fem minuter senare.

Efter sex försök ges leveransen upp permanent. Svara 2xx så fort ni har verifierat signaturen och sparat/köat händelsen — gör den faktiska bearbetningen asynkront istället för att låta MySigns 5-sekunders timeout styra hur lång tid er handler får ta.

En mottagarhändelse skickas som mest en gång per mottagare, händelsetyp och dokumentversion — recipient.changes_requested en gång per ändringsbegäran. document.version_published skickas en gång per version, document.revision_started och .revision_cancelled en gång per tillfälle (de kan alltså komma flera gånger för samma dokument), och övriga dokumenthändelser en gång per dokument.

Bygg ändå mottagaren idempotent, som skydd mot dubbletter om nätverket lurar er. En nyckel som fungerar för alla händelser är documentId + recipientId (tom för dokumenthändelser) + event + occurredAt. Ett omförsök skickar exakt samma body som första försöket.

Registrera domäner

MySign skickar bara vidare till domäner som ert företag har registrerat i förväg. En ägare eller administratör lägger till dem under Inställningar > Integrationer > API & webhook. Att registrera example.se tillåter även underdomäner som app.example.se, men inte evilexample.se. Delade värdsuffix som github.io och vercel.app, och andranivåregister som co.uk, går inte att registrera som de är — registrera ert eget namn under dem (t.ex. example.co.uk).

Har företaget ingen webhook-hemlighet när en ägare eller administratör registrerar en domän skapar MySign en och visar den en gång, direkt där. Den används för att signera omdirigeringen, se Parametrar & signatur.

Adressen måste börja med https://, sakna användarnamn, port och fragment, och peka på ett domännamn (inte en IP-adress). Era egna query-parametrar får vara kvar, utom sådana som börjar med mysign_. Ett ärende med en adress som inte godkänns skapas inte — se felkoder redirect_* under Felkoder.

Parametrar & signatur

MySign lägger till följande parametrar på er adress. Inget om personen läggs till: inga namn, e-postadresser, telefonnummer, personnummer eller länkar.

obligatoriskmåste skickas med·villkoradkrävs bara i vissa fall·valfrikan utelämnas

https://app.example.se/avtal/tack?kampanj=var
  &mysign_document=1HBR5TuZb
  &mysign_reference=member-4711
  &mysign_status=signed
  &mysign_ts=1760446800
  &mysign_mode=live
  &mysign_sig=<64 hex-tecken>

Det som signeras är exakt sex rader, sammanfogade med radbrytning (\n), i den här ordningen. Raden för referensen är tom om dokumentet saknar en:

mysign-redirect-v1
<mysign_document>
<mysign_reference, tom rad om den saknas>
<mysign_status>
<mysign_ts>
<mysign_mode>

Använd värdena som de står i adressen (avkodade). Kontrollera signaturen på er server innan ni litar på parametrarna, och avvisa gamla tidsstämplar:

const crypto = require("crypto");

// query = parametrarna från adressen, redan avkodade
function verifyMySignRedirect(query, secret) {
  const sig = query.mysign_sig;
  if (!sig) return false; // utan signatur: lita inte på parametrarna

  const canonical = [
    "mysign-redirect-v1",
    query.mysign_document,
    query.mysign_reference ?? "",
    query.mysign_status,
    query.mysign_ts,
    query.mysign_mode,
  ].join("\n");

  const expected = crypto
    .createHmac("sha256", secret)
    .update(canonical, "utf8")
    .digest("hex");

  // Ett testdokument ska aldrig godtas i produktion.
  if (query.mysign_mode !== "live") return false;

  const fresh = Math.abs(Date.now() / 1000 - Number(query.mysign_ts)) < 600;
  const a = Buffer.from(sig);
  const b = Buffer.from(expected);
  return fresh && a.length === b.length && crypto.timingSafeEqual(a, b);
}

För en mottagare i ett testdokument till ett utfall, som om parten hade gjort det på signeringssidan. JSON-body.

obligatoriskmåste skickas med·villkoradkrävs bara i vissa fall·valfrikan utelämnas

curl -X POST https://mysign.se/api/partner/v1/documents/1HBR5TuZb/simulate \
  -H "Authorization: Bearer msk_test_<nyckel>" \
  -H "Content-Type: application/json" \
  -d '{"recipientId":"cmg2x1k7a0001","outcome":"signed","method":"EID"}'

Svaret är detsamma som från statusendpointen (200), med det nya läget. Samma webhooks skickas som vid en riktig signering, med livemode: false. Ett anrop för ett utfall som mottagaren redan har ger samma svar och skickar inget igen.

Endast testnycklar: en live-nyckel får 403 test_mode_only. Ett utfall som inte hör till mottagarens roll ger 403 OUTCOME_ROLE_MISMATCH. Samma regler som på signeringssidan gäller i övrigt — signeringsordning, deadline, tillåtna metoder och att ärendet är PENDING — och bryter anropet mot en av dem svarar API:et med regelns kod, t.ex. 403 INVITATION_ORDER_LOCKED eller 403 SIGNATURE_METHOD_NOT_ALLOWED. Anropet räknas som ett skrivanrop i Gränser.