Skip to main content
POST
/
identities
cURL
curl --request POST \
  --url https://api.useanima.sh/v1/identities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "capabilities": [],
  "slug": "<string>",
  "email": "jsmith@example.com",
  "phone": {
    "countryCode": "US",
    "areaCode": "<string>"
  },
  "metadata": {}
}
'
{
  "id": "<string>",
  "name": "<string>",
  "slug": "<string>",
  "apiKey": "<string>",
  "email": {
    "id": "<string>",
    "email": "<string>",
    "domain": "<string>",
    "isPrimary": true
  },
  "phone": {
    "id": "<string>",
    "phoneNumber": "<string>",
    "provider": "<string>",
    "capabilities": {
      "sms": true,
      "mms": true,
      "voice": true
    },
    "isPrimary": true
  },
  "vault": {
    "id": "<string>",
    "status": "<string>"
  },
  "failures": [
    {
      "error": "<string>"
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization
string
header
required

JWT Bearer token obtained from authentication. Pass as: Authorization: Bearer

Body

application/json

Provision a complete agent identity in a single call

name
string
required

Human-readable name for the agent (e.g. 'shopping-agent')

Required string length: 2 - 100
capabilities
enum<string>[]
required

Capabilities to provision. Email is always included.

Minimum array length: 1
Available options:
email,
phone,
vault
slug
string

URL-safe identifier. Auto-derived from name if omitted

Required string length: 2 - 64
Pattern: ^[a-z0-9-]+$
email
string<email>

Custom email address. Defaults to {slug}@agents.useanima.sh

phone
object

Phone provisioning options (only used if 'phone' is in capabilities)

metadata
object

Arbitrary key-value metadata

Response

200 - application/json

OK

Provisioned agent identity with all requested capabilities

id
string
required

Agent ID

name
string
required
slug
string
required
apiKey
string
required

Agent API key — only returned on creation

email
object | null
required

Email identity (always provisioned)

phone
object | null
required

Phone identity (if requested)

vault
object | null
required

Vault identity (if requested)

failures
object[]
required

Capabilities that failed to provision. Empty on full success.

createdAt
string<date-time>
required