---
title: "Migrate company to embedded payroll"
method: PUT
path: "/v1/partner_managed_companies/{company_uuid}/migrate"
tags: ["Companies"]
---

# Migrate company to embedded payroll

`PUT /v1/partner_managed_companies/{company_uuid}/migrate`

Migrate an existing Gusto customer to your embedded payroll product.

### Prerequisites
Before calling this endpoint:
1. The customer must connect their Gusto account to your application using [OAuth2](https://docs.gusto.com/embedded-payroll/docs/oauth2)
2. The customer must view and [accept the Embedded Payroll Terms of Service](https://docs.gusto.com/embedded-payroll/reference/post-partner-managed-companies-company_uuid-accept_terms_of_service)

### Related guides
- [Migrate an existing company](https://docs.gusto.com/embedded-payroll/docs/migrate-existing-company)

scope: `partner_managed_companies:write`

## Path parameters

- `company_uuid` string, required

## Headers

- `X-Gusto-API-Version` '2026-06-15'

## Request body

- PartnerManagedCompanyMigrateRequest — Request body is optional in API version 2026-02-01 and later. The Terms of Service signer is resolved from the authenticated payroll-admin user; the previously required `email`, `ip_address`, and `external_user_id` parameters are no longer accepted.

## Response `200`

Success

- PartnerManagedCompanyMigrateResponse
  - `company_uuid` string — The company UUID.
  - `migration_status` boolean — Returns `true` when the migration completed successfully, `false` otherwise.
  - `errors` object[] — Migration blockers preventing the migration. Empty array when `migration_status` is `true`.
    - `error_key` string
    - `category` 'migration_blocker' — Returns `migration_blocker` for blockers.
    - `message` string
    - `metadata` object
      - `key` string — Issue key (e.g., `company_suspended`, `terms_of_service`, `gusto_managed_benefits`).
  - `warnings` object[] — Non-blocking issues surfaced during migration (e.g., suspended company, active integrations). May be present even when `migration_status` is `true`.
    - `error_key` string
    - `category` 'migration_warning' — Returns `migration_warning` for warnings.
    - `message` string
    - `metadata` object
      - `key` string

## Other responses

- `404` — Not Found The requested resource does not exist. Make sure the provided UUID is valid.
- `422` — Unprocessable Entity This may happen when the body of your request contains errors such as `invalid_attribute_value`, or the request fails due to an `invalid_operation`. See the [Errors Categories](https://docs.gusto.com/embedded-payroll/docs/error-categories) guide for more details.

---

[API](https://skmtc.net/gusto/apis/gusto-api.md) · [All operations](https://skmtc.net/gusto/apis/gusto-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/gusto/gusto-api/revisions/826dfa57fb3b/schema)