{"title":"Cloud Migration APIs overview (v1.0)","url":"https://jonas-paprotka.de/docs/dev-itpro/administration/cloudmigrationapi/cloud-migration-api-overview/","by":"JOP-AL","license":"Copyright (c) Microsoft Corporation. CC BY 4.0, https://creativecommons.org/licenses/by/4.0/; code samples MIT. From https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/cloudmigrationapi/cloud-migration-api-overview, MicrosoftDocs/dynamics365smb-devitpro-pb at 828b6ee (2026-11-19). Changed: includes filled in, links to this site, and for agents shortened without dropping a fact.","credit":"Microsoft Corporation, CC BY 4.0","origin":"https://learn.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/cloudmigrationapi/cloud-migration-api-overview","source":{"name":"Business Central developer and IT pro docs","repo":"https://github.com/MicrosoftDocs/dynamics365smb-devitpro-pb","commit":"828b6ee72fcd75755627cd6011f3d20899217ab2","date":"2026-11-19"},"checked":"2026-11-19","description":"Learn how to use Cloud Migration APIs to automate the cloud migration process end-to-end.","date":"2024-05-31","meta":{"topic":"overview"},"outline":[{"level":1,"title":"Cloud Migration APIs overview (v1.0)","slug":"cloud-migration-apis-overview-v10","at":0,"chars":6680},{"level":2,"title":"Set up cloud migration","slug":"set-up-cloud-migration","at":524,"chars":2432},{"level":2,"title":"Cloud migration - create companies","slug":"cloud-migration---create-companies","at":2956,"chars":1540},{"level":2,"title":"Cloud migration status","slug":"cloud-migration-status","at":4496,"chars":2108},{"level":2,"title":"Related information","slug":"related-information","at":6604,"chars":76}],"text":"# Cloud Migration APIs overview (v1.0)\n> APPLIES TO: Business Central 2022 release wave 1 and later\nCloud Migration APIs provide capability for automating the cloud migration process end-to-end by using APIs. You will be able to complete the setup, move the data, and track the progress, trigger upgrade if needed and switch off the cloud migration.\nThe main endpoint for the API is:\n`https://api.businesscentral.dynamics.com/v2.0/79dbd222-0f30-42a6-9f25-3164d21b269a/Production/api/microsoft/cloudMigration/v1.0/companies`\n## Set up cloud migration\nTo create the set up you can issue a POST request, if it is a first setup, otherwise use a PATCH request. Issue the request against the following endpoint:\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/setupCloudMigration\nAuthorization: Bearer {token}\nContent-type: application/json\n\nBody:\n{\n   \"productId\":\"{ProductID}\",\n   \"sqlServerType\":\"{SqlServerType}\",\n   \"sqlConnectionString\":\"{SqlConnectionString}\"\n}\n```\nIn the JSON example above, productId can be one of following values:\n DynamicsBCLast - use for cloud migration with upgrade\n DynamicsBC - use for cloud migration from the same version of Business Central\n DynamicsGP - use if you are setting up a Dynamics GP cloud migration\nIn the JSON example above, sqlServerType can be one of the following values:\n SQLServer - Use if you are migrating from the database that is hosted on the On-Prem SQL server\n AzureSQL - If you have uploaded the database to migrate to Azure SQL server\nAnd the SqlConnectionString must be the SQL connection string to the database you want to migrate\nThe above request will return a payload like:\n```json\n{\n    \"id\":\"{SetupRecordId}\",\n   \"productId\":\"{ProductID}\",\n   \"sqlServerType\":\"{SqlServerType}\",\n   \"sqlConnectionString\":\"{SqlConnectionString}\"\n   \"runtimeName\":\"{RuntimeName}\",\n   \"runtimeKey\":\"{RuntimeKey}\"\n}\n```\nIf you are migrating from Azure SQL you can skip next step:\nIf you are migrating from SQLServer, you should take the runtimeKey value and install and connect Microsoft Integration Runtime by using this key. Then you need to issue a PATCH request such as the following:\n```json\nPATCH  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/setupCloudMigration({SetupRecordId})\nAuthorization: Bearer {token}\nContent-type: application/json\nIf-Match: etag\nBody:\n{\n   \"productId\":\"{ProductID}\",\n   \"sqlServerType\":\"{SqlServerType}\",\n   \"sqlConnectionString\":\"{SqlConnectionString}\",\n    \"runtimeName\":\"{RuntimeName}\"\n}\n```\nTo complete the setup for both SQL and Azure SQL hosted databases invoke:\n```json\nPOST https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/setupCloudMigration({SetupRecordId})/ Microsoft.NAV.completeSetup\n\n```\n## Cloud migration - create companies\nTo create on-prem companies you can get the list first by issuing a request like this:\n```json\nGET https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationCompanies\nAuthorization: Bearer {token}\n\nThe response will be like this for each of the companies:\n  {\n      \"id\": \"{CompanyId}\",\n      \"name\": \"{CompanyName}\",\n      \"replicate\": false,\n      \"displayName\": \"{DislpayName}\",\n      \"estimatedSize\":{SizeOfComapny},\n      \"status\": \"\",\n      \"created\": false\n    }\n```\nTo include the company into the cloud migration you should issue following request:\n```http\nPATCH  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationCompanies ({CompanyId})\nAuthorization: Bearer {token}\nContent-type: application/json\nIf-Match: etag\n {\n      \"replicate\": true\n}\n```\nTo exclude the company, issue the same request with a false value.\nOnce the companies are marked for replication you can create them by running the following request:\n```http\nPOST  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationCompanies({AnyCompanyId}) /Microsoft.NAV.createCompaniesMarkedForReplication\n\nAuthorization: Bearer {token}\n```\nDELETE and POST are not allowed against this API; it is not possible to create or delete entities on this API.\n## Cloud migration status\nTo manage cloud migration or to track the status this API should be used:\n```json\nGET https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationStatus\nAuthorization: Bearer {token}\n```\nIt will return the following payload:\n```json\n{\n      \"id\": \"679c8aa5-16a9-ec11-80f1-002248334988\",\n      \"runId\": \"79090ce4-404d-4274-829a-a3b18e99006c\",\n      \"startTime\": \"2022-03-21T12:57:17Z\",\n      \"endTime\": \"2022-03-21T12:58:48.35Z\",\n      \"replicationType\": \"Normal\",\n      \"status\": \"Completed\",\n      \"source\": \"Dynamics 365 Business Central earlier versions\",\n      \"details\": \"Cloud migration setup completed.\",\n      \"tablesSuccessful\": 0,\n      \"tablesFailed\": 0,\n      \"tablesRemaining\": 0\n}\n```\nTo start the replication find the cloudMigrationStatus with last endTime and invoke the following command:\n```json\nPOST  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationStatus ({LastStatusId}) /Microsoft.NAV.runReplication\nAuthorization: Bearer {token}\n\n```\nTo refresh the status do the following request:\n```json\nPOST  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationStatus ({LastStatusId}) /Microsoft.NAV.refreshStatus\nAuthorization: Bearer {token}\n\n```\nTo trigger the data upgrade do the following request:\n```json\nPOST  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationStatus ({LastStatusId}) /Microsoft.NAV.runDataUpgrade\nAuthorization: Bearer {token}\n```\nTo disable the replication as the last step do the following request:\n```json\nPOST  https://api.businesscentral.dynamics.com/v2.0/{aadTenantID}/{environment name}/api/microsoft/cloudMigration/v1.0/companies({companyId})/cloudMigrationStatus ({LastStatusId}) /Microsoft.NAV.disableReplication\nAuthorization: Bearer {token}\n\n```\n## Related information\n../../api-reference/v2.0/endpoints-apis-for-dynamics."}