# Transitioning from API v1.0 to API v2.0
Business Central API v2.0 includes some major changes from v1.0 to improve the experience. This article describes these changes and how to transition from v1.0 to v2.0.
## Schema version
API v2.0 schema version is always set to 2.0 to get the latest features in the Business Central OData stack.
## Key fields
In v1.0, following resources didn't use the SystemId as the primary key. Instead they used non-GUID keys or multipart keys.
 attachments
 cashFlowStatement
 customerSale
 defaultDimensions
 dimensionLines
 generalLedgerEntries
 generalLedgerEntryAttachments
 incomeStatement
 purchaseInvoiceLines
 retainedEarningsStatement
 salesCreditMemoLines
 salesInvoiceLines
 salesOrderLines
 salesQuoteLines
 trialBalance
 vendorPurchase
All multipart keys and non-GUID in v2.0 are replaced with unique GUID keys. API v2.0 entities can be retrieved with the SystemId. SystemId is immutable, platform-enforced, and indexed. This change improves auditing and API reading performance. It's also possible to create a new record and provide the SystemId in API v2.0.
## Nested objects
In API v1.0, some properties had complex types<../v1.0/resources/dynamics_complextypes>. These properties defined an ../../developer/properties/devenv-odataedmtype-property that can be assigned following values.
 POSTALADDRESS
 Collection(DIMENSION)
 ITEM-UOM
 DOCUMENTLINEOBJECTDETAILS
Complex properties allowed returning nested JSON object in the API response. In API v2.0, all complex properties are replaced with first-level properties or navigation properties. This change improves API performance significantly since complex fields were calculated in the runtime and added more compute time.
The change from complex property to first-level property can be seen in resources/dynamics_customer resource type. In API v1.0, property address used POSTALADDRESS.
Here's an example of the response from API v1.0 customer resource<../v1.0/api/dynamics_customer_get>. The address property can be seen as a complex property.
> NOTE
> The response objects shown here might be truncated for brevity. All of the properties will be returned from an actual call.
```json
{
  "id": "id-value",
  "number": "10000",
  "displayName": "Coho Winery",
  "type": "Company",
  "address": {
    "street": "192 Market Square",
    "city": "Atlanta",
    "state": "GA",
    "countryLetterCode": "US",
    "postalCode": "31772"
  }
}
```
Here's the first-level property replacement of the address property in an example response from API v2.0 customer resource<api/dynamics_customer_get>.
```json
{
    "id": "id-value",
    "number": "10000",
    "displayName": "Adatum Corporation",
    "type": "Company",
    "addressLine1": "192 Market Square",
    "addressLine2": "",
    "city": "Atlanta",
    "state": "GA",
    "country": "US",
    "postalCode": "31772",
}
```
The change from complex property to navigational property can be seen in resources/dynamics_item resource type. In API v1.0, property baseUnitOfMeasure used `ITEM-UOM`.
Here's an example of the response from API v1.0 item resource<../v1.0/api/dynamics_item_get>. The baseUnitOfMeasure property can be seen as a complex property.
> NOTE
> The response objects shown here may be truncated for brevity. All of the properties will be returned from an actual call.
```json
{
  "id": "id-value",
  "number": "1896-S",
  "displayName": "ATHENS Desk",
  "baseUnitOfMeasure": {
    "unitCode": "PCS",
    "unitName": "Piece",
    "symbol": "",
    "unitConversion": null
  }
}
```
There's no first-level property replacement of the baseUnitOfMeasure property in an example response from API v2.0 item resource<api/dynamics_item_get>. Instead, the new navigation property replacement unitOfMeasure represents data from related unitOfMesure<resources/dynamics_unitofmeasure> resource and might be optionally included in the response object. Navigation properties are included in the response object by `$expand` OData parameter.
```
GET businesscentralPrefix/companies({id})/items({id})?$expand=unitOfMeasure
```
```json
{
  "id": "id-value",
  "number": "1896-S",
  "displayName": "ATHENS Desk",
  "unitOfMeasure": {
    "id": "id-value",
    "code": "PCS",
    "displayName": "Piece",
    "internationalStandardCode": "EA",
    "symbol": ""
  }
}
```
All navigation properties are documented in API (v2.0) Documentation<../v2.0>.
## Relationship multiplicities
In API v1.0, API sub pages (navigational properties) were always considered as collections. Therefore, all navigational properties returned a JSON array. In API v2.0 following properties are marked as `Multiplicity = ZeroOrOne` meaning a one-to-one relation. These properties return a JSON object in API v2.0.
Resource|Property
resources/dynamics_contact|contact
resources/dynamics_contactinformation|contact
resources/dynamics_customer|agedAccountsReceivable
resources/dynamics_customer|customerFinancialDetails
resources/dynamics_customer|picture
resources/dynamics_employee|picture
resources/dynamics_item|generalProductPostingGroup
resources/dynamics_item|inventoryPostingGroup
resources/dynamics_item|picture
resources/dynamics_item|unitOfMeasure
resources/dynamics_purchaseinvoiceline|location
resources/dynamics_purchaseinvoice|pdfDocument
resources/dynamics_purchaseorderline|location
resources/dynamics_salescreditmemoline|location
resources/dynamics_salescreditmemo|pdfDocument
resources/dynamics_salesinvoiceline|location
resources/dynamics_salesinvoice|pdfDocument
resources/dynamics_salesorderline|location
resources/dynamics_salesquoteline|location
resources/dynamics_salesquote|pdfDocument
resources/dynamics_vendor|agedAccountsPayable
resources/dynamics_vendor|picture
## Enums
All properties that were of type option in API v1.0 are converted into enums for API v2.0. These properties were previously exposed as strings, instead now they're strongly typed. Enum values can be accessed from the metadata endpoint, also enum captions can be accessed from the entityDefinitions endpoint.
This change allows integration utilizing Business Central API v2.0 to determine available values for enum properties, for example displaying dropdown values to the end user.
## Related information
API (v2.0) documentation<../v2.0>
API (v1.0) documentation<../v1.0>
Tips for working with the APIs<../../developer/devenv-connect-apps-tips>
Enabling the APIs for Dynamics 365 Business Central<enabling-apis-for-dynamics-nav>
../../developer/devenv-develop-custom-api

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/api-reference/v2.0/transition-to-api-v2.0, 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. https://jonas-paprotka.de/docs/dev-itpro/api-reference/v2.0/transition-to-api-v2.0/
