> ## Documentation Index
> Fetch the complete documentation index at: https://developer.sandbox.co.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Web

> Integrate EntityLocker SDK into your web application using JavaScript

Integrate EntityLocker business document retrieval into your web application using the JavaScript SDK. The SDK provides a pre-built interface that handles the complete EntityLocker flow.

<Steps>
  <Step title="Create a session" stepNumber={1} titleSize="h2">
    Before initializing the SDK, you must create a **unique session**.
    Each SDK instance requires its own session to ensure secure and independent interactions.

    Use the [Create Session](../../endpoints/create_session) endpoint to generate this session.
    This is a **server-side API call** that uses [Sandbox Authentication](/api-reference/authenticate) to validate your credentials.

    Once created, you'll receive a `session_id`, which you'll need when initializing the SDK on the client side.
  </Step>

  <Step title="Add the SDK script" stepNumber={2} titleSize="h2">
    Include the EntityLocker SDK script in your HTML page.

    ```html theme={null}
    <script src="https://sdk.sandbox.co.in/kyc/entitylocker/sdk.js"></script>
    ```

    The SDK is loaded globally and available as `EntitylockerSDK`.
  </Step>

  <Step title="Initialize the SDK" stepNumber={3} titleSize="h2">
    Configure and launch the EntityLocker SDK when the user initiates document retrieval.

    <AccordionGroup>
      <Accordion title="3.1 Basic implementation" defaultOpen>
        ```html theme={null}
        <button onclick="launch()">Fetch with EntityLocker</button>

        <script>
          function launch() {
            // Set your API key
            EntitylockerSDK.setAPIKey("YOUR_API_KEY");

            // Configure the SDK options
            const options = {
              session_id: "a7fac865-61a9-4589-b80c....", // Replace with your session ID from Step 1
              brand: {
                name: "MoneyApp", // Your business or app name
                logo_url: "https://example.com/your_logo", // Publicly accessible URL of your logo
              },
              theme: {
                mode: "light", // Options: "light" or "dark"
                seed: "#3D6838", // Primary color for theme customization
              },
            };

            // Launch the EntityLocker SDK
            EntitylockerSDK.open(options);
          }
        </script>
        ```
      </Accordion>

      <Accordion title="3.2 SDK options reference">
        ```json theme={null}
        {
          "session_id": "a7fac865-61a9-4589-b80c....",
          "brand": {
            "name": "MoneyApp",
            "logo_url": "https://example.com/your_logo"
          },
          "theme": {
            "mode": "light",
            "seed": "#3D6838"
          }
        }
        ```

        <ParamField body="session_id" type="string" required placeholder="a7fac865-61a9-4589-b80c....">
          Unique session ID generated when Create Session API is called.
        </ParamField>

        <ParamField body="brand" type="object" required>
          Configuration for branding displayed in the EntityLocker interface.

          <Expandable title="child attributes">
            <ParamField body="name" type="string" required>
              Display name of your business or app shown during the EntityLocker flow.
            </ParamField>

            <ParamField body="logo_url" type="string" required>
              Publicly accessible HTTPS URL of your logo displayed within the SDK.
            </ParamField>
          </Expandable>
        </ParamField>

        <ParamField body="theme" type="object" required>
          Appearance configuration for the SDK.

          <Expandable title="child attributes">
            <ParamField body="mode" type="string" required>
              Sets the overall appearance of the SDK. Accepts `"light"` or `"dark"`.
            </ParamField>

            <ParamField body="seed" type="string" required>
              Primary brand color used in the SDK interface. Accepts a hex code.
            </ParamField>
          </Expandable>
        </ParamField>
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Handle SDK events" stepNumber={4} titleSize="h2">
    Set up an event listener to handle SDK events indicating session completion, cancellation, or errors.

    ```javascript theme={null}
    // Define a custom event listener to handle SDK events
    class EventListener extends EntitylockerSDK.EventListener {
      constructor(callback) {
        super();
        this.callback = callback;
      }
      onEvent(event) {
        if (this.callback) {
          this.callback(event);
        }
      }
    }

    // Define a callback function to process events from the SDK
    const handleEvent = (event) => {
      console.log("Received event:", event);
      
      switch (event.type) {
        case "in.co.sandbox.kyc.entitylocker_sdk.session.completed":
          // Documents were fetched successfully
          // Proceed with your application flow
          fetchDocumentsFromBackend(sessionId);
          break;

        case "in.co.sandbox.kyc.entitylocker_sdk.session.closed":
          // User closed or exited the SDK
          showMessage("Document retrieval cancelled");
          break;

        default:
          console.log("Unhandled event:", event);
      }
    };

    // Initialize the event listener with your callback
    const eventListener = new EventListener(handleEvent);
    EntitylockerSDK.setEventListener(eventListener);
    ```

    To programmatically verify the final status of a session, call the [Session Status](../../endpoints/get_session_status) endpoint from your backend.
  </Step>
</Steps>

## Event types

The SDK emits the following event types:

| Event Type                                             | Description                                                                    |
| ------------------------------------------------------ | ------------------------------------------------------------------------------ |
| `in.co.sandbox.kyc.entitylocker_sdk.session.completed` | User successfully completed the EntityLocker flow and documents were retrieved |
| `in.co.sandbox.kyc.entitylocker_sdk.session.closed`    | User closed the SDK without completing the flow                                |

## Next steps

<CardGroup cols={3}>
  <Card title="Create Session API" icon="code" href="../../endpoints/create_session">
    Learn how to create sessions for the SDK
  </Card>

  <Card title="Session Status API" icon="clock" href="../../endpoints/get_session_status">
    Monitor session progress and status
  </Card>

  <Card title="Fetch Document API" icon="file" href="../../endpoints/fetch_document">
    Retrieve document data after completion
  </Card>
</CardGroup>