> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peeker.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Changing user names on active orders

> Rename the First Name, Last Name, or email username (for example, name@domain.com -> fnamelname@domain.com) on an active order domain. The domain stays; only the inbox names change.

Different from a domain swap - here the **domain stays**, but the first name, last name, or email username we use on the inbox changes. Use it when:

* A customer rotates the team that sends from a domain (Alex/Sam left, Jordan/Riley take over).
* A customer rebrands and wants different display names on warmup-aged inboxes.
* The user's names are wrong, or the generated email username needs a clean fix.

The result: each inbox on the domain gets a new first/last name, optional profile picture, and email username when needed. Warmup history stays intact.

To replace the *domain itself*, use [How to implement domain swaps](/guides/domain-swaps) instead.

## Steps in detail

<AccordionGroup>
  <Accordion title="1. Submit the new name list" defaultOpen>
    `POST /swaps/user_names` takes the existing `domain_id` and a `personas[]` list. The response is a batch of `swp_…` rows - one per inbox being renamed - each with the same `swap.*` event lifecycle as a domain swap. The number of rows in the response equals the number of inboxes on the domain (not the number of `personas[]` entries you sent).

    ```bash cURL theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
    curl -X POST "https://api.peeker.ai/partner/v1/swaps/user_names" \
      -H "Authorization: Bearer pk_test_<your-key>" \
      -H 'Content-Type: application/json' \
      -d '{
        "domain_id": "dom_01HZX0D01…",
        "personas": [
          { "first_name": "Jordan", "last_name": "Pham", "profile_picture_url": "https://cdn.acme.com/jordan.jpg" },
          { "first_name": "Riley",  "last_name": "Wu",   "profile_picture_url": "https://cdn.acme.com/riley.jpg"  }
        ]
      }'
    ```

    ```json 201 Created theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
    {
    	"data": {
    		"swaps": [
    			{
    				"id": "swp_01HZX0SW2…",
    				"type": "user_names",
    				"domain_id": "dom_01HZX0D01…",
    				"replacement_domain": null,
    				"status": "created",
    				"created_at": "2026-05-08T12:00:00Z"
    			},
    			{
    				"id": "swp_01HZX0SW3…",
    				"type": "user_names",
    				"domain_id": "dom_01HZX0D01…",
    				"replacement_domain": null,
    				"status": "created",
    				"created_at": "2026-05-08T12:00:00Z"
    			}
    		]
    	}
    }
    ```
  </Accordion>

  <Accordion title="2. Profile pictures">
    Every persona includes the `profile_picture_url` key. Use a public URL, `null`, or `""`. A private
    or local URL triggers `swap.action_required` with `profile_picture_not_accessible`. See [Best
    practices → Pending actions](/best-practices#6-handling-pending-actions).
  </Accordion>

  <Accordion title="3. Track each rename">
    Poll `GET /swaps/{id}` for any `swp_…` row, or listen for its `swap.*` webhooks. Each row moves through:

    ```bash cURL theme={"theme":{"light":"one-light","dark":"one-dark-pro"}}
    curl -X GET "https://api.peeker.ai/partner/v1/swaps/swp_01HZX0SW…" \
      -H "Authorization: Bearer pk_test_<your-key>"
    ```

    ```
    created  →  in_progress  →  completed
                           ↘  failed
                           ↘  action_required
    ```

    A batch can have some rows complete while others stall on profile-picture issues. Resolve those one inbox at a time.
  </Accordion>

  <Accordion title="4. What stays intact">
    * The domain itself - DNS, MX records, Cloudflare zone, registrar.
    * Warmup history on each inbox - the inbox's reputation isn't reset by the rename.
    * The order, the workspace, and the customer's link to both.

    What changes:

    * Display name on outgoing mail.
    * The local-part of the inbox address (e.g. `alex@…` → `jordan@…`) only if the rename changes which local-part Peeker generates. Most renames change the display only.
  </Accordion>
</AccordionGroup>

## What's next

<CardGroup cols={2}>
  <Card title="How to implement domain swaps" href="/guides/domain-swaps">
    Replace the domain itself, not just the people on it.
  </Card>

  <Card title="Best practices" href="/best-practices">
    Pending actions, webhook hygiene, idempotent retries.
  </Card>
</CardGroup>