# Identities API

> Agent identities: an inbox, a password and an optional persona for one sign-up. Every identities endpoint with its scope, parameters, body and an example answer.

Source: https://docs.dissolve.email/reference/identities

Base URL `https://api.dissolve.email`. Send an API key or OAuth access token as `Authorization: Bearer <token>` ([Authentication](/authentication)); an OAuth token needs the scope on each endpoint. Errors follow [one shape](/errors).

| Endpoint | Summary |
|---|---|
| `GET /v1/identities` | [List identities](#list-identities) |
| `POST /v1/identities` | [Create an identity](#create-an-identity) |
| `GET /v1/identities/{id}` | [Get an identity](#get-an-identity) |
| `PATCH /v1/identities/{id}` | [Extend or relabel an identity](#extend-or-relabel-an-identity) |
| `DELETE /v1/identities/{id}` | [Delete an identity](#delete-an-identity) |
| `GET /v1/identities/{id}/messages` | [List an identity's messages](#list-an-identity-s-messages) |
| `GET /v1/identities/{id}/messages/{messageId}` | [Get an identity's message](#get-an-identity-s-message) |
| `GET /v1/identities/{id}/wait` | [Wait for an identity's next message](#wait-for-an-identity-s-next-message) |
| `GET /v1/identities/{id}/code` | [Get the code sent to an identity](#get-the-code-sent-to-an-identity) |

### List identities

`GET /v1/identities` (scope `identities:read`)

Live agent identities with their passwords (Pro and Business). `expired=true` includes expired ones.

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `expired` | boolean | no | Include identities whose inbox has expired. |

```bash cURL
curl "https://api.dissolve.email/v1/identities" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listIdentities();
```

```bash CLI
dna list --json
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get("https://api.dissolve.email/v1/identities", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "identities": [
    {
      "id": "idn4Rk2PqT9wYc1Lm0ZxA",
      "email": "signup7f2k@dissolve.email",
      "password": "w8#Kq2!vLz9@pR4m",
      "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
      "label": "GitHub test account",
      "expiresAt": "2026-11-19T10:30:00.000Z",
      "expired": false,
      "createdAt": "2026-11-19T10:00:00.000Z",
      "persona": null
    }
  ]
}
```

### Create an identity

`POST /v1/identities` (scope `identities:write`)

Makes an inbox and a strong password for one sign-up, and with `persona` a fictional person (name, birthday, address) to fill in the form. The password comes back in the answer and stays readable with GET. Pro 10 live identities, Business 50; at most 30 new ones an hour.

**Body** (`application/json`)

| Name | Type | Required | Description |
|---|---|---|---|
| `label` | string | no | What it is for, such as GitHub test account. At most 100 characters. |
| `ttlMinutes` | integer | no | Minutes until it expires. Default `30`. 1 to 1440. |
| `prefix` | string | no | Start of the address (letters and digits); four random characters follow. At most 20 characters. |
| `domain` | string | no | A domain from GET /v1/domains. |
| `passwordLength` | integer | no | Length of the generated password. Default `16`. 8 to 64. |
| `persona` | boolean | no | Also make a fictional person. |
| `country` | string | no | The persona's country. One of `US`, `UK`, `AU`, `CA`, `DE`, `FR`, `JP`, `BR`, `IN`, `ES`, `IT`, `NL`, `KR`, `MX`, `SE`, `PL`, `NZ`. |
| `gender` | string | no | The persona's gender. One of `male`, `female`. |
| `inboxId` | string | no | Attach the identity to an inbox you already own instead of making one. |

```bash cURL
curl -X POST "https://api.dissolve.email/v1/identities" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"label":"GitHub test account","ttlMinutes":30,"persona":true,"country":"AU"}'
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.createIdentity({
  label: "GitHub test account",
  ttlMinutes: 30,
  persona: true,
  country: "AU"
});
```

```bash CLI
dna create --label "GitHub test account" --ttl 30 --persona --country AU --json
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.post("https://api.dissolve.email/v1/identities", json={
  "label": "GitHub test account",
  "ttlMinutes": 30,
  "persona": True,
  "country": "AU"
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `201`

```json
{
  "id": "idn4Rk2PqT9wYc1Lm0ZxA",
  "email": "signup7f2k@dissolve.email",
  "password": "w8#Kq2!vLz9@pR4m",
  "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
  "expiresAt": "2026-11-19T10:30:00.000Z",
  "ttlMinutes": 30,
  "label": "GitHub test account",
  "persona": {
    "firstName": "Mia",
    "lastName": "Nguyen",
    "fullName": "Mia Nguyen",
    "gender": "female",
    "country": "AU",
    "username": "mia.nguyen84",
    "dateOfBirth": "1984-06-12",
    "address": {
      "street": "14 Wattle Street",
      "city": "Brisbane",
      "state": "QLD",
      "zip": "4000",
      "formatted": "14 Wattle Street, Brisbane QLD 4000"
    },
    "phone": "+61 412 555 019"
  }
}
```

### Get an identity

`GET /v1/identities/{id}` (scope `identities:read`)

One identity with its password, persona and message count.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The identitie id. |

```bash cURL
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.getIdentity(identityId);
```

```bash CLI
dna get "$IDENTITY_ID" --json
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/identities/{identity_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "id": "idn4Rk2PqT9wYc1Lm0ZxA",
  "email": "signup7f2k@dissolve.email",
  "password": "w8#Kq2!vLz9@pR4m",
  "inboxId": "V1StGXR8Z5jdHi6BmyT2k",
  "label": "GitHub test account",
  "expiresAt": "2026-11-19T10:30:00.000Z",
  "expired": false,
  "createdAt": "2026-11-19T10:00:00.000Z",
  "persona": null,
  "messageCount": 1
}
```

### Extend or relabel an identity

`PATCH /v1/identities/{id}` (scope `identities:write`)

Sets the identity to expire `ttlMinutes` from now (default: the plan's extension time) and changes its label, within the plan's longest inbox life.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The identitie id. |

**Body** (`application/json`)

| Name | Type | Required | Description |
|---|---|---|---|
| `ttlMinutes` | integer | no | Minutes from now until it expires. 1 to 1440. |
| `label` | string | no | A new label. At most 100 characters. |

```bash cURL
curl -X PATCH "https://api.dissolve.email/v1/identities/$IDENTITY_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttlMinutes":60}'
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.updateIdentity(identityId, {
  ttlMinutes: 60
});
```

```bash CLI
dna extend "$IDENTITY_ID" --ttl 60
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.patch(f"https://api.dissolve.email/v1/identities/{identity_id}", json={
  "ttlMinutes": 60
}, headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "id": "idn4Rk2PqT9wYc1Lm0ZxA",
  "expiresAt": "2026-11-19T11:05:00.000Z",
  "ttlMinutes": 60,
  "label": "GitHub test account"
}
```

### Delete an identity

`DELETE /v1/identities/{id}` (scope `identities:write`)

Deletes the identity and its inbox with every message. `keepInbox=true` deletes only the identity.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The identitie id. |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `keepInbox` | boolean | no | Keep the inbox and its mail. |

```bash cURL
curl -X DELETE "https://api.dissolve.email/v1/identities/$IDENTITY_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.deleteIdentity(identityId);
```

```bash CLI
dna delete "$IDENTITY_ID"
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.delete(f"https://api.dissolve.email/v1/identities/{identity_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "deleted": true
}
```

### List an identity's messages

`GET /v1/identities/{id}/messages` (scope `messages:read`)

The newest 50 messages with a 200 character snippet each.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The identitie id. |

```bash cURL
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID/messages" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.listIdentityMessages(identityId);
```

```bash CLI
dna messages "$IDENTITY_ID" --json
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/identities/{identity_id}/messages", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "messages": [
    {
      "id": "Qm8wZ1kX0pLr7aYtV3nBc",
      "from": "noreply@github.com",
      "fromName": "GitHub",
      "subject": "Your GitHub launch code",
      "snippet": "Here is your GitHub launch code: 482913",
      "receivedAt": "2026-11-19T10:02:11.000Z"
    }
  ]
}
```

### Get an identity's message

`GET /v1/identities/{id}/messages/{messageId}` (scope `messages:read`)

One message with its text and HTML bodies.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The identitie id. |
| `messageId` | The message id. |

```bash cURL
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID/messages/$MESSAGE_ID" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.getIdentityMessage(identityId, messageId);
```

```bash CLI
dna message "$IDENTITY_ID" "$MESSAGE_ID"
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/identities/{identity_id}/messages/{message_id}", headers={"Authorization": f"Bearer {API_KEY}"})
print(response.json())
```

**Response** `200`

```json
{
  "id": "Qm8wZ1kX0pLr7aYtV3nBc",
  "from": "noreply@github.com",
  "fromName": "GitHub",
  "subject": "Your GitHub launch code",
  "bodyText": "Here is your GitHub launch code: 482913",
  "bodyHtml": "<p>Here is your GitHub launch code: <b>482913</b></p>",
  "snippet": "Here is your GitHub launch code: 482913",
  "receivedAt": "2026-11-19T10:02:11.000Z"
}
```

### Wait for an identity's next message

`GET /v1/identities/{id}/wait` (scope `messages:read`)

Holds the request until a message arrives after it started, or `timeout` (default 30, capped by the plan) runs out.

**Path parameters**

| Name | Description |
|---|---|
| `id` | The identitie id. |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `timeout` | integer | no | Seconds to wait, capped by the plan (Pro 30, Business 120). Default `30`. 1 to 300. |

```bash cURL
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID/wait?timeout=30" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.waitForIdentityMessage(identityId, { timeout: 30 });
```

```bash CLI
dna wait "$IDENTITY_ID" --timeout 30 --json
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/identities/{identity_id}/wait", params={
  "timeout": "30"
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=60)
print(response.json())
```

**Response** `200`

```json
{
  "timedOut": false,
  "message": {
    "id": "Qm8wZ1kX0pLr7aYtV3nBc",
    "from": "noreply@github.com",
    "subject": "Your GitHub launch code",
    "snippet": "Here is your GitHub launch code: 482913",
    "receivedAt": "2026-11-19T10:02:11.000Z"
  }
}
```

### Get the code sent to an identity

`GET /v1/identities/{id}/code` (scope `messages:read`)

The first verification code or magic link in the identity's mail, waiting up to `timeout` seconds for one. `from` filters by sender on the server; a `pattern` parameter is ignored here (a caller's regular expression could take too long).

**Path parameters**

| Name | Description |
|---|---|
| `id` | The identitie id. |

**Query parameters**

| Name | Type | Required | Description |
|---|---|---|---|
| `timeout` | integer | no | Seconds to wait, capped by the plan. Default `0`. 0 to 300. |
| `from` | string | no | Only messages whose sender address contains this text. |

```bash cURL
curl "https://api.dissolve.email/v1/identities/$IDENTITY_ID/code?timeout=30" \
  -H "Authorization: Bearer $DISSOLVE_API_KEY"
```

```ts TypeScript
import { Dissolve } from '@dissolve-email/sdk';

const client = new Dissolve(); // reads DISSOLVE_API_KEY
const result = await client.v1.waitForIdentityCode(identityId, { timeout: 30 });
```

```bash CLI
dna verify "$IDENTITY_ID" --timeout 30 --quiet
```

```python Python
import os, requests

API_KEY = os.environ["DISSOLVE_API_KEY"]
response = requests.get(f"https://api.dissolve.email/v1/identities/{identity_id}/code", params={
  "timeout": "30"
}, headers={"Authorization": f"Bearer {API_KEY}"}, timeout=60)
print(response.json())
```

**Response** `200`

```json
{
  "found": true,
  "type": "code",
  "value": "482913",
  "confidence": 0.95,
  "source": {
    "messageId": "Qm8wZ1kX0pLr7aYtV3nBc",
    "from": "noreply@github.com",
    "subject": "Your GitHub launch code"
  },
  "rawMatches": [
    {
      "type": "code",
      "value": "482913",
      "confidence": 0.95
    }
  ]
}
```
