identities

​

The persona

client.identities.create(body: IdentityCreate): Promise<Identity>
client.identities.list(query?: ListQuery): Promise<Page<Identity>>
client.identities.get(ref: string): Promise<Identity>
client.identities.update(ref: string, body: IdentityPatch): Promise<Identity>
client.identities.delete(ref: string): Promise<Deleted>

• create — POST /v1/identities. IdentityCreate is { name, description?, metadata? }. A persona is created empty; its endpoints are minted through their own routes.
• list — GET /v1/identities, cursor-paginated.
• get — GET /v1/identities/{ref}.
• update — PATCH /v1/identities/{ref}. IdentityPatch is every create field optional. The denormalised emails/phones/domains/connections arrays are read-only here.
• delete — DELETE /v1/identities/{ref}. Check agents first.

​

The grant

client.identities.attach(agentId: string, identity: string): Promise<Grant>
client.identities.detach(agentId: string, identityId: string): Promise<Grant>
client.identities.held(agentId: string): Promise<Page<Identity>>

• attach — POST /v1/agents/{id}/identities. Idempotent: re-attaching answers attached: true, created: false, so a provisioning script can re-run safely.
• detach — DELETE /v1/agents/{id}/identities/{identity_id}. The identity itself is untouched; running sessions are not interrupted.
• held — GET /v1/agents/{id}/identities: which personas may this agent wear.

​

agents

client.identities.agents(ref: string): Promise<Page<AgentRef>>

​

Endpoint reads

client.identities.inboxes(ref: string): Promise<Page<EmailInbox>>
client.identities.deleteInbox(ref: string, inboxId: string): Promise<Deleted>
client.identities.phones(ref: string): Promise<Page<PhoneNumber>>
client.identities.releasePhone(ref: string, phoneId: string): Promise<Deleted>
client.identities.messages(ref: string, query?: { channel?: "email" | "sms" }): Promise<Page<InboundMessage>>

• inboxes — GET /v1/identities/{ref}/emails.
• deleteInbox — DELETE /v1/identities/{ref}/emails/{inbox_id}.
• phones — GET /v1/identities/{ref}/phones.
• releasePhone — DELETE /v1/identities/{ref}/phones/{phone_id}. Irreversible at the carrier: the number goes back to the pool and cannot be reclaimed.
• messages — GET /v1/identities/{ref}/messages: everything that arrived for this persona, both channels unless channel names one.