Peeker Partner API

Use POST /swaps/user_names to replace the mailbox personas on one active domain. Peeker uses the persona names to regenerate mailbox identities. The domain, order, and workspace target stay in place. For replacing the domain itself, see Domain swaps / How swaps work.

Submit the new personas

curl -X POST "https://api.peeker.ai/partner/v1/swaps/user_names" \
  -H "Authorization: Bearer pk_test_<your-key>" \
  -H "Content-Type: application/json" \
  --data '
{
  "domain_id": "dom_01HZX0D01A2B3C4D5E6F7G8H",
  "personas": [
    {
      "first_name": "Jordan",
      "last_name": "Pham"
    },
    {
      "first_name": "Riley",
      "last_name": "Wu"
    }
  ]
}'

Only first_name and last_name are required. profile_picture_url is optional and is not applied to inboxes today. The response contains the swap job created for the domain:

{
	"data": {
		"swaps": [
			{
				"id": "swp_01HZX0SW2A2B3C4D5E6F7G8H",
				"type": "user_names",
				"domain_id": "dom_01HZX0D01A2B3C4D5E6F7G8H",
				"replacement_domain": null,
				"status": "created",
				"created_at": "2026-05-08T12:00:00Z"
			}
		]
	}
}

Track the rename

Poll GET /swaps/{id} or subscribe to swap.created, swap.in_progress, swap.completed, and swap.failed.

created → in_progress → completed
                     ↘ failed

To replace the domain itself, use Replace a domain.

​Submit the new personas

​Track the rename

Submit the new personas

Track the rename