---
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`

## Request

- Base URL: `https://api.gusto-demo.com`
- URL: `https://api.gusto-demo.com/v1/partner_managed_companies/{company_uuid}/migrate`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/gusto/apis/gusto-api/docs/v1/partner_managed_companies/:company_uuid/migrate/put.ts> (a function with typed inputs; its response is checked against the schema)

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](doc:oauth2)
2. The customer must view and [accept the Embedded Payroll Terms of Service](ref:post-partner-managed-companies-company_uuid-accept_terms_of_service)

### Related guides
- [Migrate an existing company](doc: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.dev/gusto/apis/gusto-api.md) - [All operations](https://skmtc.dev/gusto/apis/gusto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gusto/apis/gusto-api/revisions/f98575fa2a5e?raw)