> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knotapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

## **Introduction**

**Detect** enables you to identify a user's online merchant accounts and optionally retrieve them from the Knot platform, allowing you to then personalize your user experience.

## Getting started

<Tabs>
  <Tab title="Email-Based in CardSwitcher" icon="envelope">
    <Note>
      This option is for those who've already implemented the CardSwitcher product.
    </Note>

    <Steps>
      <Step title="Update session creation">
        When calling [Create Session](/api-reference/sessions/create-session) to create a session for the SDK, simply add the user's email address and phone number to the request.

        ```curl theme={"system"}
        curl --request POST \
          --url https://development.knotapi.com/session/create \
          --header 'Authorization: Basic <encoded-value>' \
          --header 'Content-Type: application/json' \
          --data '
        {
          "type": "card_switcher",
          "external_user_id": "123abc",
          "card_id": "81n9al10a0ayn13",
          "email": "ada.lovelace@gmail.com",
          "phone_number": "+11234567890"
        }
        '
        ```
      </Step>

      <Step title="Personalize the UX">
        When the merchant selection experience is rendered in the SDK, it will be automatically personalized to take into account a user's detected online merchant accounts
      </Step>

      <Step title="Optionally, receive detected merchant accounts">
        Listen for the [`NEW_DETECTED_ACCOUNTS_AVAILABLE`](/detect/webhook-events/new-detected-accounts-available) webhook event to be notified when new detected accounts have been found for a given user. The webhook payload includes a `data.detected_accounts` array with the user's detected merchant accounts.

        <Info>
          To test receiving the `NEW_DETECTED_ACCOUNTS_AVAILABLE` webhook in the development environment, pass the user's email into the `email` field when calling [Create Session](https://docs.knotapi.com/api-reference/sessions/create-session).
        </Info>
      </Step>
    </Steps>
  </Tab>

  <Tab title="Email-Based Standalone" icon="envelope">
    <Steps>
      <Step title="Access your dashboard">
        Ensure you have access to the [Knot Dashboard](https://dashboard.knotapi.com) and retrieve your `client_id` and `secret` to create an API key. Learn more about creating an API key and authentication to the API [here](/api-reference/authentication).
      </Step>

      <Step title="Call the API">
        Call [Detect Accounts](/api-reference/products/detect/detect-accounts) with the user's `email` and `phone_number`  to detect their online merchant accounts.
      </Step>

      <Step title="Receive the webhook event">
        Listen for the [`NEW_DETECTED_ACCOUNTS_AVAILABLE`](/detect/webhook-events/new-detected-accounts-available) webhook event to be notified when new detected accounts have been found for a given user. The webhook payload includes a `data.detected_accounts` array with the user's detected merchant accounts.
      </Step>
    </Steps>
  </Tab>

  <Tab title="SSO" icon="key">
    ### Start the flow

    <AccordionGroup>
      <Accordion title="Access your dashboard" defaultOpen icon="table-columns">
        Ensure you have access to the [Knot Dashboard](https://dashboard.knotapi.com) and retrieve your `client_id` and `secret` to create an API key. Learn more about creating an API key and authentication to the API [here](/api-reference/authentication).
      </Accordion>

      <Accordion title="Retrieve available merchants" defaultOpen icon="list-ul">
        Call [List Merchants](/api-reference/merchants/list-merchants) to retrieve a list of merchants that are available for merchant account detection by passing `type = detect` in the request. These are merchants you can allow users to link in your app and subsequently detect merchant accounts.

        You will be notified via the [`MERCHANT_STATUS_UPDATE`](/link/webhook-events/merchant-status-update) webhook when/if the available merchant list changes, even if temporarily.
      </Accordion>

      <Accordion title="Create a session" defaultOpen icon="code">
        With your API key for the `development` environment, call [Create Session](https://docs.knotapi.com/api-reference/sessions/create-session) with `type: link `to create a session used when invoking the SDK. More [here](/api-reference/authentication) on how to create an API key.
      </Accordion>

      <Accordion title="Install the SDK" defaultOpen icon="file-import">
        Install an SDK of your choosing, for example on iOS [here](https://docs.knotapi.com/sdk/ios) and Android [here](/sdk/android).
      </Accordion>

      <Accordion title="Initialize the SDK" defaultOpen icon="play">
        Initialize the SDK with the `session_id` retrieved from [Create Session](https://docs.knotapi.com/api-reference/sessions/create-session) and a merchant `Id` retrieved from [List Merchants](https://docs.knotapi.com/api-reference/merchants/list-merchants) in `KnotConfiguration` or you can use `merchant_id: 60`for Apple to get started quickly. The SDK is where users will interact with the Knot UI to authenticate to various merchants. All login flows, including step-up authentication, are handled within the SDK. Users will see real-time feedback as they progress through authenticating with a merchant.
      </Accordion>
    </AccordionGroup>

    ### Link a merchant account

    <AccordionGroup>
      <Accordion title="Login" defaultOpen="true" icon="arrow-right-to-bracket">
        **In the development environment,** login to a merchant account using `user_good` / `pass_good` credentials to link your user's merchant account.
      </Accordion>

      <Accordion title="Handle webhook events" defaultOpen icon="arrow-right">
        Subscribe to webhooks in the [Knot Dashboard](https://dashboard.knotapi.com/developers/webhooks) so your backend can be notified about user-generated, server-side events. Listen for the following events:

        * [`AUTHENTICATED`](/link/webhook-events/authenticated): fired when the authentication to a merchant is successful and the merchant account is therefore successfully linked to Knot. Similarly and as applicable, listen to the client-side `onEvent` callback in the SDK to receive the `authenticated` event.
        * [`NEW_DETECTED_ACCOUNTS_AVAILABLE`](/detect/webhook-events/new-detected-accounts-available): fired when new detected accounts are available.
      </Accordion>
    </AccordionGroup>

    ### Search for detected accounts

    When you receive the [`NEW_DETECTED_ACCOUNTS_AVAILABLE`](/detect/webhook-events/new-detected-accounts-available) webhook, call [Search Detected Accounts](/api-reference/products/detect/search-detected-accounts) with a list of merchant or company names that are relevant to your use case. The endpoint will return whether a detected merchant account was found for the user at each one. This is useful when you have a specific set of merchants or companies you care about and want to know if a user has an account at any of them.

    **In the development environment,** this endpoint accepts any list of `names` you provide and returns `detected: true` for 6 of them at random.

    ### Receive detected accounts

    The [`NEW_DETECTED_ACCOUNTS_AVAILABLE`](/detect/webhook-events/new-detected-accounts-available) webhook payload includes a `data.detected_accounts` array with the user's detected merchant accounts. The array includes only merchants that Knot supports on its platform (i.e. those with a `merchant_id`), making it useful for engaging or re-engaging users to provision a payment method to the merchant wallet.
  </Tab>
</Tabs>