Dashboard →
Reference

API Reference

Base URL: https://humiris.com/api

All requests must include Authorization: Bearer YOUR_API_KEY

Agents

GET/agents

List all agents in your account.

Response
{ "success": true, "data": [{ "id": "agt_...", "name": "alex-sdr", "status": "active" }] }
POST/agents

Create a new identity. A unique managed @humiris.com email address is created by default.

Parameters
namestringrequiredUnique slug identifier (e.g. alex-sdr)
persona.firstNamestringAgent first name
persona.lastNamestringAgent last name
persona.jobTitlestringJob title shown in signatures
persona.tonestringprofessional | casual | friendly
identity.emailbooleanCreate managed email; defaults to true
Response
{
  "success": true,
  "data": {
    "id": "agt_01hx3m...",
    "name": "alex-sdr",
    "status": "active",
    "emailAddresses": [
      { "fullAddress": "alex-sdr@humiris.com", "isPrimary": true }
    ]
  }
}
GET/agents/:id

Get a single agent with all provisioned resources.

Response
{ "success": true, "data": { "id": "agt_...", "persona": {...}, "emailAddresses": [...], "phone": {...}, "wallet": {...} } }
DELETE/agents/:id

Delete an agent and release all associated resources.

Response
{ "success": true }

Email

POST/agents/:id/email

Assign an additional address from a verified workspace domain. New identities already receive a managed address.

Parameters
addressstringrequiredFull email address (e.g. alex@example.com)
typestringdedicated | shared (default: dedicated)
Response
{ "success": true, "data": { "fullAddress": "alex@example.com", "isPrimary": false } }
GET/agents/:id/email

List all email addresses for the agent.

Response
{ "success": true, "data": [{ "fullAddress": "alex-sdr@humiris.com", "isPrimary": true }] }
GET/agents/:id/email/inbox?unread=true&limit=50

List received messages. The response includes unread count, plain-text previews, attachment metadata, and extracted HTTP(S) links. No link is opened.

Response
{
  "success": true,
  "data": {
    "unreadCount": 1,
    "receivingConfigured": true,
    "messages": [{
      "id": "msg_...",
      "from": "accounts@example.com",
      "subject": "Confirm your account",
      "preview": "Use the link below...",
      "isRead": false,
      "links": [{
        "url": "https://example.com/confirm?...",
        "host": "example.com",
        "likelyConfirmation": true
      }]
    }]
  }
}
GET/agents/:id/email/inbox/:messageId

Read one received message. Returns plain text and link metadata; HTML is not rendered or returned to clients.

Response
{ "success": true, "data": { "id": "msg_...", "text": "Full plain-text body", "links": [...] } }
PATCH/agents/:id/email/inbox/:messageId

Mark one received message read or unread.

Parameters
isReadbooleanrequiredtrue marks read; false marks unread
Response
{ "success": true, "data": { "id": "msg_...", "isRead": true, "readAt": "2026-07-29T..." } }
POST/agents/:id/email/send

Send outbound email from the agent's primary address. This is an external side effect.

Parameters
tostringrequiredRecipient email address
subjectstringrequiredEmail subject
messagestringrequiredPlain-text body; use html instead for HTML email
Response
{ "success": true, "data": { "id": "email_...", "from": "alex-sdr@humiris.com", "to": "recipient@example.com" } }

Phone

POST/agents/:id/phone

Create a non-operational sandbox phone record for interface testing.

Parameters
countrystringCountry code: US (default), GB, CA, AU
Response
{ "success": true, "data": { "number": "+1 (...) ...", "country": "US", "mode": "sandbox", "operational": false }, "warning": "Sandbox number only..." }
DELETE/agents/:id/phone

Delete the agent's sandbox phone record.

Response
{ "success": true }

Wallet

POST/agents/:id/wallet

Create a non-operational sandbox wallet record. Never send funds to it.

Parameters
chainstringrequiredethereum | solana | polygon | base
Response
{ "success": true, "data": { "address": "0x...", "chain": "ethereum", "mode": "sandbox", "operational": false }, "warning": "Sandbox wallet only..." }