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

# Overview

> Learn how identities work in Blnk

export const CtaCallout = props => {
  const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
  const handleCtaClick = () => {
    if (typeof window === "undefined" || !trackingEvent) {
      return;
    }
    try {
      window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
        detail: {
          name: trackingEvent,
          href
        }
      }));
    } catch {}
    try {
      window.posthog?.capture?.(trackingEvent, {
        href
      });
    } catch {}
    const gaPayload = {
      cta_href: href
    };
    try {
      window.gtag?.("event", trackingEvent, gaPayload);
    } catch {}
    try {
      window.dataLayer = window.dataLayer || [];
      window.dataLayer.push({
        event: trackingEvent,
        ...gaPayload
      });
    } catch {}
  };
  const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
  const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
  const linkRel = isExternal ? rel : undefined;
  return <section className="cta-callout not-prose relative my-8 w-full min-w-0 overflow-hidden rounded-xl border border-zinc-200 p-5 dark:border-white/10">
      <div className="cta-callout-noise" aria-hidden="true" />
      <div className="cta-callout-layout">
        {title ? <div className="cta-callout-title-row">
            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 28 28" width="14" height="14" className="cta-callout-icon shrink-0 text-zinc-800 dark:text-zinc-200" aria-hidden="true">
              <g fill="none" fillRule="nonzero">
                <path d="M28 0v28H0V0h28ZM14.691833333333335 27.134333333333334l-0.012833333333333334 0.0023333333333333335 -0.08283333333333333 0.04083333333333334 -0.023333333333333334 0.004666666666666667 -0.016333333333333335 -0.004666666666666667 -0.08283333333333333 -0.04083333333333334c-0.011666666666666667 -0.004666666666666667 -0.022166666666666668 -0.0011666666666666668 -0.028000000000000004 0.005833333333333334l-0.004666666666666667 0.011666666666666667 -0.019833333333333335 0.49933333333333335 0.005833333333333334 0.023333333333333334 0.011666666666666667 0.015166666666666667 0.12133333333333333 0.08633333333333333 0.0175 0.004666666666666667 0.014000000000000002 -0.004666666666666667 0.12133333333333333 -0.08633333333333333 0.014000000000000002 -0.018666666666666668 0.004666666666666667 -0.019833333333333335 -0.019833333333333335 -0.4981666666666667c-0.0023333333333333335 -0.011666666666666667 -0.0105 -0.019833333333333335 -0.019833333333333335 -0.021Zm0.3091666666666667 -0.13183333333333336 -0.015166666666666667 0.0023333333333333335 -0.21583333333333335 0.1085 -0.011666666666666667 0.011666666666666667 -0.0035000000000000005 0.012833333333333334 0.021 0.5016666666666667 0.005833333333333334 0.014000000000000002 0.009333333333333334 0.008166666666666668 0.23450000000000004 0.1085c0.014000000000000002 0.004666666666666667 0.026833333333333334 0 0.03383333333333334 -0.009333333333333334l0.004666666666666667 -0.016333333333333335 -0.03966666666666667 -0.7163333333333334c-0.0035000000000000005 -0.014000000000000002 -0.011666666666666667 -0.023333333333333334 -0.023333333333333334 -0.025666666666666667Zm-0.8341666666666667 0.0023333333333333335a0.026833333333333334 0.026833333333334334 0 0 0 -0.0315 0.007000000000000001l-0.007000000000000001 0.016333333333333335 -0.03966666666666667 0.7163333333333334c0 0.014000000000000002 0.008166666666666668 0.023333333333333334 0.019833333333333335 0.028000000000000004l0.0175 -0.0023333333333333335 0.23450000000000004 -0.1085 0.011666666666666667 -0.009333333333333334 0.004666666666666667 -0.012833333333333334 0.019833333333333335 -0.5016666666666667 -0.0035000000000000005 -0.014000000000000002 -0.011666666666666667 -0.011666666666666667 -0.21466666666666667 -0.10733333333333334Z" strokeWidth="1.1667" />
                <path fill="currentColor" d="M14 2.916666666666667A1.75 1.75 0 0 1 15.750000000000002 4.666666666666667v6.302333333333334L21.207666666666668 7.816666666666667a1.75 1.75 0 0 1 1.75 3.031L17.5 14l5.457666666666667 3.151166666666667a1.75 1.75 0 0 1 -1.75 3.031l-5.457666666666667 -3.1500000000000004V23.333333333333336a1.75 1.75 0 0 1 -3.5 0v-6.302333333333334L6.792333333333334 20.183333333333337a1.75 1.75 0 1 1 -1.75 -3.031L10.5 14 5.042333333333334 10.848833333333333a1.75 1.75 0 0 1 1.75 -3.031l5.457666666666667 3.1500000000000004V4.666666666666667A1.75 1.75 0 0 1 14 2.916666666666667Z" strokeWidth="1.1667" />
              </g>
            </svg>
            <p className="cta-callout-title min-w-0 font-semibold text-zinc-800 dark:text-zinc-200">
              {title}
            </p>
          </div> : null}
        <div className={`cta-callout-body text-sm leading-normal text-zinc-800 dark:text-zinc-200${title ? " cta-callout-body--indented" : ""}`}>
          {children}
        </div>
        <a href={href} target={target} rel={linkRel} onClick={handleCtaClick} data-docs-cta={trackingEvent || undefined} className="cta-callout-button inline-flex items-center justify-center gap-1 rounded-full bg-white px-3 py-1.5 text-sm font-semibold transition hover:bg-zinc-100 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-white/50 dark:bg-white dark:hover:bg-zinc-200">
          {buttonLabel}
          <span className="cta-callout-button-arrow" aria-hidden="true">
            →
          </span>
        </a>
      </div>
    </section>;
};

Identities allow you to securely record and manage customer (individual or organization) data within your Blnk Ledger. By keeping your customer data in your Ledger, you can link each identity to their respective balance and transactions, giving you a unified view of a customer's financial activities.

In this guide, you'll learn how to create identities and link them to balances and transactions.

<Warning>**Identities in Blnk Ledger are not a replacement for KYC verification.** While they enable you to securely store and manage customer data, you can integrate third-party tools to handle KYC verification. This ensures your compliance needs are met while maintaining a unified and organized system for managing customer information.</Warning>

***

## Create an identity

First step in managing and linking identities is to create one. There are two identity types in the Blnk Ledger - individual and organization.

While Blnk has predefined attributes for creating an identity in your Ledger, you can add custom fields for your application using the `metadata` object.

<CodeGroup>
  ```bash cURL wrap expandable theme={"system"}
  curl -X POST "http://localhost:5001/identities" \
    -H "X-blnk-key: <api-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "identity_type": "individual",
      "organization_name": "",
      "first_name": "Alice",
      "last_name": "Smith",
      "other_names": "Marie",
      "gender": "female",
      "dob": "1985-05-15T00:00:00Z",
      "email_address": "alice.smith@example.com",
      "phone_number": "+1234567890",
      "nationality": "Canadian",
      "category": "customer",
      "street": "789 Elm St",
      "country": "Canada",
      "state": "Ontario",
      "post_code": "M4B 1B3",
      "city": "Toronto",
      "meta_data": {
          "customer_id": "CUST123456",
          "membership_level": "Gold",
          "preferred_language": "English",
          "verification_data": {
              "verified_by": "ThirdPartyService",
              "verification_date": "2024-07-01T10:00:00Z",
              "verification_status": "verified"
          }
      }
    }'
  ```

  ```typescript TypeScript wrap expandable theme={"system"}
  const response = await blnk.Identity.create({
    identity_type: 'individual',
    organization_name: '',
    first_name: 'Alice',
    last_name: 'Smith',
    other_names: 'Marie',
    gender: 'female',
    dob: new Date('1985-05-15'),
    email_address: 'alice.smith@example.com',
    phone_number: '+1234567890',
    nationality: 'Canadian',
    category: 'customer',
    street: '789 Elm St',
    country: 'Canada',
    state: 'Ontario',
    post_code: 'M4B 1B3',
    city: 'Toronto',
    meta_data: {
      customer_id: 'CUST123456',
      membership_level: 'Gold',
      preferred_language: 'English',
      verification_data: {
        verified_by: 'ThirdPartyService',
        verification_date: '2024-07-01T10:00:00Z',
        verification_status: 'verified',
      },
    },
  });
  ```

  ```go Go wrap expandable theme={"system"}
  dob, _ := time.Parse(time.RFC3339, "1985-05-15T00:00:00Z")
  identity, resp, err := client.Identity.Create(blnkgo.Identity{
    IdentityType: blnkgo.Individual,
    FirstName:         "Alice",
    LastName:          "Smith",
    OtherNames:        "Marie",
    Gender:            "female",
    DOB:               &dob,
    EmailAddress:      "alice.smith@example.com",
    PhoneNumber:       "+1234567890",
    Nationality:       "Canadian",
    Category:          "customer",
    Street:            "789 Elm St",
    Country:           "Canada",
    State:             "Ontario",
    PostCode:          "M4B 1B3",
    City:              "Toronto",
    MetaData: map[string]interface{}{
      "customer_id":        "CUST123456",
      "membership_level":   "Gold",
      "preferred_language": "English",
      "verification_data": map[string]interface{}{
        "verified_by":          "ThirdPartyService",
        "verification_date":  "2024-07-01T10:00:00Z",
        "verification_status": "verified",
      },
    },
  })
  ```
</CodeGroup>

```json Response theme={"system"}
{
  "identity_id": "idt_11111111-1111-4111-8111-111111111111",
  "identity_type": "individual",
  "first_name": "Alice",
  "last_name": "Smith",
  "email_address": "alice.smith@example.com",
  "created_at": "2024-11-26T08:36:36.238244338Z"
}
```

| Property            | Description                                                          | Type     |
| :------------------ | :------------------------------------------------------------------- | :------- |
| `identity_type`     | Specifies the identity type. Can be "individual" or "organization".  | `string` |
| `organization_name` | Name of the organization.                                            | `string` |
| `first_name`        | First name of the individual.                                        | `string` |
| `last_name`         | Last name of the individual.                                         | `string` |
| `other_names`       | Any other names linked to the individual.                            | `string` |
| `gender`            | Gender of the individual.                                            | `string` |
| `dob`               | Date of birth.                                                       | `date`   |
| `email_address`     | Email address of the identity.                                       | `string` |
| `phone_number`      | Contact number of the identity.                                      | `string` |
| `nationality`       | Nationality of the individual.                                       | `string` |
| `category`          | Type of customer depending on your use case, e.g. VIP, regular, etc. | `string` |
| `street`            | Street address of the identity.                                      | `string` |
| `country`           | Residential country of the identity.                                 | `string` |
| `state`             | State of residence of the identity.                                  | `string` |
| `post_code`         | Postal code related to the identity.                                 | `string` |
| `city`              | City of residence of the identity.                                   | `string` |
| `meta_data`         | Custom metadata linked to the identity.                              | `object` |

### Caller-supplied identity IDs

By default, Blnk generates an `identity_id` when you create an identity. You can instead pass `identity_id` in the request body to create a deterministic ID from your own holder reference.

The value must start with `idt_` followed by a valid UUID, for example `idt_8cc22560-5ace-4989-8953-fcbad7947d48`. See [Create identity](/reference/create-identity) for validation errors and the full request shape.

<CodeGroup>
  ```bash cURL wrap theme={"system"}
  curl -X POST "http://localhost:5001/identities" \
    -H "X-blnk-key: <api-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "identity_id": "idt_8cc22560-5ace-4989-8953-fcbad7947d48",
      "identity_type": "individual",
      "first_name": "Alice",
      "last_name": "Smith",
      "email_address": "alice.smith@example.com"
    }'
  ```

  ```typescript TypeScript wrap theme={"system"}
  const response = await blnk.Identity.create({
    identity_id: 'idt_8cc22560-5ace-4989-8953-fcbad7947d48',
    identity_type: 'individual',
    first_name: 'Alice',
    last_name: 'Smith',
    email_address: 'alice.smith@example.com',
  });
  ```
</CodeGroup>

***

## Update an identity

To update an identity, call the **Update Identity** endpoint:

<CodeGroup>
  ```bash cURL wrap expandable theme={"system"}
  curl -X PUT "http://localhost:5001/identities/{identity_id}" \
    -H "X-blnk-key: <api-key>" \
    -H "Content-Type: application/json" \
    -d '{
      "identity_type": "individual",
      "first_name": "Alice",
      "last_name": "Smith",
      "other_names": "Marie",
      "gender": "female",
      "dob": "1985-05-15T00:00:00Z",
      "email_address": "alice.smith@example.com",
      "phone_number": "+1234567890",
      "nationality": "Canadian",
      "category": "customer",
      "street": "789 Elm St",
      "country": "Canada",
      "state": "Ontario",
      "post_code": "M4B 1B3",
      "city": "Toronto",
      "meta_data": {
          "customer_id": "CUST123456",
          "membership_level": "Gold",
          "preferred_language": "English",
          "verification_data": {
              "verified_by": "ThirdPartyService",
              "verification_date": "2024-07-01T10:00:00Z",
              "verification_status": "verified"
          }
      }
    }'
  ```

  ```typescript TypeScript wrap expandable theme={"system"}
  const response = await blnk.Identity.update('{identity_id}', {
    identity_type: 'individual',
    first_name: 'Alice',
    last_name: 'Smith',
    other_names: 'Marie',
    gender: 'female',
    dob: new Date('1985-05-15'),
    email_address: 'alice.smith@example.com',
    phone_number: '+1234567890',
    nationality: 'Canadian',
    category: 'customer',
    street: '789 Elm St',
    country: 'Canada',
    state: 'Ontario',
    post_code: 'M4B 1B3',
    city: 'Toronto',
    meta_data: {
      customer_id: 'CUST123456',
      membership_level: 'Gold',
      preferred_language: 'English',
      verification_data: {
        verified_by: 'ThirdPartyService',
        verification_date: '2024-07-01T10:00:00Z',
        verification_status: 'verified',
      },
    },
  });
  ```

  ```go Go wrap theme={"system"}
  identity, resp, err := client.Identity.Update("idt_8cc22560-5ace-4989-8953-fcbad7947d48", &blnkgo.Identity{
    FirstName: "Alice",
    LastName:  "Smith",
  })
  ```
</CodeGroup>

```json Response theme={"system"}
{
  "identity_id": "idt_8cc22560-5ace-4989-8953-fcbad7947d48",
  "identity_type": "individual",
  "first_name": "Alice",
  "last_name": "Smith",
  "updated_at": "2024-11-26T08:36:36.238244338Z"
}
```

***

## Delete an identity

To delete an identity, call the [Delete identity](/reference/delete-identity) endpoint:

<CodeGroup>
  ```bash cURL wrap theme={"system"}
  curl -X DELETE "http://YOUR_BLNK_INSTANCE_URL/identities/{identity_id}" \
    -H "X-blnk-key: <api-key>"
  ```

  ```typescript TypeScript wrap theme={"system"}
  const response = await blnk.Identity.delete('idt_8cc22560-5ace-4989-8953-fcbad7947d48');
  ```
</CodeGroup>

```json Response theme={"system"}
{
  "message": "Identity deleted successfully"
}
```

***

## Why use Identities

### 1. Centralized & comprehensive customer management

* **Unified records:** Storing identities on your Ledger provides a single, reliable source of truth for all customer data. This ensures that every team-technical or non-technical-has consistent access to the same information.

* **Seamless linking:** Identities are inherently connected to balances and transactions, creating a network of data that is easy to navigate and manage. This eliminates the need for complex cross-referencing between separate systems.

* **Efficient collaboration:** Teams working across functions-whether fraud & compliance, customer support, internal controls, or finance-can access and act on interconnected data effortlessly, leading to quicker resolutions and informed decisions.

### 2. Enhanced security and accountability

* **Tamper proof:** The Blnk Ledger ensures data integrity by recording changes in an auditable, unalterable format. Every update to an identity, balance, or transaction is logged, creating a robust audit trail.

* **Secure infrastructure:** Blnk employs enterprise-grade security controls to safeguard customer data against unauthorized access. Our commitment to security and compliance is demonstrated through our certifications and adherence to industry standards, including ISO 27001, PCI-DSS, SOC 2, and GDPR.

### 3. Data-driven customer insights

* **Behavioural patterns:** By linking identities to transactions, you can get insights into the spending habits, unusual activity, and long-term trends. These insights help refine strategies and improve customer offerings.

* **Customer personalization:** Knowing your customer’s complete financial history allows for tailored experiences, from customized product offerings to proactive communication based on their specific needs.

### 4. Proactive fraud prevention

* **Identity validation:** By recording identities, it’s easier to detect and prevent inconsistencies, such as duplicate accounts or incomplete credentials.

* **Anomaly detection:** Sudden spikes in activity, unusual transaction frequencies, or mismatched identity details can be identified in real-time, helping you proactively address potential issues and stay on top of your AML controls.

* **Regulatory risk mitigation:** Recurring compliance risks-like transactions involving blacklisted entities-can be monitored and addressed effectively, safeguarding your business.

## Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool.

To ask questions or discuss issues, please [contact us](mailto:support@blnkfinance.com) or [join our Discord community](https://discord.gg/7WNv94zPpx).

<CtaCallout title="Connect your ledger to Blnk Cloud" href="https://cloud.blnkfinance.com/auth/sign-up?utm_source=blnk_docs&utm_medium=documentation&utm_campaign=need-help" buttonLabel="Open Blnk Cloud" trackingEvent="clicked_cloud_signup">
  Sign up and manage your ledger with our back-office dashboard. You can invite teammates to collaborate and manage your ledger operations directly from the dashboard.
</CtaCallout>