# Origamy playbook spec v1. Reference: /playbooks/spec-format/
spec_version: 1
id: lending.kyc-nudge
title: KYC nudge
sector: lending
source:
  kind: synthesized
  notes: >-
    No lender has built this with us yet. Written from the base onboarding nudge, with a call
    from the onboarding team and an exit the moment verification is approved. Messages never
    ask for documents, numbers or codes over SMS or email.
derived_from: base.welcome-onboarding
vocabulary:
  person: customer
  people: customers
  group: team
summary: >-
  New sign-ups who haven't finished identity verification (KYC) get a reminder the next day,
  another three days later, and then a call from your onboarding team. Everything stops once
  they're verified.
when_to_use:
  - People sign up for a loan, wallet or account and must verify their identity before they can use it.
  - Your system sends an event when someone signs up and another when verification is approved.

requires:
  data_in:
    - how: app_events
      what: "Your app sends the sign-up and KYC-approved events."
  channels:
    - channel: sms
      for: The first reminder
      needs: An SMS provider, or Origamy managed SMS after business verification (KYC).
    - channel: email
      for: The second reminder
      needs: A verified sending domain for {{ params.email_from }}.
  events:
    - "{{ params.signup_event }}"
    - "{{ params.approved_event }}"
  traits: []

parameters:
  - key: org_name
    ask: true
    question: What should messages call your company?
    label: Company name
    type: string
    example: Northwind Credit
  - key: signup_event
    ask: true
    question: Which event means someone signed up?
    label: Sign-up event
    type: event_name
    default: Signed Up
  - key: approved_event
    ask: true
    question: Which event means their verification was approved?
    label: Approved event
    type: event_name
    default: KYC Approved
  - key: app_url
    ask: true
    question: Where do they finish verification? (your app or a deep link)
    label: Verification link
    type: url
    example: https://app.yourcompany.example/verify
  - key: onboarding_team
    ask: true
    question: Which team calls people who still haven't verified?
    label: Onboarding team
    type: team_name
    default: Onboarding
  - key: email_from
    label: Sender address
    type: email
    default: "{{ workspace.default_sender }}"
  - key: greeting_fallback
    label: Greeting when a first name is missing
    type: string
    default: there

timings:
  - SMS 1 day after sign-up, email 3 days later, call task 3 days after that (due in 48 hours).
  - Stops as soon as {{ params.approved_event }} arrives.

customer_must:
  - Send {{ params.signup_event }} and {{ params.approved_event }} from your backend.
  - Never ask for ID numbers, documents, PINs or one-time codes by message. These messages only point to your app; say so on your support pages so customers can spot fakes.
  - Add people to the {{ params.onboarding_team }} team.
  - Connect an SMS provider or finish business verification, verify the sending domain, then switch the follow-up on and test it.

objects:
  - ref: team_onboarding
    kind: team
    about: Calls people who haven't verified.
    body: { name: "{{ params.onboarding_team }}" }
  - ref: seg_unverified
    kind: segment
    about: Signed up in the last 30 days, not verified.
    body:
      name: Signed up, not verified
      description: "{{ params.signup_event }} in the last 30 days, no {{ params.approved_event }}."
      segment_type: dynamic
      status: active
      definition:
        operator: and
        conditions:
          - { type: event, event_name: "{{ params.signup_event }}", cond_operator: has_done, time_window: 30d }
          - { type: event, event_name: "{{ params.approved_event }}", cond_operator: has_not_done, time_window: 30d }
  - ref: tmpl_sms
    kind: template
    about: First reminder by SMS.
    body:
      name: Finish verification (SMS)
      channel: sms
      category: Onboarding
      style: text
      status: active
      subject: ""
      metadata: {}
      variables: {}
      body: "{{ params.org_name }}: you're almost set up. Finish verifying your identity in the app: {{ params.app_url }} We will never ask for your PIN or codes. Reply STOP to opt out."
  - ref: tmpl_email
    kind: template
    about: Second reminder by email.
    body:
      name: Finish verification (email)
      channel: email
      category: Onboarding
      style: html
      status: active
      subject: "One step left to use {{ params.org_name }}"
      metadata: { email: { from: "{{ params.email_from }}", preview_text: "It takes about five minutes." } }
      variables: {}
      body: >-
        <p>Hi {{ traits.first_name | default: "{{ params.greeting_fallback }}" }},</p>
        <p>To keep your account safe, we need to verify your identity before you can use
        {{ params.org_name }}. It takes about five minutes in the app.</p>
        <p><a href="{{ params.app_url }}">Finish verification</a></p>
        <p>We will never ask for your PIN, password or one-time codes by email, SMS or phone.</p>
        <p style="font-size:12px;color:#6b6b80"><a href="{{ unsubscribe_url }}">Unsubscribe</a></p>
  - ref: wf_kyc
    kind: workflow
    about: SMS, email, then a call task; exits on approval.
    body:
      name: KYC nudge
      description: Reminders and a call for people who haven't verified; stops on approval.
      enabled: false
      trigger_type: event
      trigger_config: { event_name: "{{ params.signup_event }}" }
      steps:
        - { id: s1, type: delay, config: { duration: 1d } }
        - { id: s2, type: action, config: { action_type: send_message, channel_config: { mode: single, single: { channel: sms, template_id: "{{ ref.tmpl_sms.id }}" } } } }
        - { id: s3, type: delay, config: { duration: 3d } }
        - { id: s4, type: action, config: { action_type: send_message, channel_config: { mode: single, single: { channel: email, template_id: "{{ ref.tmpl_email.id }}" } } } }
        - { id: s5, type: delay, config: { duration: 3d } }
        - id: s6
          type: human_task
          config:
            human_task:
              title: "Not verified: {{ traits.first_name }} {{ traits.last_name }}"
              instructions: |-
                {{ traits.first_name }} {{ traits.last_name }} ({{ traits.phone }}) signed up a week ago and hasn't finished verification.
                Call to help them through it in the app. Never take ID numbers, documents or codes over the phone.
              assignee_refs: [{ type: team, id: "{{ ref.team_onboarding.id }}" }]
              strategy: round_robin
              completion_policy: first_response_wins
              outcome_options:
                - { id: helped, label: Helped, intent: positive }
                - { id: not_interested, label: Not interested, intent: neutral }
                - { id: not_reached, label: Could not reach, intent: negative }
              due_hours: 48
              wait: false
              notify: immediate
      re_entry_policy: once
      re_entry_cooldown_hours: 24
      goal: { event_name: "{{ params.approved_event }}", attribution_window_hours: 720 }
      exit_conditions: [{ event_name: "{{ params.approved_event }}" }]

eval:
  name: 72_lending_kyc_nudge
  mode: task
  vertical: ""
  prompt: >-
    People sign up for our loan app but many never finish KYC. Text them the day after
    sign-up, email them a few days later, and then have our onboarding team call. Stop once
    their KYC is approved.
  expect_artifacts: [workflow, message_template]
  forbid_terms: []