> ## 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.

# Sync a workspace

> Asks Peeker to read this workspace's domains and mailboxes from the
sequencer again. Peeker also does this on its own schedule. Call it
when you changed mailboxes in the sequencer and need Peeker to see the
change now, for example after a domain import failed with
`in_sequencer_without_order`.

Returns `202` with the workspace. The sync runs in the background.
Poll `GET /workspaces/{id}` until `syncing` is `false`. Send no body
and no `Idempotency-Key`. Calling it again while a sync is running is
safe.

With a sandbox key the call returns `202` with `syncing: false`.
Peeker does not call the sequencer in sandbox.




## OpenAPI

````yaml /openapi.yaml post /workspaces/{id}/sync
openapi: 3.1.0
info:
  title: Peeker Partner API
  version: 1.0.0
  description: >
    White-label Peeker's email infrastructure: Google Workspace and Microsoft

    365 inboxes, deliverability monitoring, and self-healing domain swaps,

    from your own app. Create a provider workspace target, order licenses with
    imported or

    Peeker-managed domains, and Peeker's backend handles provisioning,

    DNS, forwarding, and lifecycle webhooks.


    Create a provider workspace target with `POST /workspaces`, then send its

    `wrk_...` ID to `POST /orders`. For Smartlead, create one main workspace,

    then add `client_id` to an order only when it should go to a client

    workspace. Omit it to order into the main workspace.


    ## Read first


    - **[Authentication](/authentication)**: bearer keys, live vs sandbox,
    request IDs.

    - **[Rate limits](/rate-limits)**: 600/min per environment, shared by all
    your keys, 429 backoff.

    - **[Webhooks](/webhooks)**: signed events and delivery rules.

    - **[Async jobs](/concepts/async-jobs)**: what to poll vs subscribe to.

    - **[Best practices](/best-practices)**: errors, paging, idempotency.


    ## Concepts


    - **[Orders](/concepts/orders)**: statuses, sizing, pending actions, cancel.

    - **[Domains](/concepts/domains)**: inventory, `usable_for`, import,
    forwarding.

    - **[Bundles](/concepts/bundles)**: saved templates and capacity.

    - **[Swaps](/concepts/swaps)**: standard vs premium, renames.


    ## Workflow guides


    - **[Provider ordering](/guides/provider-ordering)** — create a provider
    workspace target and order through it.

    - **[Buying domains & ordering](/guides/buying-domains)** — the default
    flow: bundle, availability, order, webhooks.

    - **[Importing domains](/guides/importing-domains)** — bring in existing
    customer domains.

    - **[Forwarding](/guides/forwarding)** — point a domain at a marketing site.

    - **[How to implement domain swaps](/guides/domain-swaps)** — standard vs
    premium swaps.

    - **[Renaming inbox senders](/guides/user-name-swaps)** — change mailbox
    personas on a warm domain.


    ## Public ID prefixes


    | Prefix | Resource |

    | --- | --- |

    | `cus_` | Customer tracking record |

    | `wrk_` | Provider workspace |

    | `bun_` | Bundle |

    | `ord_` | Order |

    | `dom_` | Domain |

    | `pcl_` | Pool reservation |

    | `prp_` | Pool replacement |

    | `prl_` | Pool release |

    | `imp_` | Domain import job |

    | `fwj_` | Domain forwarding job |

    | `brj_` | Burned-domain replacement job |

    | `swp_` | Domain swap |

    | `act_` | Pending action |

    | `evt_` | Webhook event |
servers:
  - url: https://api.peeker.ai/partner/v1
    description: >-
      Same base URL for live and sandbox. The key prefix (`pk_live_…` /
      `pk_test_…`) picks the environment.
security:
  - BearerAuth: []
tags:
  - name: Account
    x-group: Account
    description: >
      Confirm an API key with `GET /me`. Returns environment (live or sandbox),

      permission preset, and the partner profile. See
      [Authentication](/authentication).
  - name: Provider workspaces
    x-group: Provider workspaces
    description: |
      A provider workspace is one reusable provider connection. Create it once,
      keep the returned `wrk_...` ID, and use it in orders and pool attach.
      Optional customer tracking stays on the target. Provider credentials stay
      internal and are never echoed.

      EmailBison requires a workspace API-user key. Super-admin keys are
      rejected. Instantly and Smartlead connections require `api_key`.
      Smartlead workspace creation takes a main API key and a label. Do not send
      `client_id` or customer data. Its login email and password are optional,
      but must be sent together. Google orders do not need the pair, and orders
      never accept it. Smartlead Microsoft orders and pool attach still use the
      workspace-saved pair. Add
      `client_id` to the order destination when the order belongs to a client
      workspace; omit it for the main workspace.
      PlusVibe setup requires `api_key` and the remote `workspace_id`. PlusVibe
      orders and pool attach use that API key and need no login. Its login
      email and password are optional, but must be sent together. Instantly
      login credentials belong on an order destination.
  - name: Bundles
    x-group: Bundles
    description: |
      Saved order template sized by monthly sending volume (`bun_…`). Pass
      `bundle_id` on an order instead of custom license counts.

      Lifecycle: [How bundles work](/concepts/bundles).
  - name: Domains
    x-group: Domains
    description: >
      Sending domains in your partner account (`dom_…`). Same ID whether or not

      the domain is on an order.


      **Status values**


      | Value | What it means |

      | --- | --- |

      | `available` | The domain is in inventory but not on an order yet. |

      | `in_progress` | We're setting it up. |

      | `active` | Live and warming or healthy. |

      | `failed` | Something broke that we can't fix automatically. |

      | `action_required` | We need your help (e.g. update nameservers). |


      **Inventory vs connected**


      - `category=inventory` — yours but not on any order. Inventory rows
        don't include `provider`.
      - `category=connected` — on an active order. The row carries the link
        fields `provider`, `customer_id`, `order_id`, `usable_for`, and
        `forwarding_url`.

      **`usable_for` matrix**


      When you check a domain's availability:


      | Who's on the domain | `usable_for` |

      | --- | --- |

      | Nobody, or just Google | `["google", "microsoft"]` |

      | Microsoft (or both) | `["google"]` |

      | Premium / invalid / errored | not orderable; `available: false` with a
      `reason` |


      **Imports and forwarding are jobs**


      Both **import** and **forwarding** are async jobs. Posting to those

      endpoints starts the job and gives you back a row with `status:

      "in_progress"`. Poll the job's GET endpoint to see when it finishes:


      - Import jobs: prefix `imp_…`. Includes the `nameserver_groups` your
        customer needs to set at their registrar.
        - Forwarding jobs: prefix `fwj_…`. Already-correct domains are
          returned in `completed` with newly updated domains.
  - name: Domain pool
    x-group: Domain pool
    description: |
      Assign an exact quantity from pre-warmed Google inventory. Each domain
      needs at least one active Google inbox on a paid Google order (commonly
      two), complete provider mailbox identity, and no explicit burned provider
      result. Attach is all-or-nothing: full quantity or
      `insufficient_inventory` with no pool change. Attach and release are
      async. Poll the resource or subscribe to `pool.*` webhooks.

      Guide: [Pre-warmed pool](/guides/pre-warmed-pool).
  - name: Prewarmed inboxes
    x-group: Prewarmed inboxes
    description: |
      Buy domains whose inboxes Peeker has already warmed. List live stock
      with `GET /prewarmed`, then buy exact domains with
      `POST /prewarmed/purchase`. Each purchase is a normal order (`ord_…`):
      follow it with `GET /orders/{id}` and find it in `GET /orders`.

      Guide: [Prewarmed inboxes](/guides/prewarmed-inboxes).
  - name: Orders
    x-group: Orders
    description: |
      One purchase of domains plus Google and/or Microsoft licenses for one
      customer (`ord_…`). Use a saved `bundle_id` **or** custom license counts,
      never both. Requires `Idempotency-Key`.

      Lifecycle: [How orders work](/concepts/orders).
  - name: Domain swaps
    x-group: Domain swaps
    description: |
      Replace a domain inside an existing order without losing the order
      (`swp_…`). For persona-only changes use `POST /swaps/user_names`.

      Statuses and standard vs premium: [How swaps work](/concepts/swaps).
  - name: Webhooks
    x-group: Webhooks
    description: |
      Signed JSON POSTs for orders, domains, imports, forwarding, pool, and
      swaps. Register the URL and secret in the
      [Partner portal](https://app.peeker.ai/partner/webhooks). Event IDs look
      like `evt_01HZX`.

      Delivery is at least once (up to 5 attempts). Verify `Peeker-Signature`
      and dedupe `Peeker-Event-Id` for at least 24 hours.

      Full catalog: [Webhooks](/webhooks).
paths:
  /workspaces/{id}/sync:
    parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          pattern: ^wrk_
        description: Public provider routing target ID.
    post:
      tags:
        - Provider workspaces
      summary: Sync a workspace
      description: |
        Asks Peeker to read this workspace's domains and mailboxes from the
        sequencer again. Peeker also does this on its own schedule. Call it
        when you changed mailboxes in the sequencer and need Peeker to see the
        change now, for example after a domain import failed with
        `in_sequencer_without_order`.

        Returns `202` with the workspace. The sync runs in the background.
        Poll `GET /workspaces/{id}` until `syncing` is `false`. Send no body
        and no `Idempotency-Key`. Calling it again while a sync is running is
        safe.

        With a sandbox key the call returns `202` with `syncing: false`.
        Peeker does not call the sequencer in sandbox.
      operationId: syncProviderWorkspaceV1
      responses:
        '202':
          description: Sync accepted. `syncing` stays `true` until it finishes.
          headers:
            Peeker-Request-Id:
              $ref: '#/components/headers/PeekerRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceEnvelope'
              example:
                data:
                  workspace_id: wrk_01HZX0PV1A2B3C4D5E6F7G8H
                  name: Acme PlusVibe
                  provider: plusvibe
                  provider_workspace_id: 692577ed8543f416f83ad252
                  status: active
                  syncing: true
                  last_synced_at: '2026-07-09T12:05:00.000Z'
                  created_at: '2026-07-09T12:00:00.000Z'
                  updated_at: '2026-07-09T12:00:00.000Z'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            Peeker cannot sync this workspace (`workspace_sync_unavailable`).
            `error.details.reason` says why.
          headers:
            Peeker-Request-Id:
              $ref: '#/components/headers/PeekerRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  headers:
    PeekerRequestId:
      description: Stable request identifier. Log it with the status and response body.
      schema:
        type: string
        example: 550e8400-e29b-41d4-a716-446655440000
  schemas:
    WorkspaceEnvelope:
      type: object
      additionalProperties: false
      required:
        - data
      properties:
        data:
          $ref: '#/components/schemas/Workspace'
      example:
        data:
          workspace_id: wrk_01HZX0PV1A2B3C4D5E6F7G8H
          name: Acme PlusVibe
          provider: plusvibe
          provider_workspace_id: 692577ed8543f416f83ad252
          status: active
          syncing: false
          last_synced_at: '2026-07-09T12:05:00.000Z'
          created_at: '2026-07-09T12:00:00.000Z'
          updated_at: '2026-07-09T12:00:00.000Z'
    ErrorEnvelope:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: object
          additionalProperties: false
          required:
            - code
            - message
            - request_id
          properties:
            code:
              type: string
              description: Stable machine-readable code. Branch on this field.
              enum:
                - invalid_request
                - unauthorized
                - forbidden
                - not_found
                - rate_limited
                - provider_not_supported
                - provider_mismatch
                - provider_credentials_invalid
                - provider_login_credentials_required
                - provider_unavailable
                - emailbison_super_admin_key
                - smartlead_connection_required
                - smartlead_client_id_required
                - smartlead_client_not_found
                - idempotency_key_required
                - idempotency_conflict
                - idempotency_in_progress
                - workspace_promotion_required
                - workspace_credentials_conflict
                - workspace_sync_unavailable
                - order_shape_conflict
                - domain_count_mismatch
                - insufficient_inventory
                - domain_not_imported
                - domains_not_submittable
                - premium_domain_not_supported
                - domain_not_usable_for_provider
                - domain_already_in_active_order
                - internal_error
              example: emailbison_super_admin_key
            message:
              type: string
              description: Human-readable explanation. Wording may change.
              example: >-
                Use an EmailBison workspace/user API key; super-admin keys are
                not accepted.
            request_id:
              type: string
              description: >-
                Stable request identifier, identical to the `Peeker-Request-Id`
                response header.
              example: 550e8400-e29b-41d4-a716-446655440000
            field:
              type: string
              description: Dot path to the invalid request property, when applicable.
              example: credentials.api_key
            details:
              type: object
              additionalProperties: true
              description: Structured context specific to `error.code`.
    Workspace:
      type: object
      required:
        - workspace_id
        - name
        - provider
        - provider_workspace_id
        - status
        - created_at
        - updated_at
      properties:
        workspace_id:
          type: string
          pattern: ^wrk_
          description: Peeker workspace target ID (`wrk_…`) for orders and pool attach.
          example: wrk_01HZX0WK1A2B3C4D5E6F7G8H
        name:
          type: string
          example: Acme PlusVibe
        provider:
          type: string
          enum:
            - emailbison
            - instantly
            - smartlead
            - plusvibe
          example: plusvibe
        provider_workspace_id:
          type: string
          description: Remote workspace ID from the provider (not Peeker’s `wrk_…`).
          example: 692577ed8543f416f83ad252
        client_id:
          type: string
          pattern: ^[1-9][0-9]*$
          description: Present when this target routes to a Smartlead client.
          example: '366903'
        label:
          type: string
          description: >-
            Optional label owned by this workspace target. Omitted when no label
            was supplied.
          example: Agency Smartlead
        customer:
          $ref: '#/components/schemas/WorkspaceCustomer'
        status:
          type: string
          enum:
            - active
            - disconnected
          example: active
        syncing:
          type: boolean
          description: >-
            `true` from `POST /workspaces/{id}/sync` until a sync that began
            after that request has finished. Poll until it is `false`.
          example: false
        last_synced_at:
          type: string
          format: date-time
          nullable: true
          description: >-
            Peeker's copy of this workspace's domains and mailboxes matches the
            sequencer as of this time. `null` before the first sync finishes.
          example: '2026-07-09T12:05:00.000Z'
        created_at:
          type: string
          format: date-time
          example: '2026-07-09T12:00:00.000Z'
        updated_at:
          type: string
          format: date-time
          example: '2026-07-09T12:00:00.000Z'
    WorkspaceCustomer:
      type: object
      additionalProperties: false
      required:
        - customer_id
        - reference
        - status
      properties:
        customer_id:
          type: string
          pattern: ^cus_
          description: >-
            Stable Peeker ID for filtering orders, domains, pending actions, and
            swaps.
          example: cus_01HZX0C6Z3K4M5N6P7Q8R9S0
        reference:
          type: string
          description: Partner-owned customer or account identifier.
          example: customer-42
        name:
          type: string
          example: Acme
        email:
          type: string
          format: email
          example: ops@acme.com
        status:
          type: string
          enum:
            - active
            - archived
          example: active
  responses:
    Unauthorized:
      description: Missing, invalid, or revoked API key.
      headers:
        Peeker-Request-Id:
          $ref: '#/components/headers/PeekerRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    Forbidden:
      description: Valid key, but it doesn’t allow this action.
      headers:
        Peeker-Request-Id:
          $ref: '#/components/headers/PeekerRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    NotFound:
      description: >-
        A referenced workspace, customer, bundle, domain, or order was not
        found.
      headers:
        Peeker-Request-Id:
          $ref: '#/components/headers/PeekerRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    RateLimited:
      description: >-
        Too many requests. Wait `Retry-After` seconds (also in
        `error.details.retry_after_seconds`), then retry.
      headers:
        Retry-After:
          description: Seconds to wait before retrying; capacity is not reserved.
          schema:
            type: integer
            minimum: 1
        Peeker-Request-Id:
          $ref: '#/components/headers/PeekerRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
    InternalError:
      description: Unexpected server error. Retry with backoff and keep the request ID.
      headers:
        Peeker-Request-Id:
          $ref: '#/components/headers/PeekerRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorEnvelope'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        Partner API key (`pk_live_…` or `pk_test_…`).
      x-default: Bearer pk_test_<your-test-key>

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.