An identity is the root object in Ravi. Each one bundles an email inbox, an optional
phone number, a contact book, and a credential vault into a single persona your agent
owns and operates as — over the CLI, the Python SDK, and the TypeScript SDK.

Start here: create an identity, then everything else (email, phone, contacts, vault)
hangs off it. You create and list identities through the account-level client, so the
examples below show that setup once with your API key.

## Create an identity

Give it a name and an email handle. Add `provision_phone` to get a real phone number
too. You get back an identity with `identity.email.address` set, and
`identity.phone.number` when you provisioned one.

CLI:
```bash
ravi identity create \
  --name "Support Agent" \
  --email-identifier support \
  --provision-phone
```

Python:
```python
from ravi import Ravi

ravi = Ravi(api_key="ravi_mgmt_...")

identity = ravi.identities.create(
    name="Support Agent",
    email_identifier="support",
    provision_phone=True,
)
print(identity.email.address)   # support@ravi.app
print(identity.phone.number)    # +15551234567
```

TypeScript:
```typescript
import { Ravi } from "@ravi-hq/sdk";

const ravi = new Ravi({ apiKey: process.env.RAVI_API_KEY! });

const identity = await ravi.identities.create({
  name: "Support Agent",
  email_identifier: "support",
  provision_phone: true,
});
console.log(identity.email.address);   // support@ravi.app
console.log(identity.phone?.number);   // +15551234567
```

## List identities

See every identity on your account.

CLI:
```bash
ravi identity list
```

Python:
```python
ravi = Ravi(api_key="ravi_mgmt_...")

for identity in ravi.identities.list():
    print(identity.name, identity.email.address)
```

TypeScript:
```typescript
const ravi = new Ravi({ apiKey: process.env.RAVI_API_KEY! });

const identities = await ravi.identities.list();
for (const identity of identities) {
  console.log(identity.name, identity.email.address);
}
```

## Get one identity

Fetch a single identity by its uuid. On the CLI, this sets the active identity so
later commands operate on it.

CLI:
```bash
ravi identity use <identity-uuid>
```

Python:
```python
identity = ravi.identities.get("<identity-uuid>")
print(identity.email.address)
```

TypeScript:
```typescript
const identity = await ravi.identities.get("<identity-uuid>");
console.log(identity.email.address);
```

## Rename an identity

Update the display name. (Python and TypeScript only.)

Python:
```python
identity = ravi.identities.update("<identity-uuid>", name="Sales Agent")
```

TypeScript:
```typescript
const identity = await ravi.identities.update("<identity-uuid>", {
  name: "Sales Agent",
});
```

## Add a phone number later

Created an identity without a phone? Provision one at any time and
`identity.phone.number` fills in. (Python and TypeScript only.)

Python:
```python
identity = ravi.identities.provision_phone("<identity-uuid>")
print(identity.phone.number)
```

TypeScript:
```typescript
const identity = await ravi.identities.provisionPhone("<identity-uuid>");
console.log(identity.phone?.number);
```

---

Once you have an identity, put it to work: give it an [email inbox](/core-concepts/email/)
or a [phone number](/core-concepts/phone-and-sms/).

Looking for exact request and response fields? See the full [API reference](/api/reference/).