Placement Confirmation Flow¶

End-to-end worker journey from accepting an offer to a fully confirmed placement. The flow has four sequential phases: ID verification, first-phase document signing, personal data collection, and final placement-document signing.

sequenceDiagram
    participant Worker
    participant Cruits
    participant Sumsub
    participant DocuSign
    participant SF as Salesforce

    Note over Worker,Cruits: Phase 1 — ID Check
    Worker->>Cruits: Open placement confirmation
    Cruits->>Sumsub: Create access token (user_id)
    Sumsub-->>Cruits: Access token
    Cruits-->>Worker: Launch Sumsub WebSDK
    Worker->>Sumsub: Submit ID + liveness
    Sumsub-->>Cruits: Webhook — applicant reviewed
    Cruits->>Cruits: Mark ID check completed

    Note over Worker,Cruits: Phase 2 — Sign Phase 1 Documents
    Cruits->>DocuSign: Create draft envelope (phase=PHASE_ONE, status=created, no docs yet)
    DocuSign-->>Cruits: envelopeId
    Cruits->>SF: Generate screening PDFs (code of conduct, ABU, ...)
    Note over Cruits,SF: Background: documents generated and downloaded asynchronously
    SF-->>Cruits: Generated documents (async)
    loop For each document as it arrives
        Cruits->>DocuSign: Add document to draft envelope
    end
    Cruits->>DocuSign: Send envelope (all documents present)
    Cruits->>DocuSign: Create recipient view
    DocuSign-->>Cruits: Embedded signing URL
    Cruits-->>Worker: Redirect to signing URL
    Worker->>DocuSign: Sign documents
    DocuSign-->>Cruits: Connect webhook — envelope completed
    Cruits->>DocuSign: Download combined PDF
    Cruits->>Cruits: Store signed documents

    Note over Worker,Cruits: Phase 3 — Fill Personal Data
    Cruits-->>Worker: Open data form
    Worker->>Cruits: Submit IBAN, BSN, health insurance, wage tax
    Cruits->>Cruits: Persist on Contact / Placement
    Cruits->>SF: Sync personal data

    Note over Worker,Cruits: Phase 4 — Sign Phase 2 (Placement) Documents
    Cruits->>DocuSign: Create draft envelope (phase=PHASE_TWO, status=created, no docs yet)
    DocuSign-->>Cruits: envelopeId
    Cruits->>SF: Generate placement PDFs (Uitzendbevestiging, Arbeidscontract, ...)
    Note over Cruits,SF: Background: documents generated and downloaded asynchronously
    SF-->>Cruits: Generated documents (async)
    loop For each document as it arrives
        Cruits->>DocuSign: Add document to draft envelope
    end
    Cruits->>DocuSign: Send envelope (all documents present)
    Cruits->>DocuSign: Create recipient view
    DocuSign-->>Cruits: Embedded signing URL
    Cruits-->>Worker: Redirect to signing URL
    Worker->>DocuSign: Sign placement documents
    DocuSign-->>Cruits: Connect webhook — envelope completed
    Cruits->>DocuSign: Download combined PDF
    Cruits->>Cruits: Store signed documents
    Cruits->>Cruits: Mark placement confirmed

Phase Gates¶

Each phase must complete before the next becomes available to the worker:

Phase	Trigger to advance	Stored on
1. ID check	Sumsub webhook — applicant reviewed	`Contact` / screening record
2. Sign Phase 1	DocuSign Connect — `PHASE_ONE` envelope completed	`DocuSignEnvelope`
3. Fill data	Worker submits form (IBAN, BSN, health insurance, wage tax)	`Contact` / `Placement`
4. Sign Phase 2	DocuSign Connect — `PHASE_TWO` envelope completed	`DocuSignEnvelope`

Notes¶

DocuSign envelopes are created in draft (status=created) immediately; documents are added asynchronously as Salesforce generates and Cruits downloads them. The envelope is sent only once all expected documents are attached.
PHASE_ONE envelopes are linked to the worker directly (DocuSignEnvelope.worker); PHASE_TWO envelopes are additionally linked to a Placement.
Phase 2 documents are the screening pack (code of conduct, ABU, etc.) generated before the worker provides personal data; Phase 4 documents are the placement pack generated by Salesforce after personal data is captured (see placement-confirmation-documents-flow.md).
Both DocuSign envelopes use embedded signing with clientUserId = worker.pk; the returnUrl brings the worker back to Cruits to advance to the next phase.