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:

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,
  "document": {
    "id": "1HBR5TuZb",
    "documentName": "Medlemsavtal 2026",
    "externalReference": "member-4711",
    "status": "COMPLETED",
    "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",
        "invitationOrder": 1
      }
    ]
  }
}

status är ett av: DRAFT, PENDING, COMPLETED, DECLINED, EXPIRED, CANCELLED. Varje mottagares status: PENDING, OPENED, REVIEWED, SIGNED, DECLINED.

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.

Kontrollerar att nyckeln fungerar och svarar med företaget den tillhör (company.name, company.organizationNumber). Använd den som anslutningstest.

Prenumererar en URL på händelser, utöver företagets egen webhook-URL. Skicka JSON med url (https) och valfritt events — en lista med händelsenamn; utelämnad betyder alla. 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, i exakt samma form som en webhook-leverans — avsett som exempeldata när ni bygger ett flöde. Finns ingen sådan händelse ännu returneras en exempelhändelse.

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

Åtta 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"
}

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"
}

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.

Varje (dokument, mottagare, händelsetyp)-kombination levereras som mest en gång per faktisk statusändring — men bygg mottagaren idempotent ändå (nyckla på documentId + recipientId + event) som skydd mot dubbletter om nätverket lurar er.