+> **Web API chains (On-Behalf-Of) is not supported by Azure AD B2C** - Many architectures include a web API that needs to call another downstream web API, both secured by Azure AD B2C. This scenario is common in clients that have a web API back end, which in turn calls another service. This chained web API scenario can be supported by using the OAuth 2.0 JWT Bearer Credential grant, otherwise known as the On-Behalf-Of flow. However, the On-Behalf-Of flow is not currently implemented in Azure AD B2C. Although On-Behalf-Of works for applications registered in Microsoft Entra ID, it does not work for applications registered in Azure AD B2C, regardless of the tenant (Microsoft Entra ID or Azure AD B2C) that is issuing the tokens.

+| Selfasserted | >=2.1.30 |

+| Unifiedssp | >=2.1.18 |

+| Multifactor | >=1.2.16 |

+- Learn how to [Configure CAPTCHA display control](display-control-captcha.md).

+- A Microsoft Entra account with the [Owner](../role-based-access-control/built-in-roles.md#owner) role in the Microsoft Entra subscription. See how to [Assign a user as an administrator of an Azure subscription](../role-based-access-control/role-assignments-portal-subscription-admin.yml).

+ 

+- Familiarize yourself with the Azure Static Web App [App Settings](../static-web-apps/application-settings.yml).

+Once the application is registered with Azure AD B2C, create the following application secrets in the Azure Static Web App's [application settings](../static-web-apps/application-settings.yml). You can configure application settings via the Azure portal or with the Azure CLI. For more information, check out the [Configure application settings for Azure Static Web Apps](../static-web-apps/application-settings.yml#configure-application-settings) article.

+1. Under **Manage**, select the **Authentication**, go to **Implicit grant and hybrid flows**, select the **ID tokens (used for implicit and hybrid flows)** checkbox.

+ 1. Name: `_dnsauth.login.contoso.com`, but you need to enter just `_dnsauth`.

+1. In the `ContosoCustomPolicy.XML` file, locate the `AAD-UserRead` technical profile and then add a new technical profile below it by using the following code:

+ Make sure you also add the `authenticationSource` claim in the output claims collection of the `UserSignInCollector` self-asserted technical profile.

+Azure AD B2C custom policy provides an OpenID Connect technical profile, which you use to make a call to a secure Microsoft endpoint. Learn more about [OpenID Connect technical profile](openid-connect-technical-profile.md).

+- Learn more about [OpenID Connect technical profile](openid-connect-technical-profile.md).

+ <ValidationTechnicalProfile ReferenceId="UserInputDisplayNameGenerator"/>

+You can configure a Microsoft Entra ID technical profile to update a user account instead of attempting to create a new one. To do so, set the Microsoft Entra ID technical profile to throw an error if the specified user account doesn't already exist in the metadata collection by using the following code. Also, remove the `Key="UserMessageIfClaimsPrincipalAlreadyExists` metadata entry. The *Operation* needs to be set to *Write*:

+ <Item Key="RaiseErrorIfClaimsPrincipalDoesNotExist">false</Item>

+| [Self-Service password reset](add-password-reset-policy.md) | GA| GA| Available in China cloud, but only for custom policies. |

+| [Force password reset](force-password-reset.md) | GA | GA | Available in China cloud, but only for custom policies. |

+| [Phone sign-up and sign-in](phone-authentication-user-flows.md) | GA | GA | Available in China cloud, but only for custom policies. |

+| [Conditional Access and Identity Protection](conditional-access-user-flow.md) | GA | GA | Not available for SAML applications. Limited CA features are available in China cloud. Identity Protection is not available in China cloud. |

+| [Multi-language support](localization.md)| GA | GA | Available in China cloud, but only for custom policies. |

+| [Custom domains](custom-domain.md)| GA | GA | Available in China cloud, but only for custom policies. |

+| [Page layout version](page-layout.md) | GA | GA | Available in China cloud, but only for custom policies. |

+| [JavaScript](javascript-and-page-layout.md) | GA | GA | Available in China cloud, but only for custom policies. |

+| [Password complexity](password-complexity.md) | GA | GA | Available in China cloud, but only for custom policies. |

+|[Apple](identity-provider-apple-id.md) | GA | GA | Available in China cloud, but only for custom policies. |

+|[WeChat](identity-provider-wechat.md) | Preview | GA | Available in China cloud, but only for custom policies. |

+| [Default SSO session provider](custom-policy-reference-sso.md#defaultssosessionprovider) | GA | Available in China cloud, but only for custom policies. |

+| [External login session provider](custom-policy-reference-sso.md#externalloginssosessionprovider) | GA | Available in China cloud, but only for custom policies. |

+| [SAML SSO session provider](custom-policy-reference-sso.md#samlssosessionprovider) | GA | Available in China cloud, but only for custom policies. |

+| [OAuth SSO Session Provider](custom-policy-reference-sso.md#oauthssosessionprovider) | GA| Available in China cloud, but only for custom policies. |

+| [Phone factor authentication](phone-factor-technical-profile.md) | GA | Available in China cloud, but only for custom policies. |

+1. Under **Settings** in the leftmost menu, select **Configuration**.

+1. Enable **Allow Blob anonymous access**.

+1. Select **Save**.

+1. Navigate to [www.test-cors.org](https://cors-test.codehappy.dev/)

+In this article, you learn how to create your web app that calls your web API. The web API needs to be protected by Azure Active Directory B2C (Azure AD B2C). To authorize access to the web API, you serve requests that include a valid access token that's issued by Azure AD B2C.

+This article describes ways you can customize and enhance the Azure Active Directory B2C (Azure AD B2C) authentication experience for your React single-page application (SPA). Before you start, familiarize yourself with the article [Configure authentication in a React SPA](configure-authentication-sample-react-spa-app.md) or [Enable authentication in your own React SPA](enable-authentication-react-spa-app.md).

+| `AADB2C99027` | Policy '{0}' does not contain an AuthorizationTechnicalProfile with a corresponding ClientAssertionType. | [Client credentials flow](client-credentials-grant-flow.md) |

+To enable sign-in for users with a LinkedIn account in Azure Active Directory B2C (Azure AD B2C), you need to create an application in [LinkedIn Developers website](https://developer.linkedin.com/). If you don't already have a LinkedIn account, you can sign up at [https://www.linkedin.com/](https://www.linkedin.com/).

+1. By default, your LinkedIn app isn't approved for scopes related to sign in. To request a review, select the **Products** tab, and then select **Sign In with LinkedIn using OpenID Connect**. When the review is complete, the required scopes will be added to your application.

+1. On the **Portal settings | Directories + subscriptions** page, find your Azure AD B2C directory in the **Directory name** list, and then select **Switch**.

+1. Select **Identity providers**, then select **New OpenID Connect provider**.

+1. Enter a **Name**. For example, *LinkedIn-OIDC*.

+1. For the **Metadata URL**, enter **https://www.linkedin.com/oauth/.well-known/openid-configuration**.

+1. For the **Scope**, enter **openid profile email**.

+1. For the **Response type**, enter **code**.

+1. For the **User ID**, enter **email**.

+1. For the **Display name**, enter **name**.

+1. For the **Given name**, enter **given_name**.

+1. For the **Surname**, enter **family_name**.

+1. For the **Email**, enter **email**.

+1. Under the **Custom identity providers**, select **LinkedIn-OIDC**.

+1. From the sign-up or sign-in page, select **LinkedIn-OIDC** to sign in with LinkedIn account.

+1. On the **Portal settings | Directories + subscriptions** page, find your Azure AD B2C directory in the **Directory name** list, and then select **Switch**.

+To enable users to sign in using a LinkedIn account, you need to define the account as a claims provider that Azure AD B2C can communicate with through an endpoint. The endpoint provides a set of claims that are used by Azure AD B2C to verify that a specific user has authenticated.

+ <DisplayName>LinkedIn-OIDC</DisplayName>

+ <TechnicalProfile Id="LinkedIn-OIDC">

+ <Protocol Name="OpenIdConnect" />

+ <Item Key="METADATA">https://www.linkedin.com/oauth/.well-known/openid-configuration</Item>

+ <Item Key="scope">openid profile email</Item>

+ <Item Key="HttpBinding">POST</Item>

+ <Item Key="response_types">code</Item>

+ <Item Key="UsePolicyInRedirectUri">false</Item>

+ <Item Key="client_id">Your LinkedIn application client ID</Item>

+ <Key Id="client_secret" StorageReferenceId="B2C_1A_LinkedInSecret" />

+ <OutputClaim ClaimTypeReferenceId="issuerUserId" PartnerClaimType="email" />

+ <OutputClaim ClaimTypeReferenceId="givenName" PartnerClaimType="given_name" />

+ <OutputClaim ClaimTypeReferenceId="surname" PartnerClaimType="family_name" />

+ <OutputClaim ClaimTypeReferenceId="identityProvider" DefaultValue="linkedin.com" AlwaysUseDefaultValue="true" />

+ <OutputClaim ClaimTypeReferenceId="authenticationSource" DefaultValue="socialIdpAuthentication" AlwaysUseDefaultValue="true" />

+ <OutputClaimsTransformation ReferenceId="CreateRandomUPNUserName" />

+ <OutputClaimsTransformation ReferenceId="CreateUserPrincipalName" />

+ <OutputClaimsTransformation ReferenceId="CreateAlternativeSecurityId" />

+ <OutputClaimsTransformation ReferenceId="CreateSubjectClaimFromAlternativeSecurityId" />

+ </TechnicalProfile>

+ <ClaimsExchange Id="LinkedInExchange" TechnicalProfileReferenceId="LinkedIn-OIDC" />

+1. From the sign-up or sign-in page, select **LinkedIn-OIDC** to sign in with LinkedIn account.

+Obtaining the email address from LinkedIn during sign-up is optional. If you choose not to obtain the email from LinkedIn but require one during sign-up, the user is required to manually enter the email address and validate it.

+The previously published sample code is not available at this time.

+<!--:::code language="csharp" source="~/ms-identity-dotnetcore-b2c-account-management/src/Program.cs" id="ms_docref_set_auth_provider":::-->

+The previously published sample code is not available at this time.

+<!--:::code language="csharp" source="~/ms-identity-dotnetcore-b2c-account-management/src/Services/UserService.cs" id="ms_docref_get_list_of_user_accounts":::-->

+**2.1.30**

+- Removed Change Email for readonly scenarios (i.e. Change Phone Number). You will no longer be able to change the email if you are trying to change your phone number, it will now be read only.

+- Implementation of Captcha Control

+

+**2.1.18**

+- Implementation of Captcha Control

+

+- Include Aria-required for UnifiedSSP (Accessibility).

+**1.2.16**

+- Fixes enter key for 'Phone only' mode.

+- Implementation to Captcha Control

+- Fixes `Enter` event trigger on MFA.

+- Fixes Multifactor tab navigation bug.

+- Removed `ReplaceAll` function for IE11 compatibility.

+|  is an identity verification and decentralized digital identity solution for Canadian citizens. It enables organizations to meet Identity Assurance Level (IAL) 2 and Know Your Customer (KYC) requirements. |

+|  is a document ID and facial biometrics verification solution that allows companies to meet *Know Your Customer* and identity requirements in real time. |

+|  is a passwordless, soft biometric, and MFA solution. Asignio uses a combination of the patented Asignio Signature and live facial verification for user authentication. The changeable biometric signature eliminates passwords, fraud, phishing, and credential reuse through omni-channel authentication. |

+|  is a passwordless authentication provider, which provides real-time consent-based services with biometric authentication like faceID and fingerprinting eliminating fraud and credential reuse. |

+|  is an Electronic Identification, Authentication and Trust Services (eiDAS) compliant digital ID solution to allow users to sign in securely without card readers, passwords, two-factor authentication, and multiple PIN codes. |

+|  is a digital ID solution that provides users with passwordless, secure, multifactor authentication. xID-authenticated users obtain their identities verified by a My Number Card, the digital ID card issued by the Japanese government. Organizations can get users verified personal information through the xID API. |

+|  is a fraud prevention solution provider that helps organizations protect against bot attacks, account takeover attacks, and fraudulent account openings. |

+ 

+Learn more: [Saviynt for Azure AD B2C](https://saviynt.com/fr/integrations/entra-id/for-b2c)

+ * See, [Saviynt for Azure AD B2C](https://saviynt.com/fr/integrations/entra-id/for-b2c)

+ Title: Tutorial to configure Azure Active Directory B2C with Transmit Security

+description: Learn how to configure Azure Active Directory B2C with Transmit Security for risk detect.

+zone_pivot_groups: b2c-policy-type

+# Customer intent: As a developer integrating Transmit Security with Azure AD B2C for risk detect. I want to configure a custom poicy with Transmit Security and set it up in Azure AD B2C, so I can detect and remidiate risks by using multi-factor authentication.

+# Configure Transmit Security with Azure Active Directory B2C for risk detection and prevention

+In this tutorial, learn to integrate Azure Active Directory B2C (Azure AD B2C) authentication with [Transmit Security's Detection and Response Services (DRS)](https://transmitsecurity.com/platform/detection-and-response). Transmit Security allows you to detect risk in customer interactions on digital channels, and to enable informed identity and trust decisions across the consumer experience.

+## Scenario description

+A Transmit Detection and Response integration includes the following components:

+- **Azure AD B2C tenant**: Authenticates the user and hosts a script that collects device information as users execute a target policy. It blocks or challenges sign-in/up attempts based on the risk recommendation returned by Transmit.

+- **Custom UI templates**: Customizes HTML content of the pages rendered by Azure AD B2C. These pages include the JavaScript snippets required for Transmit risk detection.

+- **Transmit data collection service**: Dynamically embedded script that logs device information, which is used to continuously assess risk during user interactions.

+- **Transmit DRS API endpoint**: Provides the risk recommendation based on collected data. Azure AD B2C communicates with this endpoint using a REST API connector.

+- **Azure Functions**: Your hosted API endpoint that is used to obtain a recommendation from the Transmit DRS API endpoint via the API connector.

+The following architecture diagram illustrates the implementation described in the guide:

+[  ](./media/partner-transmit-security/transmit-security-integration-diagram.png#lightbox)

+1. The user signs-in with Azure AD B2C.

+2. A custom page initializes the Transmit SDK, which starts streaming device information to Transmit.

+3. Azure AD B2C reports a sign-in action event to Transmit in order to obtain an action token.

+4. Transmit returns an action token, and Azure AD B2C proceeds with the user sign-up or sign-in.

+5. After the user signs-in, Azure AD B2C requests a risk recommendation from Transmit via the Azure Function.

+6. The Azure Function sends Transmit the recommendation request with the action token.

+7. Transmit returns a recommendation (challenge/allow/deny) based on the collected device information.

+8. The Azure Function passes the recommendation result to Azure AD B2C to handle accordingly.

+9. Azure AD B2C performs more steps if needed, like multifactor authentication and completes the sign-up or sign-in flow.

+## Prerequisites

+* A Microsoft Entra subscription. If you don't have one, get a [free account](https://azure.microsoft.com/free/)

+* [An Azure AD B2C tenant](./tutorial-create-tenant.md) linked to the Entra subscription

+* [A registered web application](./tutorial-register-applications.md) in your Azure AD B2C tenant

+* [Azure AD B2C custom policies](./tutorial-create-user-flows.md?pivots=b2c-custom-policy)

+* A Transmit Security tenant. Go to [transmitsecurity.com](https://transmitsecurity.com/)

+## Step 1: Create a Transmit app

+Sign in to the [Transmit Admin Portal](https://portal.transmitsecurity.io/) and [create an application](https://developer.transmitsecurity.com/guides/user/create_new_application/):

+1. From **Applications**, select **Add application**.

+1. Configure the application with the following attributes:

+ | Property | Description |

+ |:|:|

+ | **Application name** | Application name|

+ | **Client name** | Client name|

+ | **Redirect URIs** | Enter your website URL. This attribute is a required field but not used for this flow|

+3. Select **Add**.

+4. Upon registration, a **Client ID** and **Client Secret** appear. Record the values for use later.

+## Step 2: Create your custom UI

+Start by integrating Transmit DRS into the B2C frontend application. Create a custom sign-in page that integrates the [Transmit SDK](https://developer.transmitsecurity.com/sdk-ref/platform/introduction/), and replaces the default Azure AD B2C sign-in page.

+Once activated, Transmit DRS starts collecting information for the user interacting with your app. Transmit DRS returns an action token that Azure AD B2C needs for risk recommendation.

+To integrating Transmit DRS into the B2C sign-in page, follow these steps:

+1. Prepare a custom HTML file for your sign-in page based on the [sample templates](./customize-ui-with-html.md#sample-templates). Add the following script to load and initialize the Transmit SDK, and to obtain an action token. The returned action token should be stored in a hidden HTML element (`ts-drs-response` in this example).

+ ```html

+ <!-- Function that obtains an action token -->

+ <script>

+ function fill_token() {

+ window.tsPlatform.drs.triggerActionEvent("login").then((actionResponse) => {

+ let actionToken = actionResponse.actionToken;

+ document.getElementById("ts-drs-response").value = actionToken;

+ console.log(actionToken);

+ });

+ }

+ </script>

+

+ <!-- Loads DRS SDK -->

+ <script src="https://platform-websdk.transmitsecurity.io/platform-websdk/latest/ts-platform-websdk.js" defer> </script>

+

+ <!-- Upon page load, initializes DRS SDK and calls the fill_token function -->

+ <script defer>

+ window.onload = function() {

+ if (window.tsPlatform) {

+ // Client ID found in the app settings in Transmit Admin portal

+ window.tsPlatform.initialize({ clientId: "[clientId]" });

+ console.log("Transmit Security platform initialized");

+ fill_token();

+ } else {/

+ console.error("Transmit Security platform failed to load");

+ }

+ };

+ </script>

+ ```

+1. [Enable JavaScript and page layout versions in Azure AS B2C](./javascript-and-page-layout.md).

+1. Host the HTML page on a Cross-Origin Resource Sharing (CORS) enabled web endpoint by [creating a storage account](../storage/blobs/storage-blobs-introduction.md) and [adding CORS support for Azure Storage](/rest/api/storageservices/cross-origin-resource-sharing--cors--support-for-the-azure-storage-services).

+## Step 3: Create an Azure Function

+Azure AD B2C can obtain a risk recommendation from Transmit using a [API connector](./add-api-connector.md). Passing this request through an intermediate web API (such as using [Azure Functions](/azure/azure-functions/)) provides more flexibility in your implementation logic.

+Follow these steps to create an Azure function that uses the action token from the frontend application to get a recommendation from the [Transmit DRS endpoint](https://developer.transmitsecurity.com/openapi/risk/recommendations/#operation/getRiskRecommendation).

+1. Create the entry point of your Azure Function, an HTTP-triggered function that processes incoming HTTP requests.

+ ```csharp

+ public static async Task<HttpResponseMessage> Run(HttpRequest req, ILogger log)

+ {

+ // Function code goes here

+ }

+ ```

+2. Extract the action token from the request. Your custom policy defines how to pass the request, in query string parameters or body.

+ ```csharp

+ // Checks for the action token in the query string

+ string actionToken = req.Query["actiontoken"];

+

+ // Checks for the action token in the request body

+ string requestBody = await new StreamReader(req.Body).ReadToEndAsync();

+ dynamic data = JsonConvert.DeserializeObject(requestBody);

+ actionToken = actionToken ?? data?.actiontoken;

+ ```

+3. Validate the action token by checking that the provided value isn't empty or null:

+ ```csharp

+ // Returns an error response if the action token is missing

+ if (string.IsNullOrEmpty(actionToken))

+ {

+ var respContent = new { version = "1.0.0", status = (int)HttpStatusCode.BadRequest, userMessage = "Invalid or missing action token" };

+ var json = JsonConvert.SerializeObject(respContent);

+ log.LogInformation(json);

+ return new HttpResponseMessage(HttpStatusCode.BadRequest)

+ {

+ Content = new StringContent(json, Encoding.UTF8, "application/json")

+ };

+ }

+ ```

+4. Call the Transmit DRS API. The Transmit Client ID and Client Secret obtained in Step 1 should be used to generate bearer tokens for API authorization. Make sure to add the necessary environment variables (like ClientId and ClientSecret) in your `local.settings.json` file.

+ ```csharp

+ HttpClient client = new HttpClient();

+ client.DefaultRequestHeaders.Add("Authorization", $"Bearer {transmitSecurityApiKey}");

+

+ // Add code here that sends this GET request:

+ // https://api.transmitsecurity.io/risk/v1/recommendation?action_token=[YOUR_ACTION_TOKEN]

+

+ HttpResponseMessage response = await client.GetAsync(urlWithActionToken);

+ ```

+5. Process the API response. The following code forwards the API response if successful; otherwise, handles any errors.

+ ```csharp

+ if (response.IsSuccessStatusCode)

+ {

+ log.LogInformation(responseContent);

+ return new HttpResponseMessage(HttpStatusCode.OK)

+ {

+ Content = new StringContent(responseContent, Encoding.UTF8, "application/json")

+ };

+ }

+ else

+ {

+ var errorContent = new { version = "1.0.0", status = (int)response.StatusCode, userMessage = "Error calling Transmit Security API" };

+ var json = JsonConvert.SerializeObject(errorContent);

+ log.LogError(json);

+ return new HttpResponseMessage(response.StatusCode)

+ {

+ Content = new StringContent(json, Encoding.UTF8, "application/json")

+ };

+ }

+ ```

+## Step 4: Configure your custom policies

+You incorporate Transmit DRS into your Azure B2C application by extending your custom policies.

+1. Download the [custom policy starter pack](https://github.com/Azure-Samples/active-directory-b2c-custom-policy-starterpack/archive/master.zip) to get started (see [Create custom policies in Azure AD B2C](./tutorial-create-user-flows.md?pivots=b2c-custom-policy))

+2. Create a new file that inherits from **TrustFrameworkExtensions**, which extens the base policy with tenant-specific customizations for Transmit DRS.

+ ```xml

+ <BasePolicy>

+ <TenantId>YOUR AZURE TENANT</TenantId>

+ <PolicyId>B2C_1A_TrustFrameworkExtensions</PolicyId>

+ </BasePolicy>

+ ```

+2. In the `BuildingBlocks` section, define `actiontoken`, `ts-drs-response`, and `ts-drs-recommendation` as claims:

+ ```xml

+ <BuildingBlocks>

+ <ClaimsSchema>

+ <ClaimType Id="ts-drs-response">

+ <DisplayName>ts-drs-response</DisplayName>

+ <DataType>string</DataType>

+ <UserHelpText>Parameter provided to the DRS service for the response</UserHelpText>

+ <UserInputType>TextBox</UserInputType>

+ </ClaimType>

+ <ClaimType Id="actiontoken">

+ <DisplayName>actiontoken</DisplayName>

+ <DataType>string</DataType>

+ <UserHelpText />

+ <UserInputType>TextBox</UserInputType>

+ </ClaimType>

+ <ClaimType Id="ts-drs-recommendation">

+ <DisplayName>recommendation</DisplayName>

+ <DataType>string</DataType>

+ <UserHelpText />

+ <UserInputType>TextBox</UserInputType>

+ </ClaimType>

+ </ClaimsSchema>

+ <BuildingBlocks>

+ ```

+3. In the `BuildingBlocks` section, add a reference to your custom UI:

+ ```xml

+ <BuildingBlocks>

+ <ClaimsSchema>

+ <!-- your claim schemas-->

+ </ClaimsSchema>

+

+ <ContentDefinitions>

+ <ContentDefinition Id="api.selfasserted">

+ <!-- URL of your hosted custom HTML file-->

+ <LoadUri>YOUR_SIGNIN_PAGE_URL</LoadUri>

+ </ContentDefinition>

+ </ContentDefinitions>

+ </BuildingBlocks>

+ ```

+4. In the `ClaimsProviders` section, configure a claims provider that includes the following technical profiles: one (`SelfAsserted-LocalAccountSignin-Email`) that outputs the action token, and another (`login-DRSCheck` in our example) for the Azure function that receives the action token as input and outputs the risk recommendation.

+ ```xml

+ <ClaimsProviders>

+ <ClaimsProvider>

+ <DisplayName>Sign in using DRS</DisplayName>

+ <TechnicalProfiles>

+ <TechnicalProfile Id="SelfAsserted-LocalAccountSignin-Email">

+ <DisplayName>Local Account Sign-in</DisplayName>

+ <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.SelfAssertedAttributeProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

+ <Metadata>

+ <Item Key="SignUpTarget">SignUpWithLogonEmailExchange</Item>

+ <Item Key="setting.operatingMode">Email</Item>

+ <Item Key="setting.showSignupLink">true</Item>

+ <Item Key="setting.showCancelButton">false</Item>

+ <Item Key="ContentDefinitionReferenceId">api.selfasserted</Item>

+ <Item Key="language.button_continue">Sign In</Item>

+ </Metadata>

+ <IncludeInSso>false</IncludeInSso>

+ <InputClaims>

+ <InputClaim ClaimTypeReferenceId="signInName" />

+ </InputClaims>

+ <OutputClaims>

+ <OutputClaim ClaimTypeReferenceId="signInName" Required="true" />

+ <OutputClaim ClaimTypeReferenceId="password" Required="true" />

+ <OutputClaim ClaimTypeReferenceId="objectId" />

+ <OutputClaim ClaimTypeReferenceId="authenticationSource" />

+ <!-- Outputs the action token value provided by the frontend-->

+ <OutputClaim ClaimTypeReferenceId="ts-drs-response" />

+ </OutputClaims>

+ <ValidationTechnicalProfiles>

+ <ValidationTechnicalProfile ReferenceId="login-DRSCheck" />

+ <ValidationTechnicalProfile ReferenceId="login-NonInteractive" />

+ </ValidationTechnicalProfiles>

+ </TechnicalProfile>

+ <TechnicalProfile Id="login-DRSCheck">

+ <DisplayName>DRS check to validate the interaction and device </DisplayName>

+ <Protocol Name="Proprietary" Handler="Web.TPEngine.Providers.RestfulProvider, Web.TPEngine, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null" />

+ <Metadata>

+ <!-- Azure Function App -->

+ <Item Key="ServiceUrl">YOUR_FUNCTION_URL</Item>

+ <Item Key="AuthenticationType">None</Item>

+ <Item Key="SendClaimsIn">Body</Item>

+ <!-- JSON, Form, Header, and Query String formats supported -->

+ <Item Key="ClaimsFormat">Body</Item>

+ <!-- Defines format to expect claims returning to B2C -->

+ <!-- REMOVE the following line in production environments -->

+ <Item Key="AllowInsecureAuthInProduction">true</Item>

+ </Metadata>

+ <InputClaims>

+ <!-- Receives the action token value as input -->

+ <InputClaim ClaimTypeReferenceId="ts-drs-response" PartnerClaimType="actiontoken" DefaultValue="0" />

+ </InputClaims>

+ <OutputClaims>

+ <!-- Outputs the risk recommendation value returned by Transmit (via the Azure function) -->

+ <OutputClaim ClaimTypeReferenceId="ts-drs-recommendation" PartnerClaimType="recommendation.type" />

+ </OutputClaims>

+ </TechnicalProfile>

+ </TechnicalProfiles>

+ </ClaimsProvider>

+ </ClaimsProviders>

+ ```

+5. In the `UserJourneys` section, create a new user journey (`SignInDRS` in our example) that identifies the user and performs the appropriate identity protection steps based on the Transmit risk recommendation. For example, the journey can proceed normally if Transmit returns **allow** or **trust**, terminate and inform the user of the issue if 'deny', or trigger a step-up authentication process if **challenge**.

+```xml

+ <UserJourneys>

+ <UserJourney Id="SignInDRS">

+ <OrchestrationSteps>

+ <!-- Step that identifies the user by email and stores the action token -->

+ <OrchestrationStep Order="1" Type="CombinedSignInAndSignUp" ContentDefinitionReferenceId="api.selfasserted">

+ <ClaimsProviderSelections>

+ <ClaimsProviderSelection ValidationClaimsExchangeId="LocalAccountSigninEmailExchange" />

+ </ClaimsProviderSelections>

+ <ClaimsExchanges>

+ <ClaimsExchange Id="LocalAccountSigninEmailExchange" TechnicalProfileReferenceId="SelfAsserted-LocalAccountSignin-Email" />

+ </ClaimsExchanges>

+ </OrchestrationStep>

+ <!-- Step to perform DRS check -->

+ <OrchestrationStep Order="2" Type="ClaimsExchange">

+ <ClaimsExchanges>

+ <ClaimsExchange Id="DRSCheckExchange" TechnicalProfileReferenceId="login-DRSCheck" />

+ </ClaimsExchanges>

+ </OrchestrationStep>

+ <!-- Conditional step for ACCEPT or TRUST -->

+ <OrchestrationStep Order="3" Type="ClaimsExchange">

+ <Preconditions>

+ <Precondition Type="ClaimEquals" ExecuteActionsIf="false">

+ <Value>ts-drs-recommendation</Value>

+ <Value>ACCEPT</Value>

+ <Value>TRUST</Value>

+ <Action>SkipThisOrchestrationStep</Action>

+ </Precondition>

+ </Preconditions>

+ <!-- Define the ClaimsExchange or other actions for ACCEPT or TRUST -->

+ </OrchestrationStep>

+ <!-- Conditional step for CHALLENGE -->

+ <OrchestrationStep Order="4" Type="ClaimsExchange">

+ <Preconditions>

+ <Precondition Type="ClaimEquals" ExecuteActionsIf="false">

+ <Value>ts-drs-recommendation</Value>

+ <Value>CHALLENGE</Value>

+ <Action>SkipThisOrchestrationStep</Action>

+ </Precondition>

+ </Preconditions>

+ <!-- Define the ClaimsExchange or other actions for CHALLENGE -->

+ </OrchestrationStep>

+ <!-- Conditional step for DENY -->

+ <OrchestrationStep Order="5" Type="ClaimsExchange">

+ <Preconditions>

+ <Precondition Type="ClaimEquals" ExecuteActionsIf="false">

+ <Value>ts-drs-recommendation</Value>

+ <Value>DENY</Value>

+ <Action>SkipThisOrchestrationStep</Action>

+ </Precondition>

+ </Preconditions>

+ <!-- Define the ClaimsExchange or other actions for DENY -->

+ </OrchestrationStep>

+ </UserJourney>

+ </UserJourneys>

+```

+7. Save the policy file as `DRSTrustFrameworkExtensions.xml`.

+8. Create a new file that inherits from the file you saved. It extends the sign-in policy that works as an entry point for the sign-up and sign-in user journeys with Transmit DRS.

+ ```xml

+ <BasePolicy>

+ <TenantId>YOUR AZURE TENANT</TenantId>

+ <PolicyId>B2C_1A_DRSTrustFrameworkExtensions</PolicyId>

+ </BasePolicy>

+ ```

+9. In the `RelyingParty` section, configure your DRS-enhanced user journey (`SignInDRS` in our example).

+ ```xml

+ <RelyingParty>

+ <DefaultUserJourney ReferenceId="SignInDRS" />

+ <UserJourneyBehaviors>

+ <ScriptExecution>Allow</ScriptExecution>

+ </UserJourneyBehaviors>

+ <TechnicalProfile Id="PolicyProfile">

+ <DisplayName>PolicyProfile</DisplayName>

+ <Protocol Name="OpenIdConnect" />

+ <OutputClaims>

+ <OutputClaim ClaimTypeReferenceId="displayName" />

+ <OutputClaim ClaimTypeReferenceId="givenName" />

+ <OutputClaim ClaimTypeReferenceId="surname" />

+ <OutputClaim ClaimTypeReferenceId="email" />

+ <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub" />

+ </OutputClaims>

+ <SubjectNamingInfo ClaimType="sub" />

+ </TechnicalProfile>

+ </RelyingParty>

+ ```

+9. Save the policy file as `DRSSignIn.xml`.

+## Step 5: Upload the custom policy

+Using the directory with your Azure AD B2C tenant, upload the custom policy:

+1. Sign in to the [Azure portal](https://portal.azure.com/).

+1. In the portal toolbar, select **Directories + subscriptions**.

+1. On the **Portal settings | Directories + subscriptions** page, in the **Directory name** list, find the Azure AD B2C directory and then select **Switch**.

+1. Under **Policies**, select **Identity Experience Framework**.

+1. Select **Upload Custom Policy**, and then upload the updated custom policy files.

+## Step 6: Test your custom policy

+Using the directory with your Azure AD B2C tenant, test your custom policy:

+1. In the Azure AD B2C tenant, and under Policies, select Identity Experience Framework.

+2. Under **Custom policies**, select the Sign in policy.

+3. For **Application**, select the web application you registered.

+4. Select **Run now**.

+5. Complete the user flow.

+## Next steps

+* Ask questions on [Stackoverflow](https://stackoverflow.com/questions/tagged/azure-ad-b2c)

+* Check out the [Azure AD B2C custom policy overview](custom-policy-overview.md)

+<a name='create-a-xid-policy-key'></a>

+## Create an xID policy key

+The following example shows an IsLengthRange method with the parameters `Minimum` and `Maximum` that specify the length range of the string:

+> [!NOTE]

+> When you collect the password claim value in the self-asserted technical profile, that value is only available within the same technical profile or within a validation technical profiles that are referenced by that same self-asserted technical profile. When execution of that self-asserted technical profile completes, and moves to another technical profile, the password's value is lost. Consequently, password claim can only be stored in the orchestration step in which it is collected.

+|Total number of objects (user accounts and applications) per tenant (using a verified custom domain). If you want to increase this limit, please contact [Microsoft Support](find-help-open-support-ticket.md).|5.25 million |

+| InputParameter | compareTo | string | String comparison, one of the values, that is, the string to which the input claim values must be compared to: Ordinal, OrdinalIgnoreCase. |

+- [Clean up resources and delete tenant](tutorial-delete-tenant.md)

+- Respond back with a new authentication request using Azure AD B2C password reset user flow.

+After you finish developing your policy, you upload the policy to Azure AD B2C. There might be some issues with your policy, but you can validate your policy before you upload it.

+ Title: Calculate cost savings in Azure Advisor

+# Calculate cost savings

+This article provides guidance on how to calculate total cost savings in Azure Advisor.

+## Export cost savings for recommendations

+> Different types of cost savings recommendations are generated using overlapping datasets (for example, VM rightsizing/shutdown, VM reservations and savings plan recommendations all consider on-demand VM usage). As a result, resource changes (e.g., VM shutdowns) or reservation/savings plan purchases will impact on-demand usage, and the resulting recommendations and associated savings forecast.

+## Understand cost savings

+Azure Advisor provides recommendations for resizing/shutting down underutilized resources, purchasing compute reserved instances, and savings plans for compute.

+These recommendations contain one or more calls-to-action and forecasted savings from following the recommendations. Recommendations should be followed in a specific order: rightsizing/shutdown, followed by reservation purchases, and finally, the savings plan purchase. This sequence allows each step to impact the subsequent ones positively.

+For example, rightsizing or shutting down resources reduces on-demand costs immediately. This change in your usage pattern essentially invalidates your existing reservation and savings plan recommendations, as they were based on your pre-rightsizing usage and costs. Updated reservation and savings plan recommendations (and their forecasted savings) should appear within three days.

+The forecasted savings from reservations and savings plans are based on actual rates and usage, while the forecasted savings from rightsizing/shutdown are based on retail rates. The actual savings may vary depending on the usage patterns and rates. Assuming there are no material changes to your usage patterns, your actual savings from reservations and savings plan should be in line with the forecasts. Savings from rightsizing/shutdown vary based on your actual rates. This is important if you intend to track cost savings forecasts from Azure Advisor.

+Learn more about [Volume - Azure NetApp Files Cross Zone Replication SDK recommendation](https://aka.ms/anf-sdkversion).

+Learn more about [Volume - Large Volumes SDK Recommendation](/azure/azure-netapp-files/azure-netapp-files-resource-limits).

+## April 2024

+### Azure Advisor will no longer display aggregated potential yearly savings beginning 30 September 2024

+In the Azure portal, Azure Advisor currently shows potential aggregated cost savings under the label "Potential yearly savings based on retail pricing" on pages where cost recommendations are displayed (as shown in the image). This aggregated savings estimate will be removed from the Azure portal on 30 September 2024. However, you can still evaluate potential yearly savings tailored to your specific needs by following the steps in [Calculate cost savings](/azure/advisor/advisor-how-to-calculate-total-cost-savings). All individual recommendations and their associated potential savings will remain available.

+#### Recommended action

+If you want to continue calculating aggregated potential yearly savings, follow [these steps](/azure/advisor/advisor-how-to-calculate-total-cost-savings). Note that individual recommendations might show savings that overlap with the savings shown in other recommendations, although you might not be able to benefit from them concurrently. For example, you can benefit from savings plans or from reservations for virtual machines, but not typically from both on the same virtual machines.

+### Public Preview: Resiliency Review on Azure Advisor

+Recommendations from WAF Reliability reviews in Advisor help you focus on the most important recommendations to ensure your workloads remain resilient. As part of the review, personalized and prioritized recommendations from Microsoft Cloud Solution Architects will be presented to you and your team. You can triage recommendations (accept or reject), manage their lifecycle on Advisor, and work with your Microsoft account team to track resolution. You can reach out to your account team to request Well Architected Reliability Assessment to successfully optimize workload resiliency and reliability by implementing curated recommendations and track its lifecycle on Advisor.

+To learn more, visit [Azure Advisor Resiliency Reviews](/azure/advisor/advisor-resiliency-reviews).

+The Azure Cost Optimization workbook serves as a centralized hub for some of the most used tools that can help you drive utilization and efficiency goals. It offers a range of recommendations, including Azure Advisor cost recommendations, identification of idle resources, and management of improperly deallocated Virtual Machines. Additionally, it provides insights into leveraging Azure Hybrid benefit options for Windows, Linux, and SQL databases.

+To learn more, visit [Dismissing and postponing recommendations](/azure/advisor/view-recommendations#dismissing-and-postponing-recommendations).

+It's easier now to get an overview of optimization opportunities available to your organization ΓÇô no need to spend time and effort to apply filters and process subscription in batches.

+|Subscription Owner<br>Subscription Contributor|View reviews for a workload, triage recommendations linked to those reviews, manage the recommendation lifecycle.|

+|Advisor Recommendations Contributor (Assessments and Reviews)|View accepted recommendations, and manage the recommendation lifecycle.|

+This page is a collection of [Azure Resource Graph](../governance/resource-graph/overview.md) sample queries for Azure Advisor. For a complete list of Azure Resource Graph samples, see [Resource Graph samples by Category](../governance/resource-graph/samples/samples-by-category.md) and [Resource Graph samples by Table](../governance/resource-graph/samples/samples-by-table.md).

+ * Add label

+ * Add batch label

+ * Review labels

+ * Suggest endpoint queries for entities

+ * Suggest endpoint queries for intents

+ For more information, see the [LUIS reference documentation](/rest/api/cognitiveservices-luis/authoring/features?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true).

+Your app might need to process sentences, like "Book a ticket to Paris for me," or a fragment of a sentence, like "Booking" or "Paris flight" Users also often make spelling mistakes. When planning your app, consider whether or not you want to use [Bing Spell Check](../luis-tutorial-bing-spellcheck.md) to correct user input before passing it to LUIS.

+If you don't spell check user utterances, you should train LUIS on utterances that include typos and misspellings.

+When choosing utterances, be aware that what you think are common terms or phrases might not be common for the typical user of your client application. They might not have domain experience or use different terminology. Be careful when using terms or phrases that a user would only say if they were an expert.

+You'll find that even if you make efforts to create varied sentence patterns, you'll still repeat some vocabulary. For example, the following utterances have similar meaning, but different terminology and phrasing:

+Each intent needs to have example utterances - at least 15. If you have an intent that doesn't have any example utterances, you will not be able to train LUIS. If you have an intent with one or few example utterances, LUIS might not accurately predict the intent.

+It's better to start with a few utterances, then [review the endpoint utterances](../how-to/improve-application.md) for correct intent prediction and entity extraction.

+Set your app's version settings using the LUIS portal by selecting **Manage** from the top navigation menu, in the **Application Settings** page. You can also use the [Update Version Settings API](/rest/api/cognitiveservices-luis/authoring/versions/update?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true). See the [Reference](../luis-reference-application-settings.md) documentation for more information.

+Punctuation is a separate token in LUIS. An utterance that contains a period at the end is a separate utterance than one that doesn't contain a period at the end, and might get two different predictions.

+If punctuation isn't normalized, LUIS doesn't ignore punctuation marks by default because some client applications might place significance on these marks. Make sure to include example utterances that use punctuation, and ones that don't, for both styles to return the same relative scores.

+Training is nondeterministic: utterance prediction can vary slightly across versions or apps. You can remove nondeterministic training by updating the [version settings](/rest/api/cognitiveservices-luis/authoring/settings/update?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) API with the UseAllTrainingData name/value pair to use all training data.

+Developers should start testing their LUIS application with real data by sending utterances to the [prediction endpoint](../luis-how-to-azure-subscription.md) URL. These utterances are used to improve the performance of the intents and entities with [Review utterances](../how-to/improve-application.md). Tests submitted using the testing pane in the LUIS portal aren't sent through the endpoint, and don't contribute to active learning.

+If the word choice or word arrangement is the same, but doesn't mean the same thing, don't label it with the entity.

+* "*What kinds of county fairs are happening in the Seattle area this summer?*"

+|Buy a ticket to Paris|Reserve two tickets on the red eye to Paris next Monday|

+|Authoring|[V2](https://go.microsoft.com/fwlink/?linkid=2092087)<br>[preview V3](/rest/api/cognitiveservices-luis/authoring/operation-groups)|

+|Prediction|[V2](https://go.microsoft.com/fwlink/?linkid=2092356)<br>[V3](/rest/api/cognitiveservices-luis/runtime/operation-groups?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)|

+description: Use this article to see frequently asked questions about LUIS, and troubleshooting information.

+LUIS has little or no knowledge of the broader _NLP_ aspects, such as semantic similarity, without explicit identification in examples. For example, the following tokens (words) are three different things until they're used in similar contexts in the examples provided:

+For semantic similarity Natural Language Understanding (NLU), you can use [Conversation Language Understanding](../language-service/conversational-language-understanding/overview.md).

+Language Understand has separate resources, one type for authoring, and one type for querying the prediction endpoint, each has their own pricing. See [Resource usage and limits](luis-limits.md#resource-usage-and-limits).

+See [region support](https://azure.microsoft.com/global-infrastructure/services/?products=cognitive-services).

+LUIS stores data encrypted in an Azure data store corresponding to the region specified by the key. Data used to train the model such as entities, intents, and utterances will be saved in LUIS for the lifetime of the application. If an owner or contributor deletes the app, this data will be deleted with it. If an application hasn't been used in 90 days, it will be deleted. See [Data retention](luis-concept-data-storage.md) for more details about data storage.

+Enable or disable the use nondeterministic training option. When disabled, training will use all available data. When enabled (by default), training will use a random sample each time the app is trained, to be used as a negative for the intent. To make sure that you are getting same scores every time, make sure you train your LUIS app with all your data. See the [training article](how-to/train-test.md#change-deterministic-training-settings-using-the-version-settings-api) for more information.

+Designate a single main app. Any utterances that are suggested for review should be added to the main app, then moved back to all the other apps. This is either a full export of the app, or loading the labeled utterances from the main app to the other apps. Loading can be done from either the [LUIS](./luis-reference-regions.md?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) website or the authoring API for a [single utterance](/rest/api/cognitiveservices-luis/authoring/examples/add) or for a [batch](/rest/api/cognitiveservices-luis/authoring/examples/batch?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true).

+Use this article to get started with the LUIS portal, and create an authoring resource. After completing the steps in this article, you'll be able to create and publish LUIS apps.

+1. To get started with LUIS, go to the [LUIS Portal](https://www.luis.ai/). If you don't already have a subscription, you'll be prompted to go create a [free account](https://azure.microsoft.com/free/cognitive-services/) and return back to the portal.

+4. If your subscription lives under another tenant, you won't be able to switch tenants from the existing window. You can switch tenants by closing this window and selecting the avatar containing your initials in the top-right section of the screen. Select **Choose a different authoring resource** from the top to reopen the window.

+* **Tenant Name** - the tenant your Azure subscription is associated with. You won't be able to switch tenants from the existing window. You can switch tenants by closing this window and selecting the avatar at the top-right corner of the screen, containing your initials. Select **Choose a different authoring resource** from the top to reopen the window.

+* **Azure Resource group name** - a custom resource group name you choose in your subscription. Resource groups allow you to group Azure resources for access and management. If you currently don't have a resource group in your subscription, you won't be allowed to create one in the LUIS portal. Go to [Azure portal](https://portal.azure.com/#create/Microsoft.ResourceGroup) to create one then go to LUIS to continue the sign-in process.

+* **Location** - Choose to author your applications in one of the [three authoring locations](../luis-reference-regions.md) that are currently supported by LUIS including: West US, West Europe, and East Australia

+* [Add application](/rest/api/cognitiveservices-luis/authoring/apps/add?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) - start with an empty app and create intents, utterances, and entities.

+* [Add prebuilt application](/rest/api/cognitiveservices-luis/authoring/apps/add-custom-prebuilt-domain?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) - start with a prebuilt domain, including intents, utterances, and entities.

+1. Send an HTTP POST [request for training](/rest/api/cognitiveservices-luis/authoring/train/train-version?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true).

+2. Request the [training status](/rest/api/cognitiveservices-luis/authoring/train/get-status?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) with an HTTP GET request.

+Use the [Version settings API](/rest/api/cognitiveservices-luis/authoring/settings/update?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) with the UseAllTrainingData set to *true* to turn off deterministic training.

+If you want to disable non-deterministic training for those LUIS app versions that you're building for the purpose of testing, use the [Version settings API](/rest/api/cognitiveservices-luis/authoring/versions?view=rest-cognitiveservices-luis-authoring-v3.0-preview&preserve-view=true) with the `UseAllTrainingData` setting set to `true`.

+* [Published package API](/rest/api/cognitiveservices-luis/authoring/apps/package-published-application-as-gzip?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)

+* [Not-published, trained-only package API](/rest/api/cognitiveservices-luis/authoring/apps/package-trained-application-as-gzip?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)

+The app running in the container can't be altered. In order to change the app in the container, you need to change the app in the LUIS service using the [LUIS](https://www.luis.ai) portal or use the LUIS [authoring APIs](/rest/api/cognitiveservices-luis/authoring/operation-groups?view=rest-cognitiveservices-luis-authoring-v3.0-preview&preserve-view=true). Then train and/or publish, then download a new package and run the container again.

+[download-published-package]: /rest/api/cognitiveservices-luis/authoring/apps/package-published-application-as-gzip?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true

+[download-versioned-package]: /rest/api/cognitiveservices-luis/authoring/apps/package-trained-application-as-gzip?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true

+#Customer intent: As a developer familiar with how to use a browser but new to the LUIS service, I want to query the LUIS endpoint of a published model so that I can see the JSON prediction response.

+The active version is the [version](luis-how-to-manage-versions.md) of your app that is updated when you make changes to the model using the LUIS portal. In the LUIS portal, if you want to make changes to a version that isn't the active version, you need to first set that version as active.

+In LUIS, your application, or app, is a collection of machine-learned models, built on the same data set, that works together to predict intents and entities for a particular scenario. Each application has a separate prediction endpoint.

+A true negative is when your app correctly predicts no match. In batch testing, a true negative occurs when your app does predict an intent or entity for an example that hasn't been labeled with that intent or entity.

+A contributor isn't the [owner](#owner) of the app, but has the same permissions to add, edit, and delete the intents, entities, utterances. A contributor provides Azure role-based access control (Azure RBAC) to a LUIS app.

+The LUIS prediction endpoint URL is where you submit LUIS queries after the [LUIS app](#application-app) is authored and published. The endpoint URL contains the region or custom subdomain of the published app as well as the app ID. You can find the endpoint on the **[Azure resources](luis-how-to-azure-subscription.md)** page of your app, or you can get the endpoint URL from the [Get App Info](/rest/api/cognitiveservices-luis/authoring/apps/get?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) API.

+[Entities](concepts/entities.md) are words in utterances that describe information used to fulfill or identify an intent. If your entity is complex and you would like your model to identify specific parts, you can break your model into subentities. For example, you might want your model to predict an address, but also the subentities of street, city, state, and zipcode. Entities can also be used as features to models. Your response from the LUIS app includes both the predicted intents and all the entities.

+The entity will be predicted if a word in the list entity is included in the list. For example, if you have a list entity called "size" and you have the words "small, medium, large" in the list, then the size entity will be predicted for all utterances where the words "small," "medium," or "large" are used regardless of the context.

+See Prebuilt model's entry for [prebuilt entity](#prebuilt-entity).

+These hints are used with the labels to learn how to predict new data. LUIS supports both phrase lists and using other models as features.

+Consider an example where you have a prebuilt-number feature that you have marked as required on the quantity entity for a menu ordering bot. When your bot sees `I want a bajillion large pizzas?`, bajillion will not be predicted as a quantity regardless of the context in which it appears. Bajillion isn't a valid number and wonΓÇÖt be predicted by the number prebuilt entity.

+An [intent](concepts/intents.md) represents a task or action the user wants to perform. It's a purpose or goal expressed in a user's input, such as booking a flight, or paying a bill. In LUIS, an utterance as a whole is classified as an intent, but parts of the utterance are extracted as entities.

+In LUIS, intents within an app are mutually exclusive. This means when you add an utterance to an intent, it is considered a _positive_ example for that intent and a _negative_ example for all other intents. Negative examples shouldn't be confused with the "None" intent, which represents utterances that are outside the scope of the app.

+Overfitting happens when the model is fixated on the specific examples and isn't able to generalize well.

+A prebuilt entity is an entity LUIS provides for common types of information such as number, URL, and email. These are created based on public data. You can choose to add a prebuilt entity as a stand-alone entity, or as a feature to an entity.

+This key isn't the authoring key. If you have a prediction endpoint key, it should be used for any endpoint requests instead of the authoring key. You can see your current prediction key inside the endpoint URL at the bottom of Azure resources page in LUIS website. It is the value of the subscription-key name/value pair.

+The [score](luis-concept-prediction-score.md) is a number from 0 and 1 that is a measure of how confident the system is that a particular input utterance matches a particular intent. A score closer to 1 means the system is very confident about its output and a score closer to 0 means the system is confident that the input doesn't match a particular output. Scores in the middle mean the system is very unsure of how to make the decision.

+|Small| the little one, 8 ounces|

+|Medium| regular, 12 ounces|

+|Large| big, 16 ounces|

+|Xtra large| the biggest one, 24 ounces|

+The model returns the normalized value for the entity when any of synonyms are seen in the input.

+The endpoint includes [timezoneOffset](luis-concept-data-alteration.md#change-time-zone-of-prebuilt-datetimev2-entity). This is the number in minutes you want to add or remove from the datetimeV2 prebuilt entity. For example, if the utterance is "what time is it now?", the datetimeV2 returned is the current time for the client request. If your client request is coming from a bot or other application that isn't the same as your bot's user, you should pass in the offset between the bot and the user.

+|`RMT33W`|1|A record locator number. It might have numbers and letters, but doesn't have any punctuation.|

+Training errors are predictions on your training data that don't match their labels.

+An [utterance](concepts/utterances.md) is user input that is short text representative of a sentence in a conversation. It's a natural language phrase such as "book 2 tickets to Seattle next Tuesday". Example utterances are added to train the model and the model predicts on new utterance at runtime.

+You can use the [v3.0-preview LUIS Programmatic APIs](/rest/api/cognitiveservices-luis/authoring/apps?view=rest-cognitiveservices-luis-authoring-v3.0-preview&preserve-view=true) to manage authoring resources.

+You can use the [v3.0-preview LUIS Endpoint API](/rest/api/cognitiveservices-luis/runtime/operation-groups?view=rest-cognitiveservices-luis-runtime-v3.0&preserve-view=true) to manage prediction resources.

+1. Use the token to request the LUIS runtime resources across subscriptions. Use the API to [get the LUIS Azure account](/rest/api/cognitiveservices-luis/authoring/azure-accounts/get-assigned?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) that your user account has access to.

+1. Assign the token to the LUIS resource by using the [Assign a LUIS Azure accounts to an application](/rest/api/cognitiveservices-luis/authoring/azure-accounts/assign-to-app?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) API.

+1. Use the token to request the LUIS runtime resources across subscriptions. Use the [Get LUIS Azure accounts API](/rest/api/cognitiveservices-luis/authoring/azure-accounts/get-assigned?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true), which your user account has access to.

+1. Assign the token to the LUIS resource by using the [Unassign a LUIS Azure account from an application](/rest/api/cognitiveservices-luis/authoring/azure-accounts/remove-from-app?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) API.

+In the Azure portal, find your Language Understanding (LUIS) authoring resource. It has the type `LUIS.Authoring`. In the resource's **Access Control (IAM)** page, add the role of **contributor** for the user that you want to contribute. For detailed steps, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.yml).

+* [Importing applications](/rest/api/cognitiveservices-luis/authoring/versions/import?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)

+* [Exporting applications](/rest/api/cognitiveservices-luis/authoring/versions/export?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)

+These settings are stored in the [exported](/rest/api/cognitiveservices-luis/authoring/versions/export?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&tabs=HTTP&preserve-view=true) app and updated with the REST APIs or LUIS portal.

+#### Brazilian Portuguese `pt-br` diacritics

+This includes both French and Canadian subcultures.

+This includes both Spanish and Canadian Mexican.

+LUIS authoring regions are supported by the LUIS portal. To publish a LUIS app to more than one region, you need at least one prediction key per region.

+A public app is published in all regions so that a user with a supported prediction resource can access the app in all regions.

+When you first create our LUIS application, you're required to choose an [authoring region](#luis-authoring-regions). To use the application in runtime, you're required to create a resource in a publishing region.

+Single data residency means that the data doesn't leave the boundaries of the region.

+> * Make sure to set `log=false` for [V3 APIs](/rest/api/cognitiveservices-luis/runtime/prediction/get-slot-prediction?view=rest-cognitiveservices-luis-runtime-v3.0&tabs=HTTP&preserve-view=true) to disable active learning. By default this value is `false`, to ensure that data does not leave the boundaries of the runtime region.

+description: Understand what HTTP response codes are returned from the LUIS Authoring and Endpoint APIs.

+|401|Authoring|you aren't the owner or collaborator|

+* REST API [authoring](/rest/api/cognitiveservices-luis/authoring/operation-groups?view=rest-cognitiveservices-luis-authoring-v3.0-preview&preserve-view=true) and [endpoint](/rest/api/cognitiveservices-luis/runtime/operation-groups?view=rest-cognitiveservices-luis-runtime-v3.0&preserve-view=true) documentation

+description: Learn how to build a LUIS app programmatically from pre-existing data in CSV format using the LUIS Authoring API.

+* Install the latest Node.js version. Download it from [here](https://nodejs.org/en/download/).

+## Map pre-existing data to intents and entities

+Once the entities and intents have been defined in the LUIS app, you can add the utterances. The following code uses the [Utterances_AddBatch](/rest/api/cognitiveservices-luis/authoring/examples/batch?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) API, which allows you to add up to 100 utterances at a time. Copy or [download](https://github.com/Azure-Samples/cognitive-services-language-understanding/blob/master/examples/build-app-programmatically-csv/_upload.js) it, and save it into `_upload.js`.

+Install the Node.js dependencies in the terminal/command line.

+Or

+[Test and train your app in LUIS website](how-to/train-test.md).

+- [create app](/rest/api/cognitiveservices-luis/authoring/apps/add?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)

+- [add intents](/rest/api/cognitiveservices-luis/authoring/features/add-intent-feature?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)

+- [add entities](/rest/api/cognitiveservices-luis/authoring/features/add-entity-feature?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)

+- [add utterances](/rest/api/cognitiveservices-luis/authoring/examples/add?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)

+Language Understanding Intelligent Service (LUIS) preserves customer content to operate the service, but the LUIS user has full control over viewing, exporting, and deleting their data. This can be done through the LUIS web [portal](luis-reference-regions.md) or the [LUIS Authoring (also known as Programmatic) APIs](/rest/api/cognitiveservices-luis/authoring/operation-groups?view=rest-cognitiveservices-luis-authoring-v3.0-preview&preserve-view=true).

+| **APIs** | [Link](/rest/api/cognitiveservices-luis/authoring/azure-accounts/remove-from-app?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) | [Link](/rest/api/cognitiveservices-luis/authoring/apps/delete?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) | [Link](/rest/api/cognitiveservices-luis/authoring/examples/delete?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) | [Link](/rest/api/cognitiveservices-luis/authoring/versions/delete-unlabelled-utterance?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) |

+| **APIs** | [Link](/rest/api/cognitiveservices-luis/authoring/azure-accounts/list-user-luis-accounts?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) | [Link](/rest/api/cognitiveservices-luis/authoring/versions/export?view=rest-cognitiveservices-luis-authoring-v2.0&tabs=HTTP&preserve-view=true) | [Link](/rest/api/cognitiveservices-luis/authoring/examples/list?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) | [Link](/rest/api/cognitiveservices-luis/authoring/apps/download-query-logs?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) |

+create an [Explicit List](/rest/api/cognitiveservices-luis/authoring/model/add-explicit-list-item?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true) through the authoring API to allow the exception when:

+To fix this exception to the pattern, add `the man from la mancha` as an explicit list match for the {subject} entity using the [authoring API for explicit list](/rest/api/cognitiveservices-luis/authoring/model/add-explicit-list-item?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true).

+Within a few minutes, the target will be assigned the selected role at the selected scope. For help with these steps, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.yml).

+ * [LUIS Programmatic v3.0-preview](/rest/api/cognitiveservices-luis/authoring/operation-groups?view=rest-cognitiveservices-luis-authoring-v3.0-preview&preserve-view=true)

+ * [LUIS Programmatic v2.0 APIs](/rest/api/cognitiveservices-luis/authoring/operation-groups?view=rest-cognitiveservices-luis-authoring-v2.0&preserve-view=true)

+ * [LUIS Endpoint APIs v3.0](/rest/api/cognitiveservices-luis/runtime/operation-groups?view=rest-cognitiveservices-luis-runtime-v3.0&preserve-view=true)

+ * [LUIS Programmatic v3.0-preview](/rest/api/cognitiveservices-luis/authoring/operation-groups?view=rest-cognitiveservices-luis-authoring-v3.0-preview&preserve-view=true)

+ * [LUIS Programmatic v2.0 APIs](/rest/api/cognitiveservices-luis/authoring/operation-groups?view=rest-cognitiveservices-luis-authoring-v2.0&preserve-view=true)

+ * [Delete application](/rest/api/cognitiveservices-luis/authoring/apps/delete?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)

+ * Move app to another LUIS authoring Azure resource

+ * [Publish an application](/rest/api/cognitiveservices-luis/authoring/apps/publish?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)

+ * [Update application settings](/rest/api/cognitiveservices-luis/authoring/apps/update-settings?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)

+ * [Assign a LUIS azure accounts to an application](/rest/api/cognitiveservices-luis/authoring/azure-accounts/assign-to-app?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)

+ * [Remove an assigned LUIS azure accounts from an application](/rest/api/cognitiveservices-luis/authoring/azure-accounts/remove-from-app?view=rest-cognitiveservices-luis-authoring-v3.0-preview&tabs=HTTP&preserve-view=true)

+>

+> For information on configuring Azure AI Studio, see the [Azure AI Studio documentation](../ai-studio/how-to/configure-private-link.md).

+If you use Azure ExpressRoute on-premises for Microsoft peering, you need to identify the NAT IP addresses. For more information, see [What is Azure ExpressRoute](../expressroute/expressroute-introduction.md).

+For Microsoft peering, the NAT IP addresses that are used are either customer provided or supplied by the service provider. To allow access to your service resources, you must allow these public IP addresses in the resource IP firewall setting.

+- Access to the Azure AI Vision Face Client SDK for mobile (IOS and Android) and web. To get started, you need to apply for the [Face Recognition Limited Access features](https://customervoice.microsoft.com/Pages/ResponsePage.aspx?id=v4j5cvGGr0GRqy180BHbR7en2Ais5pxKtso_Pz4b1_xUQjA5SkYzNDM4TkcwQzNEOE1NVEdKUUlRRCQlQCN0PWcu) to get access to the SDK. For more information, see the [Face Limited Access](/legal/cognitive-services/computer-vision/limited-access-identity?context=%2Fazure%2Fcognitive-services%2Fcomputer-vision%2Fcontext%2Fcontext) page.

+The liveness solution integration involves two different components: a frontend mobile/web application and an app server/orchestrator.

+Once you have access to the SDK, follow instruction in the [azure-ai-vision-sdk](https://github.com/Azure-Samples/azure-ai-vision-sdk) GitHub repository to integrate the UI and the code into your native mobile application. The liveness SDK supports Java/Kotlin for Android mobile applications, Swift for iOS mobile applications and JavaScript for web applications:

+- For JavaScript Web, follow the instructions in the [Web sample](https://aka.ms/liveness-sample-web)

+1. The frontend application starts the liveness check and notifies the app server.

+1. The app server creates a new liveness session with Azure AI Face Service. The service creates a liveness-session and responds back with a session-authorization-token. More information regarding each request parameter involved in creating a liveness session is referenced in [Liveness Create Session Operation](https://aka.ms/face-api-reference-createlivenesssession).

+1. The app server provides the session-authorization-token back to the frontend application.

+1. The frontend application provides the session-authorization-token during the Azure AI Vision SDKΓÇÖs initialization.

+ ```javascript

+ azureAIVisionFaceAnalyzer.token = "<INSERT_TOKEN_HERE>"

+ ```

+1. The frontend application relays the liveness check completion to the app server.

+ "fileName": "content.bin",

+ - The app server provides the reference image when creating the liveness session. More information regarding each request parameter involved in creating a liveness session with verification is referenced in [Liveness With Verify Create Session Operation](https://aka.ms/face-api-reference-createlivenesswithverifysession).

+ - The mobile application provides the reference image when initializing the SDK. This is not a supported scenario in the web solution.

+ --form 'Content=@"content.bin"' \

+ "fileName": "content.bin",

+- [JavaScript (Web)](https://aka.ms/azure-ai-vision-face-liveness-client-sdk-web-readme)

+- [Liveness Session Operations](/rest/api/face/liveness-session-operations)

+* Refer to the [Read API](/rest/api/computervision/operation-groups?view=rest-computervision-v3.2-preview) for details about the methods supported by the container.

+The background removal feature is available through the [Segment](/rest/api/computervision/image-analysis/segment?view=rest-computervision-2023-02-01-preview&tabs=HTTP) API (`imageanalysis:segment`). See the [Background removal how-to guide](./how-to/background-removal.md) for more information.

+The built-in logo database covers popular brands in consumer electronics, clothing, and more. If you find that the brand you're looking for isn't detected by the Azure AI Vision service, you could also try creating and training your own logo detector using the [Custom Vision](../custom-vision-service/index.yml) service.

+In some cases, the brand detector picks up both the logo image and the stylized brand name as two separate logos.

+The brand detection feature is part of the [Analyze Image](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2) API. You can call this API through a native SDK or through REST calls. Include `Brands` in the **visualFeatures** query parameter. Then, when you get the full JSON response, parse the string for the contents of the `"brands"` section.

+The categorization feature is part of the [Analyze Image 3.2](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2) API. You can call this API through a native SDK or through REST calls. Include `Categories` in the **visualFeatures** query parameter. Then, when you get the full JSON response, simply parse the string for the contents of the `"categories"` section.

+The image description feature is part of the [Analyze Image](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2) API. You can call this API through a native SDK or through REST calls. Include `Description` in the **visualFeatures** query parameter. Then, when you get the full JSON response, parse the string for the contents of the `"description"` section.

+You can detect adult content with the [Analyze Image 3.2](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2) API. When you add the value of `Adult` to the **visualFeatures** query parameter, the API returns three boolean properties&mdash;`isAdultContent`, `isRacyContent`, and `isGoryContent`&mdash;in its JSON response. The method also returns corresponding properties&mdash;`adultScore`, `racyScore`, and `goreScore`&mdash;which represent confidence scores between zero and one for each respective category.

+The color scheme detection feature is part of the [Analyze Image 3.2](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2) API. You can call this API through a native SDK or through REST calls. Include `Color` in the **visualFeatures** query parameter. Then, when you get the full JSON response, simply parse the string for the contents of the `"color"` section.

+In addition to tagging and high-level categorization, Azure AI Vision also supports further domain-specific analysis using models that are trained on specialized data.

+You can analyze an image using only the chosen domain-specific model by calling the [Models/\<model\>/Analyze](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2) API.

+The following is a sample JSON response returned by the `models/celebrities/analyze` API for the given image:

+You can also use domain-specific models to supplement general image analysis. You do this as part of [high-level categorization](concept-categorizing-images.md) by specifying domain-specific models in the *details* parameter of the [Analyze Image](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2) API call.

+Calling the [Models](/rest/api/computervision/list-models/list-models?view=rest-computervision-v3.2&tabs=HTTP) API returns this information along with the categories to which each model can apply:

+This feature is available through the [Analyze Image 3.2 API](/rest/api/computervision/analyze-image/analyze-image?view=rest-computervision-v3.2&tabs=HTTP). You can call this API through a native SDK or through REST calls. Include `Celebrities` or `Landmarks` in the **details** query parameter. Then, when you get the full JSON response, parse the string for the contents of the `"details"` section.

+The face detection feature is part of the [Analyze Image 3.2](/rest/api/computervision/analyze-image/analyze-image?view=rest-computervision-v3.2&tabs=HTTP) API. You can call this API through a native SDK or through REST calls. Include `Faces` in the **visualFeatures** query parameter. Then, when you get the full JSON response, simply parse the string for the contents of the `"faces"` section.

+With the [Analyze Image 3.2 API](/rest/api/computervision/analyze-image/analyze-image?view=rest-computervision-v3.2&tabs=HTTP), Azure AI Vision can analyze the content type of images and indicate whether an image is clip art or a line drawing.

+The image type detection feature is part of the [Analyze Image 3.2 API](/rest/api/computervision/analyze-image/analyze-image?view=rest-computervision-v3.2&tabs=HTTP). You can call this API through a native SDK or through REST calls. Include `ImageType` in the **visualFeatures** query parameter. Then, when you get the full JSON response, simply parse the string for the contents of the `"imageType"` section.

+You use the [Detect] API to detect faces in an image. To get started using the REST API or a client SDK, follow a [quickstart](./quickstarts-sdk/identity-client-library.md). Or, for a more in-depth guide, see [Call the detect API](./how-to/identity-detect-faces.md).

+The face ID is a unique identifier string for each detected face in an image. Face ID requires limited access approval, which you can apply for by filling out the [intake form](https://aka.ms/facerecognition). For more information, see the Face [limited access page](/legal/cognitive-services/computer-vision/limited-access-identity?context=%2Fazure%2Fcognitive-services%2Fcomputer-vision%2Fcontext%2Fcontext). You can request a face ID in your [Detect] API call.

+Attributes are a set of features that can optionally be detected by the [Detect] API. The following attributes can be detected:

+[Detect]: /rest/api/face/face-detection-operations/detect

+You need to create a [PersonGroup](/rest/api/face/person-group-operations/create-person-group) or [LargePersonGroup](/rest/api/face/person-group-operations/create-large-person-group) to store the set of people to match against. PersonGroups hold [Person](/rest/api/face/person-group-operations/create-person-group-person) objects, which each represent an individual person and hold a set of face data belonging to that person.

+The [Train](/rest/api/face/person-group-operations/train-person-group) operation prepares the data set to be used in face data comparisons.

+The [Identify](/rest/api/face/face-recognition-operations/identify-from-large-person-group) operation takes one or several source face IDs (from a DetectedFace or PersistedFace object) and a PersonGroup or LargePersonGroup. It returns a list of the Person objects that each source face might belong to. Returned Person objects are wrapped as Candidate objects, which have a prediction confidence value.

+The [Verify](/rest/api/face/face-recognition-operations/verify-face-to-face) operation takes a single face ID (from a DetectedFace or PersistedFace object) and a Person object. It determines whether the face belongs to that same person. Verification is one-to-one matching and can be used as a final check on the results from the Identify API call. However, you can optionally pass in the PersonGroup to which the candidate Person belongs to improve the API performance.

+The generate thumbnail feature is available through the [Get Thumbnail](/rest/api/computervision/generate-thumbnail/generate-thumbnail?view=rest-computervision-v3.2&tabs=HTTP) and [Get Area of Interest](/rest/api/computervision/get-area-of-interest/get-area-of-interest?view=rest-computervision-v3.2&tabs=HTTP) API. You can call this API through a native SDK or through REST calls.

+Object detection is similar to [tagging](concept-tag-images-40.md), but the API returns the bounding box coordinates (in pixels) for each object found in the image. For example, if an image contains a dog, cat, and person, the object detection operation lists those objects with their coordinates in the image. You can use this functionality to process the relationships between the objects in an image. It also lets you determine whether there are multiple instances of the same object in an image.

+The object detection function applies tags based on the objects or living things identified in the image. There's no formal relationship between the tagging taxonomy and the object detection taxonomy. At a conceptual level, the object detection function only finds objects and living things, while the tag function can also include contextual terms like "indoor," which can't be localized with bounding boxes.

+The following JSON response illustrates what the Analyze Image API returns when detecting objects in the example image.

+* Objects are usually not detected if they're small (less than 5% of the image).

+* Objects are usually not detected if they're arranged closely together (a stack of plates, for example).

+* Objects aren't differentiated by brand or product names (different types of sodas on a store shelf, for example). However, you can get brand information from an image by using the [Brand detection](concept-brand-detection.md) feature.

+The object detection feature is part of the [Analyze Image](/rest/api/computervision/analyze-image/analyze-image?view=rest-computervision-v3.2&tabs=HTTP) API. You can call this API through a native SDK or through REST calls. Include `Objects` in the **visualFeatures** query parameter. Then, when you get the full JSON response, parse the string for the contents of the `"objects"` section.

+* [API reference](/rest/api/computervision/operation-groups?view=rest-computervision-2023-04-01-preview)

+The tagging feature is part of the [Analyze Image](/rest/api/computervision/analyze-image/analyze-image?view=rest-computervision-v3.2&tabs=HTTP) API. You can call this API through a native SDK or through REST calls. Include `Tags` in the **visualFeatures** query parameter. Then, when you get the full JSON response, parse the string for the contents of the `"tags"` section.

+> Some of the features in Image Analysis can be called directly as well as through the Analyze API call. For example, you can do a scoped analysis of only image tags by making a request to `<endpoint>/vision/v3.2/tag` (or to the corresponding method in the SDK). See the [reference documentation](/rest/api/computervision/operation-groups?view=rest-computervision-v3.2) for other features that can be called separately.

+By default, the service extracts all text from your images or documents including mixed languages. The [Read operation](/rest/api/computervision/read/read?view=rest-computervision-v3.2-preview&tabs=HTTP) has an optional request parameter for language. Only provide a language code if you want to force the document to be processed as that specific language. Otherwise, the service may return incomplete and incorrect text.

+The Read API's [Read call](/rest/api/computervision/read/read?view=rest-computervision-v3.2-preview&tabs=HTTP) takes an image or PDF document as the input and extracts text asynchronously.

+The second step is to call [Get Read Result](/rest/api/computervision/get-read-result/get-read-result?view=rest-computervision-v3.2-preview&tabs=HTTP) operation. This operation takes as input the operation ID that was created by the Read operation.

+- [Read 3.2 REST API reference](/rest/api/computervision/read/read?view=rest-computervision-v3.2-preview&tabs=HTTP).

+The [Find Similar](/rest/api/face/face-recognition-operations/find-similar-from-large-face-list) operation does face matching between a target face and a set of candidate faces, finding a smaller set of faces that look similar to the target face. This is useful for doing a face search by image.

+The limited access token feature is a part of the existing Azure AI Services token service. We have added a new operation for the purpose of bypassing the Limited Access gate for approved scenarios. Only ISVs that pass the gating requirements will be given access to this feature.

+* [cURL](https://curl.se/) installed (or another tool that can make HTTP requests).

+* The ISV needs to have either an [Azure AI Face](https://portal.azure.com/#view/Microsoft_Azure_ProjectOxford/CognitiveServicesHub/~/Face) resource or an [Azure AI services multi-service](https://portal.azure.com/#view/Microsoft_Azure_ProjectOxford/CognitiveServicesHub/~/AllInOne) resource.

+* The client needs to have an [Azure AI Face](https://portal.azure.com/#view/Microsoft_Azure_ProjectOxford/CognitiveServicesHub/~/Face) resource.

+The code snippets in this guide are written in C# by using the Azure AI Face client library. The same functionality is available through the [REST API](/rest/api/face/face-detection-operations/detect).

+- [Reference documentation (REST)](/rest/api/face/operation-groups)

+> These APIs are only available in the following geographic regions: SwedenCentral, EastUS, NorthEurope, WestEurope,WestUS, SoutheastAsia, KoreaCentral, FranceCentral, AustraliaEast, WestUS2, SwitzerlandNorth, JapanEast.

+* Once you have your Azure subscription, <a href="https://portal.azure.com/#create/Microsoft.CognitiveServicesComputerVision" title="Create a Computer Vision resource" target="_blank">create a Computer Vision resource </a> in the Azure portal to get your key and endpoint. Be sure to create it in one of the permitted geographic regions: SwedenCentral, EastUS, NorthEurope, WestEurope,WestUS, SoutheastAsia, KoreaCentral, FranceCentral, AustraliaEast, WestUS2, SwitzerlandNorth, JapanEast.

+* [API reference](/rest/api/computervision/operation-groups?view=rest-computervision-2023-04-01-preview)

+* [API reference](/rest/api/computervision/operation-groups?view=rest-computervision-2023-04-01-preview)

+* [API reference](/rest/api/computervision/operation-groups?view=rest-computervision-2023-04-01-preview)

+|**detection_03** | Released in February 2021 and available optionally in all face detection operations. | Further improved accuracy, including on smaller faces (64x64 pixels) and rotated face orientations. | Returns mask, blur, and head pose attributes if they're specified in the detect call. | Returns face landmarks if they're specified in the detect call. |

+The best way to compare the performances of the detection models is to use them on a sample dataset. We recommend calling the [Detect] API on a variety of images, especially images of many faces or of faces that are difficult to see, using each detection model. Pay attention to the number of faces that each model returns.

+When you use the [Detect] API, you can assign the model version with the `detectionModel` parameter. The available values are:

+A request URL for the [Detect] REST API will look like this:

+string imageUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/detection1.jpg";

+The Face service can extract face data from an image and associate it with a **Person** object through the [Add Person Group Person Face] API. In this API call, you can specify the detection model in the same way as in [Detect].

+string imageUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/detection1.jpg";

+> You don't need to use the same detection model for all faces in a **Person** object, and you don't need to use the same detection model when detecting new faces to compare with a **Person** object (in the [Identify From Person Group] API, for example).

+string imageUrl = "https://raw.githubusercontent.com/Azure-Samples/cognitive-services-sample-data-files/master/Face/images/detection1.jpg";

+[Detect]: /rest/api/face/face-detection-operations/detect

+[Identify From Person Group]: /rest/api/face/face-recognition-operations/identify-from-person-group

+[Add Person Group Person Face]: /rest/api/face/person-group-operations/add-person-group-person-face

+When using the [Detect] API, assign the model version with the `recognitionModel` parameter. The available values are:

+Optionally, you can specify the _returnRecognitionModel_ parameter (default **false**) to indicate whether _recognitionModel_ should be returned in response. So, a request URL for the [Detect] REST API will look like this:

+The Face service can extract face data from an image and associate it with a **Person** object (through the [Add Person Group Person Face] API call, for example), and multiple **Person** objects can be stored together in a **PersonGroup**. Then, a new face can be compared against a **PersonGroup** (with the [Identify From Person Group] call), and the matching person within that group can be identified.

+A **PersonGroup** should have one unique recognition model for all of the **Person**s, and you can specify this using the `recognitionModel` parameter when you create the group ([Create Person Group] or [Create Large Person Group]). If you don't specify this parameter, the original `recognition_01` model is used. A group will always use the recognition model it was created with, and new faces will become associated with this model when they're added to it. This can't be changed after a group's creation. To see what model a **PersonGroup** is configured with, use the [Get Person Group] API with the _returnRecognitionModel_ parameter set as **true**.

+Correspondingly, you need to specify which model to use when detecting faces to compare against this **PersonGroup** (through the [Detect] API). The model you use should always be consistent with the **PersonGroup**'s configuration; otherwise, the operation will fail due to incompatible models.

+There is no change in the [Identify From Person Group] API; you only need to specify the model version in detection.

+You can also specify a recognition model for similarity search. You can assign the model version with `recognitionModel` when creating the **FaceList** with [Create Face List] API or [Create Large Face List]. If you don't specify this parameter, the `recognition_01` model is used by default. A **FaceList** will always use the recognition model it was created with, and new faces will become associated with this model when they're added to the list; you can't change this after creation. To see what model a **FaceList** is configured with, use the [Get Face List] API with the _returnRecognitionModel_ parameter set as **true**.

+This code creates a **FaceList** called `My face collection`, using the _recognition_04_ model for feature extraction. When you search this **FaceList** for similar faces to a new detected face, that face must have been detected ([Detect]) using the _recognition_04_ model. As in the previous section, the model needs to be consistent.

+There is no change in the [Find Similar] API; you only specify the model version in detection.

+The [Verify Face To Face] API checks whether two faces belong to the same person. There is no change in the Verify API with regard to recognition models, but you can only compare faces that were detected with the same model.

+1. Train your **PersonGroup**s using the [Train Person Group] API.

+1. Test with [Identify From Person Group] on all four **PersonGroup**s and compare the results.

+[Detect]: /rest/api/face/face-detection-operations/detect

+[Verify Face To Face]: /rest/api/face/face-recognition-operations/verify-face-to-face

+[Identify From Person Group]: /rest/api/face/face-recognition-operations/identify-from-person-group

+[Find Similar]: /rest/api/face/face-recognition-operations/find-similar-from-large-face-list

+[Create Person Group]: /rest/api/face/person-group-operations/create-person-group

+[Get Person Group]: /rest/api/face/person-group-operations/get-person-group

+[Train Person Group]: /rest/api/face/person-group-operations/train-person-group

+[Add Person Group Person Face]: /rest/api/face/person-group-operations/add-person-group-person-face

+[Create Large Person Group]: /rest/api/face/person-group-operations/create-large-person-group

+[Create Face List]: /rest/api/face/face-list-operations/create-face-list

+[Get Face List]: /rest/api/face/face-list-operations/get-face-list

+[Create Large Face List]: /rest/api/face/face-list-operations/create-large-face-list

+This guide demonstrates the migration process. It assumes a basic familiarity with **PersonGroup** and **FaceList** objects, the **Train** operation, and the face recognition functions. To learn more about these subjects, see the [face recognition](../concept-face-recognition.md) conceptual guide.

+The preceding table is a comparison of list-level operations between **FaceList** and **LargeFaceList**. As is shown, **LargeFaceList** comes with new operations, [Train](/rest/api/face/face-list-operations/train-large-face-list) and [Get Training Status](/rest/api/face/face-list-operations/get-large-face-list-training-status), when compared with **FaceList**. Training the **LargeFaceList** is a precondition of the

+[FindSimilar](/rest/api/face/face-recognition-operations/find-similar-from-large-face-list) operation. Training isn't required for **FaceList**. The following snippet is a helper function to wait for the training of a **LargeFaceList**:

+ await FaceClient.LargeFaceList.TrainAsync(largeFaceListId);

+ await Task.Delay(timeIntervalInMilliseconds);

+ var status = await faceClient.LargeFaceList.GetTrainingStatusAsyn(largeFaceListId);

+await faceClient.FaceList.CreateAsync(FaceListId, FaceListName);

+ var faces = await faceClient.Face.DetectWithStreamAsync(stream);

+await faceClient.LargeFaceList.CreateAsync(LargeFaceListId, LargeFaceListName);

+ var faces = await faceClient.Face.DetectWithStreamAsync(stream);

+Although the **Train** operation speeds up [FindSimilar](/rest/api/face/face-recognition-operations/find-similar-from-large-face-list)

+and [Identification](/rest/api/face/face-recognition-operations/identify-from-large-person-group), the training time suffers, especially when coming to large scale. The estimated training time in different scales is listed in the following table.

+var addPersonUri = "https://{endpoint}/face/v1.0-preview/persons";

+ await Task.Delay(500);

+- Face Algorithm APIs: Cover core functions such as [Detection](/rest/api/face/face-detection-operations/detect), [Find Similar](/rest/api/face/face-recognition-operations/find-similar-from-large-face-list), [Verification](/rest/api/face/face-recognition-operations/verify-face-to-face), [Identification](/rest/api/face/face-recognition-operations/identify-from-large-person-group), and [Group](/rest/api/face/face-recognition-operations/group).

+- [DetectLiveness session APIs](/rest/api/face/liveness-session-operations): Used to create and manage a Liveness Detection session. See the [Liveness Detection](/azure/ai-services/computer-vision/tutorials/liveness) tutorial.

+- [FaceList APIs](/rest/api/face/face-list-operations): Used to manage a FaceList for [Find Similar From Face List](/rest/api/face/face-recognition-operations/find-similar-from-face-list).

+- [LargeFaceList APIs](/rest/api/face/face-list-operations): Used to manage a LargeFaceList for [Find Similar From Large Face List](/rest/api/face/face-recognition-operations/find-similar-from-large-face-list).

+- [PersonGroup APIs](/rest/api/face/person-group-operations): Used to manage a PersonGroup dataset for [Identification From Person Group](/rest/api/face/face-recognition-operations/identify-from-person-group).

+- [LargePersonGroup APIs](/rest/api/face/person-group-operations): Used to manage a LargePersonGroup dataset for [Identification From Large Person Group](/rest/api/face/face-recognition-operations/identify-from-large-person-group).

+- [PersonDirectory APIs](/rest/api/face/person-directory-operations): Used to manage a PersonDirectory dataset for [Identification From Person Directory](/rest/api/face/face-recognition-operations/identify-from-person-directory) or [Identification From Dynamic Person Group](/rest/api/face/face-recognition-operations/identify-from-dynamic-person-group).

+- [Face API error codes](./reference-face-error-codes.md): A list of all error codes returned by the Face API operations.

+Some features of the [Analyze - Image](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2) API can return results in other languages, specified with the `language` query parameter. Other actions return results in English regardless of what language is specified, and others throw an exception for unsupported languages. Actions are specified with the `visualFeatures` and `details` query parameters; see the [Overview](overview-image-analysis.md) for a list of all the actions you can do with the Analyze API, or follow the [How-to guide](/azure/ai-services/computer-vision/how-to/call-analyze-image-40) to try them out.

+For more information on face detection and analysis, see the [Face detection](concept-face-detection.md) concepts article. Also see the [Detect API](/rest/api/face/face-detection-operations/detect) reference documentation.

+- [JavaScript (Web)](https://aka.ms/liveness-sdk-web)

+For more information about Face recognition, see the [Facial recognition](concept-face-recognition.md) concepts guide or the [Identify](/rest/api/face/face-recognition-operations/identify-from-large-person-group) and [Verify](/rest/api/face/face-recognition-operations/verify-face-to-face) API reference documentation.

+The service supports two working modes, **matchPerson** and **matchFace**. The **matchPerson** mode returns similar faces after filtering for the same person by using the [Verify API](/rest/api/face/face-recognition-operations/verify-face-to-face). The **matchFace** mode ignores the same-person filter. It returns a list of similar candidate faces that may or may not belong to the same person.

+To find four similar faces, the **matchPerson** mode returns A and B, which show the same person as the target face. The **matchFace** mode returns A, B, C, and D, which is exactly four candidates, even if some aren't the same person as the target or have low similarity. For more information, see the [Facial recognition](concept-face-recognition.md) concepts guide or the [Find Similar API](/rest/api/face/face-recognition-operations/find-similar-from-large-face-list) reference documentation.

+All of the faces in a returned group are likely to belong to the same person, but there can be several different groups for a single person. Those groups are differentiated by another factor, such as expression, for example. For more information, see the [Facial recognition](concept-face-recognition.md) concepts guide or the [Group API](/rest/api/face/face-recognition-operations/group) reference documentation.

+> The Azure AI Vision legacy [OCR API in v3.2](/rest/api/computervision/recognize-printed-text?view=rest-computervision-v3.2) and [RecognizeText API in v2.1](/rest/api/computervision/recognize-printed-text/recognize-printed-text?view=rest-computervision-v2.1) operations are not recommended for use.

+* Refer to the [Read API](/rest/api/computervision/read/read?view=rest-computervision-v3.2-preview&tabs=HTTP) for details about the methods supported by the container.

+ Title: Azure AI Face API error codes

+description: Error codes returned from Face API services.

+# Azure AI Face API error codes

+## Common error codes

+These error codes can be returned by any Face API calls.

+|Http status code|Error code|Error message|Description|

+|-|-|-|--|

+|Bad Request (400)|BadArgument|Request body is invalid.||

+|Bad Request (400)|BadArgument|JSON parsing error.|Bad or unrecognizable request JSON body.|

+|Bad Request (400)|BadArgument|'recognitionModel' is invalid.||

+|Bad Request (400)|BadArgument|'detectionModel' is invalid.||

+|Bad Request (400)|BadArgument|'name' is empty.||

+|Bad Request (400)|BadArgument|'name' is too long.||

+|Bad Request (400)|BadArgument|'userData' is too long.||

+|Bad Request (400)|BadArgument|'start' is too long.||

+|Bad Request (400)|BadArgument|'top' is invalid.||

+|Bad Request (400)|BadArgument|Argument targetFace out of range.||

+|Bad Request (400)|BadArgument|Invalid argument targetFace.|Caused by invalid string format or invalid left/top/height/width value.|

+|Bad Request (400)|InvalidURL|Invalid image URL.|Supported formats include JPEG, PNG, GIF(the first frame) and BMP.|

+|Bad Request (400)|InvalidURL|Invalid image URL or error downloading from target server. Remote server error returned: "An error occurred while sending the request."||

+|Bad Request (400)|InvalidImage|Decoding error, image format unsupported.||

+|Bad Request (400)|InvalidImage|No face detected in the image.||

+|Bad Request (400)|InvalidImage|There is more than 1 face in the image.||

+|Bad Request (400)|InvalidImageSize|Image size is too small.|The valid image file size should be larger than or equal to 1 KB.|

+|Bad Request (400)|InvalidImageSize|Image size is too big.|The valid image file size should be no larger than 6 MB.|

+|Unauthorized (401)|401|Access denied due to invalid subscription key or wrong API endpoint. Make sure to provide a valid key for an active subscription and use a correct regional API endpoint for your resource.||

+|Conflict (409)|ConcurrentOperationConflict|There is a conflict operation on resource `<resourceName>`, please try later.||

+|Too Many Requests (429)|429|Rate limit is exceeded.||

+## Face Detection error codes

+These error codes can be returned by Face Detection operation.

+|Http status code|Error code|Error message|Description|

+|||||

+|Bad Request (400)|BadArgument|Invalid argument returnFaceAttributes.||

+|Bad Request (400)|BadArgument|'returnFaceAttributes' is not supported by detection_02.||

+|Bad Request (400)|BadArgument|'returnLandmarks' is not supported by detection_02.||

+## Face Liveness Session error codes

+These error codes can be returned by Face Liveness Session operations.

+|Http status code|Error code|Error message|Description|

+|||||

+|Bad Request (400)|BadArgument|Start parameter is invalid. Please specify the 'Id' field of the last entry to continue the listing process.||

+|Bad Request (400)|BadArgument|Top parameter is invalid. Valid range is between 1 and 1000 inclusive.||

+|Bad Request (400)|InvalidRequestBody|Incorrect request body provided. Please check the operation schema and try again.||

+|Bad Request (400)|InvalidTokenLifetime|Invalid authTokenTimeToLiveInSeconds specified. Must be within 60 to 86400.||

+|Bad Request (400)|InvalidLivenessOperationMode|Invalid livenessOperationMode specified. Must be 'Passive'.||

+|Bad Request (400)|InvalidDeviceCorrelationId|A device correlation ID is required in the request body during session create or session start. Must not be null or empty, and be no more than 64 characters.||

+|Not Found (404)|SessionNotFound|Session ID is not found. The session ID is expired or does not exist.||

+## Face Identify error codes

+These error codes can be returned by Face Identify operation.

+|Http status code|Error code|Error message|Description|

+|||||

+|Bad Request (400)|BadArgument|'recognitionModel' is incompatible.||

+|Bad Request (400)|BadArgument|Person group ID is invalid.||

+|Bad Request (400)|BadArgument|Large person group ID is invalid.||

+|Bad Request (400)|BadArgument|Dynamic person group ID is invalid.||

+|Bad Request (400)|BadArgument|The argument maxNumOfCandidatesReturned is not valid.|The valid range is between [1, 100].|

+|Bad Request (400)|BadArgument|The argument confidenceThreshold is not valid.|The valid range is between [0, 1].|

+|Bad Request (400)|BadArgument|The length of faceIds is not in a valid range.|The valid range is between [1, 10].|

+|Bad Request (400)|FaceNotFound|Face is not found.||

+|Bad Request (400)|PersonGroupNotFound|Person group is not found.||

+|Bad Request (400)|LargePersonGroupNotFound|Large person group is not found.||

+|Bad Request (400)|DynamicPersonGroupNotFound|Dynamic person group is not found.||

+|Bad Request (400)|PersonGroupNotTrained|Person group not trained.||

+|Bad Request (400)|LargePersonGroupNotTrained|Large person group not trained.||

+|Bad Request (400)|PersonGroupIdAndLargePersonGroupIdBothNotNull|Large person group ID and person group ID are both not null.||

+|Bad Request (400)|PersonGroupIdAndLargePersonGroupIdBothNull|Large person group ID and person group ID are both null.||

+|Bad Request (400)|MissingIdentificationScopeParameters|No identification scope parameter is present in the request.||

+|Bad Request (400)|IncompatibleIdentificationScopeParametersCombination|Incompatible identification scope parameters are present in the request.||

+|Conflict (409)|PersonGroupTrainingNotFinished|Person group is under training.||

+|Conflict (409)|LargePersonGroupTrainingNotFinished|Large person group is under training.||

+## Face Verify error codes

+These error codes can be returned by Face Verify operation.

+|Http status code|Error code|Error message|Description|

+|||||

+|Bad Request (400)|BadArgument|'recognitionModel' is incompatible.||

+|Bad Request (400)|BadArgument|Face ID is invalid.|A valid faceId comes from Face - Detect.|

+|Bad Request (400)|BadArgument|Person ID is invalid.|A valid personId is generated from Create Person Group Person, Create Large Person Group Person or Person Directory - Create Person.|

+|Bad Request (400)|BadArgument|Person group ID is invalid.||

+|Bad Request (400)|BadArgument|Large person group ID is invalid.||

+|Bad Request (400)|PersonNotFound|Person is not found.||

+|Bad Request (400)|PersonGroupNotFound|Person Group is not found.||

+|Bad Request (400)|LargePersonGroupNotFound|Large Person Group is not found.||

+|Not Found (404)|FaceNotFound|Face is not found.||

+|Not Found (404)|PersonNotFound|Person is not found.||

+|Not Found (404)|PersistedFaceNotFound|No persisted face of the person is found.||

+## Find Similar error codes

+These error codes can be returned by Face Find Similar operation.

+|Http status code|Error code|Error message|Description|

+|||||

+|Bad Request (400)|BadArgument|'recognitionModel' is incompatible.||

+|Bad Request (400)|BadArgument|Mode is invalid.||

+|Bad Request (400)|BadArgument|Face list ID is invalid.||

+|Bad Request (400)|BadArgument|Large face list ID is invalid.||

+|Bad Request (400)|BadArgument|LargeFaceListId, faceListId and faceIds, not exactly one of them is valid.||

+|Bad Request (400)|BadArgument|LargeFaceListId, faceListId and faceIds are all null.||

+|Bad Request (400)|BadArgument|2 or more of largeFaceListId, faceListId and faceIds are not null.||

+|Bad Request (400)|BadArgument|The argument maxNumOfCandidatesReturned is not valid.|The valid range is between [1, 1000].|

+|Bad Request (400)|BadArgument|The length of faceIds is not in a valid range.|The valid range is between [1, 1000].|

+|Bad Request (400)|FaceNotFound|Face is not found.||

+|Bad Request (400)|FaceListNotFound|Face list is not found.||

+|Bad Request (400)|LargeFaceListNotFound|Large face list is not found.||

+|Bad Request (400)|LargeFaceListNotTrained|Large face list is not trained.||

+|Bad Request (400)|FaceListNotReady|Face list is empty.||

+|Conflict (409)|LargeFaceListTrainingNotFinished|Large face list is under training.||

+## Face Group error codes

+These error codes can be returned by Face Group operation.

+|Http status code|Error code|Error message|Description|

+|||||

+|Bad Request (400)|BadArgument|'recognitionModel' is incompatible.||

+|Bad Request (400)|BadArgument|The length of faceIds is not in a valid range.|The valid range is between [2, 1000].|

+## Person Group operations

+These error codes can be returned by Person Group operations.

+### Person Group error codes

+|Http status code|Error code|Error message|Description|

+|||||

+|Bad Request (400)|BadArgument|Person group ID is invalid.|Valid character is English letter in lower case, digit, '-' or '_'. Maximum length is 64.|

+|Forbidden (403)|QuotaExceeded|Person group number reached subscription level limit.||

+|Forbidden (403)|QuotaExceeded|Person number reached person group level limit.||

+|Forbidden (403)|QuotaExceeded|Person number reached subscription level limit.||

+|Forbidden (403)|QuotaExceeded|Persisted face number reached limit.||

+|Not Found (404)|PersonGroupNotFound|Person group is not found.||

+|Not Found (404)|PersonGroupNotFound|Person group ID is invalid.||

+|Not Found (404)|PersonNotFound|Person `<personId>` is not found.||

+|Not Found (404)|PersonNotFound|Person ID is invalid.||

+|Not Found (404)|PersistedFaceNotFound|Persisted face is not found.||

+|Not Found (404)|PersistedFaceNotFound|Persisted face `<faceId>` is not found.||

+|Not Found (404)|PersistedFaceNotFound|Persisted face ID is invalid.||

+|Not Found (404)|PersonGroupNotTrained|Person group not trained.|This error appears on getting training status of a group which never been trained.|

+|Conflict (409)|PersonGroupExists|Person group already exists.||

+|Conflict (409)|PersonGroupTrainingNotFinished|Person group is under training.|Try again after training completed.|

+### Large Person Group error codes

+|Http status code|Error code|Error message|Description|

+|||||

+|Bad Request (400)|BadArgument|Large person group ID is invalid.|Valid character is English letter in lower case, digit, '-' or '_'. Maximum length is 64.|

+|Bad Request (400)|BadArgument|Both 'name' and 'userData' are empty.||

+|Forbidden (403)|QuotaExceeded|Large person group number reached subscription level limit.||

+|Forbidden (403)|QuotaExceeded|Person number reached large person group level limit.||

+|Forbidden (403)|QuotaExceeded|Person number reached subscription level limit.||

+|Forbidden (403)|QuotaExceeded|Persisted face number reached limit.||

+|Not Found (404)|LargePersonGroupNotFound|Large person group is not found.||

+|Not Found (404)|LargePersonGroupNotFound|Large person group ID is invalid.||

+|Not Found (404)|PersonNotFound|Person `<personId>` is not found.||

+|Not Found (404)|PersonNotFound|Person ID is invalid.||

+|Not Found (404)|PersistedFaceNotFound|Persisted face is not found.||

+|Not Found (404)|PersistedFaceNotFound|Persisted face `<faceId>` is not found.||

+|Not Found (404)|PersistedFaceNotFound|Persisted face ID is invalid.||

+|Not Found (404)|LargePersonGroupNotTrained|Large person group not trained.|This error appears on getting training status of a group which never been trained.|

+|Conflict (409)|LargePersonGroupExists|Large person group already exists.||

+|Conflict (409)|LargePersonGroupTrainingNotFinished|Large person group is under training.|Try again after training completed.|

+## Face List operations

+These error codes can be returned by Face List operations.

+### Face List error codes

+|Http status code|Error code|Error message|Description|

+|||||

+|Bad Request (400)|BadArgument|Face list ID is invalid.|Valid character is English letter in lower case, digit, '-' or '_'. Maximum length is 64.|

+|Forbidden (403)|QuotaExceeded|Persisted face number reached limit.||

+|Not Found (404)|FaceListNotFound|Face list is not found.||

+|Not Found (404)|FaceListNotFound|Face list ID is invalid.||

+|Not Found (404)|PersistedFaceNotFound|Persisted face is not found.||

+|Not Found (404)|PersistedFaceNotFound|Persisted face ID is invalid.||

+|Conflict (409)|FaceListExists|Face list already exists.||

+### Large Face List error codes

+|Http status code|Error code|Error message|Description|

+|||||

+|Bad Request (400)|BadArgument|Large face list ID is invalid.|Valid character is English letter in lower case, digit, '-' or '_'. Maximum length is 64.|

+|Bad Request (400)|BadArgument|Both 'name' and 'userData' are empty.||

+|Forbidden (403)|QuotaExceeded|Large Face List number reached limit.||

+|Forbidden (403)|QuotaExceeded|Persisted face number reached limit.||

+|Not Found (404)|LargeFaceListNotFound|Large face list is not found.||

+|Not Found (404)|LargeFaceListNotFound|Large face list ID is invalid.||

+|Not Found (404)|PersistedFaceNotFound|Large Face List Face `<faceId>` is not found.||

+|Not Found (404)|PersistedFaceNotFound|Persisted face ID is invalid.||

+|Not Found (404)|LargeFaceListNotTrained|Large face list not trained.|This error appears on getting training status of a large face list which never been trained.|

+|Conflict (409)|LargeFaceListExists|Large face list already exists.||

+|Conflict (409)|LargeFaceListTrainingNotFinished|Large face list is under training.|Try again after training completed.|

+## Person Directory operations

+These error codes can be returned by Person Directory operations.

+### Person Directory error codes

+|Http status code|Error code|Error message|Description|

+|||||

+|Bad Request (400)|BadArgument|Recognition model is not supported for this feature.||

+|Bad Request (400)|BadArgument|'start' is not valid person ID.||

+|Bad Request (400)|BadArgument|Both 'name' and 'userData' are empty.||

+|Bad Request (400)|DynamicPersonGroupNotFound|Dynamic person group ID is invalid.||

+|Forbidden (403)|QuotaExceeded|Person number reached subscription level limit.||

+|Forbidden (403)|QuotaExceeded|Persisted face number reached limit.||

+|Not Found (404)|DynamicPersonGroupNotFound|Dynamic person group was not found.||

+|Not Found (404)|DynamicPersonGroupNotFound|DynamicPersonGroupPersonReference `<groupId>` is not found.||

+|Not Found (404)|PersonNotFound|Person is not found.||

+|Not Found (404)|PersonNotFound|Person ID is invalid.||

+|Not Found (404)|PersistedFaceNotFound|Persisted face is not found.||

+|Not Found (404)|PersistedFaceNotFound|Persisted face `<faceId>` is not found.||

+|Not Found (404)|PersistedFaceNotFound|Persisted Face ID is invalid.||

+|Conflict (409)|DynamicPersonGroupExists|Dynamic person group ID `<groupId>` already exists.||

+Next steps

+- [Face API reference](/rest/api/face/operation-groups)

+> - The SDK now calls the generally available [Computer Vision REST API (2023-10-01)](/rest/api/computervision/operation-groups?view=rest-computervision-2023-10-01), instead of the preview [Computer Vision REST API (2023-04-01-preview)](/rest/api/computervision/operation-groups?view=rest-computervision-2023-04-01-preview).

+> - Image Analysis with a custom model, and Image Segmentation (background removal) are no longer supported in the SDK, because the [Computer Vision REST API (2023-10-01)](/rest/api/computervision/operation-groups?view=rest-computervision-2023-10-01) does not yet support them. To use either feature, call the [Computer Vision REST API (2023-04-01-preview)](/rest/api/computervision/operation-groups?view=rest-computervision-2023-04-01-preview) directly (using the `Analyze` and `Segment` operations respectively).

+- The SDK now calls the generally available [Computer Vision REST API (2023-10-01)](/rest/api/computervision/operation-groups?view=rest-computervision-2023-10-01), instead of the preview [Computer Vision REST API (2023-04-01-preview)](/rest/api/computervision/operation-groups?view=rest-computervision-2023-04-01-preview).

+- Image Analysis with a custom model, and Image Segmentation (background removal) are no longer supported in the SDK, because the [Computer Vision REST API (2023-10-01)](/rest/api/computervision/operation-groups?view=rest-computervision-2023-10-01) doesn't yet support them. To use either feature, call the [Computer Vision REST API (2023-04-01-preview)](/rest/api/computervision/operation-groups?view=rest-computervision-2023-04-01-preview) directly (using the `Analyze` and `Segment` operations respectively).

+- The [Analyze Image](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2) and [Read](/rest/api/computervision/recognize-printed-text?view=rest-computervision-v3.2) API calls take an optional _model-version_ parameter that you can use to specify which AI model to use. By default, they use the latest model.

+- The [Analyze Image](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2) and [Read](/rest/api/computervision/recognize-printed-text?view=rest-computervision-v3.2) API calls also return a `model-version` field in successful API responses. This field reports which model was used.

+- Azure AI Vision 3.2 API uses a different error-reporting format. See the [API reference documentation](/rest/api/computervision/operation-groups?view=rest-computervision-v3.2) to learn how to adjust any error-handling code.

+1. The [Analyze Image](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2) and [Read](/rest/api/computervision/recognize-printed-text?view=rest-computervision-v3.2) API calls now take an optional _model-version_ parameter that you can use to specify which AI model to use. By default, they use the latest model.

+1. The [Analyze Image](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2) and [Read](/rest/api/computervision/recognize-printed-text?view=rest-computervision-v3.2) API calls also return a `model-version` field in successful API responses. This field reports which model was used.

+1. Image Analysis APIs now use a different error-reporting format. See the [API reference documentation](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2) to learn how to adjust any error-handling code.

+The [latest version (v3.2)](/rest/api/computervision/operation-groups?view=rest-computervision-v3.2) of the Image tagger now supports tags in 50 languages. See the [language support](language-support.md) page for more information.

+* Improved image tagging model: analyzes visual content and generates relevant tags based on objects, actions, and content displayed in the image. This model is available through the [Tag Image API](/rest/api/computervision/operation-groups?view=rest-computervision-v3.2). See the Image Analysis [how-to guide](./how-to/call-analyze-image.md) and [overview](./overview-image-analysis.md) to learn more.

+* Updated content moderation model: detects presence of adult content and provides flags to filter images containing adult, racy, and gory visual content. This model is available through the [Analyze API](/rest/api/computervision/analyze-image?view=rest-computervision-v3.2). See the Image Analysis [how-to guide](./how-to/call-analyze-image.md) and [overview](./overview-image-analysis.md) to learn more.

+> [See Azure AI Vision v3.2 GA](/rest/api/computervision/recognize-printed-text?view=rest-computervision-v3.2)

+> [See Azure AI Vision v3.2 public preview 3](/rest/api/computervision/operation-groups?view=rest-computervision-v3.2-preview)

+> [Use the Read API v3.2 Public Preview](/rest/api/computervision/operation-groups?view=rest-computervision-v3.2-preview)

+* While the Face Service does not store customer images, the extracted face feature(s) will be stored on server. The Face ID is an identifier of the face feature and will be used in [Face - Identify](/rest/api/face/face-recognition-operations/identify-from-dynamic-person-group), [Face - Verify](/rest/api/face/face-recognition-operations/verify-face-to-face), and [Face - Find Similar](/rest/api/face/face-recognition-operations/find-similar). The stored face features will expire and be deleted 24 hours after the original detection call. Customers can now determine the length of time these Face IDs are cached. The maximum value is still up to 24 hours, but a minimum value of 60 seconds can now be set. The new time ranges for Face IDs being cached is any value between 60 seconds and 24 hours. More details can be found in the [Face - Detect](/rest/api/face/face-detection-operations) API reference (the *faceIdTimeToLive* parameter).

+> [Learn more about Read API v3.1 Public Preview 2](/rest/api/computervision/operation-groups?view=rest-computervision-v3.1-preview)

+> [Learn more about Read API v3.1 Public Preview 1](/rest/api/computervision/operation-groups?view=rest-computervision-v3.1-preview)

+* The new Detection 02 model features improved accuracy on small, side-view, occluded, and blurry faces. Use it through [Face - Detect](/rest/api/face/face-detection-operations), [FaceList - Add Face](/rest/api/face/face-list-operations/add-face-list-face), [LargeFaceList - Add Face](/rest/api/face/face-list-operations/add-large-face-list-face), [PersonGroup Person - Add Face](/rest/api/face/person-group-operations/add-person-group-person-face) and [LargePersonGroup Person - Add Face](/rest/api/face/person-group-operations/add-large-person-group-person-face) by specifying the new face detection model name `detection_02` in `detectionModel` parameter. More details in [How to specify a detection model](how-to/specify-detection-model.md).

+* Improved overall accuracy of the `age` and `headPose` attributes. The `headPose` attribute is also updated with the `pitch` value enabled now. Use these attributes by specifying them in the `returnFaceAttributes` parameter of [Face - Detect](/rest/api/face/face-detection-operations) `returnFaceAttributes` parameter.

+* Improved speeds of [Face - Detect](/rest/api/face/face-detection-operations), [FaceList - Add Face](/rest/api/face/face-list-operations/add-face-list-face), [LargeFaceList - Add Face](/rest/api/face/face-list-operations/add-large-face-list-face), [PersonGroup Person - Add Face](/rest/api/face/person-group-operations/add-person-group-person-face) and [LargePersonGroup Person - Add Face](/rest/api/face/person-group-operations/add-large-person-group-person-face) operations.

+* The Recognition 02 model has improved accuracy. Use it through [Face - Detect](/rest/api/face/face-detection-operations), [FaceList - Create](/rest/api/face/face-list-operations/create-face-list), [LargeFaceList - Create](/rest/api/face/face-list-operations/create-large-face-list), [PersonGroup - Create](/rest/api/face/person-group-operations/create-person-group) and [LargePersonGroup - Create](/rest/api/face/person-group-operations/create-large-person-group) by specifying the new face recognition model name `recognition_02` in `recognitionModel` parameter. More details in [How to specify a recognition model](how-to/specify-recognition-model.md).

+* This feature allows the service to support data migration across subscriptions: [Snapshot](/rest/api/face/snapshot?view=rest-face-v1.0-preview).

+* Refined description for `status`, `createdDateTime`, `lastActionDateTime`, and `lastSuccessfulTrainingDateTime` in [PersonGroup - Get Training Status](/rest/api/face/person-group-operations/get-person-group-training-status), [LargePersonGroup - Get Training Status](/rest/api/face/person-group-operations/get-large-person-group-training-status), and [LargeFaceList - Get Training Status](/rest/api/face/face-list-operations/get-large-face-list-training-status).

+* Improved `gender` attribute significantly and also improved `age`, `glasses`, `facialHair`, `hair`, `makeup` attributes. Use them through [Face - Detect](/rest/api/face/face-detection-operations) `returnFaceAttributes` parameter.

+* Increased input image file size limit from 4 MB to 6 MB in [Face - Detect](/rest/api/face/face-detection-operations), [FaceList - Add Face](/rest/api/face/face-list-operations/add-face-list-face), [LargeFaceList - Add Face](/rest/api/face/face-list-operations/add-large-face-list-face), [PersonGroup Person - Add Face](/rest/api/face/person-group-operations/add-person-group-person-face) and [LargePersonGroup Person - Add Face](/rest/api/face/person-group-operations/add-large-person-group-person-face).

+* [LargeFaceList](/rest/api/face/face-list-operations/create-large-face-list) and [LargePersonGroup](/rest/api/face/person-group-operations/create-large-person-group). More details in [How to scale to handle more enrolled users](how-to/use-large-scale.md).

+* Increased [Face - Identify](/rest/api/face/face-recognition-operations/identify-from-dynamic-person-group) `maxNumOfCandidatesReturned` parameter from [1, 5] to [1, 100] and default to 10.

+* Added `hair`, `makeup`, `accessory`, `occlusion`, `blur`, `exposure`, and `noise` attributes in [Face - Detect](/rest/api/face/face-detection-operations) `returnFaceAttributes` parameter.

+* Supported 10K persons in a PersonGroup and [Face - Identify](/rest/api/face/face-recognition-operations/identify-from-dynamic-person-group).

+* Supported pagination in [PersonGroup Person - List](/rest/api/face/person-group-operations/get-person-group-persons) with optional parameters: `start` and `top`.

+* Added `emotion` attribute in [Face - Detect](/rest/api/face/face-detection-operations) `returnFaceAttributes` parameter.

+* Face could not be re-detected with rectangle returned from [Face - Detect](/rest/api/face/face-detection-operations) as `targetFace` in [FaceList - Add Face](/rest/api/face/face-list-operations/add-face-list-face) and [PersonGroup Person - Add Face](/rest/api/face/person-group-operations/add-person-group-person-face).

+* Added Face Storage Standard subscription to store additional persisted faces when using [PersonGroup Person - Add Face](/rest/api/face/person-group-operations/add-person-group-person-face) or [FaceList - Add Face](/rest/api/face/face-list-operations/add-face-list-face) for identification or similarity matching. The stored images are charged at $0.5 per 1000 faces and this rate is prorated on a daily basis. Free tier subscriptions continue to be limited to 1,000 total persons.

+* Changed the error message of more than one face in the `targetFace` from 'There are more than one face in the image' to 'There is more than one face in the image' in [FaceList - Add Face](/rest/api/face/face-list-operations/add-face-list-face) and [PersonGroup Person - Add Face](/rest/api/face/person-group-operations/add-person-group-person-face).

+* Supported Face to Person object authentication in [Face - Verify](/rest/api/face/face-recognition-operations/verify-face-to-face).

+* Added optional `mode` parameter enabling selection of two working modes: `matchPerson` and `matchFace` in [Face - Find Similar](/rest/api/face/face-recognition-operations/find-similar) and default is `matchPerson`.

+* Added optional `confidenceThreshold` parameter for user to set the threshold of whether one face belongs to a Person object in [Face - Identify](/rest/api/face/face-recognition-operations/identify-from-dynamic-person-group).

+* Added optional `start` and `top` parameters in [PersonGroup - List](/rest/api/face/person-group-operations/get-person-groups) to enable user to specify the start point and the total PersonGroups number to list.

+ [Face - Detect](/rest/api/face/face-detection-operations), [Face - Identify](/rest/api/face/face-recognition-operations/identify-from-dynamic-person-group), [Face - Find Similar](/rest/api/face/face-recognition-operations/find-similar) and [Face - Group](/rest/api/face/face-recognition-operations/group).

+| **Image Moderation API**<br /><br />Scan images and detect potential adult and racy content by using tags, confidence scores, and other extracted information. | [Image Moderation API reference](/rest/api/cognitiveservices/contentmoderator/image-moderation) |

+| **Text Moderation API**<br /><br />Scan text content. Profanity terms and personal data are returned. | [Text Moderation API reference](/rest/api/cognitiveservices/contentmoderator/text-moderation) |

+| **List Management API**<br /><br />Create and manage custom exclusion or inclusion lists of images and text. If enabled, the **Image - Match** and **Text - Screen** operations do fuzzy matching of the submitted content against your custom lists. <br /><br />For efficiency, you can skip the machine learning-based moderation step.<br /><br /> | [List Management API reference](/rest/api/cognitiveservices/contentmoderator/list-management-image-lists) |

+| Images for custom matching | Call the [Get image IDs API](/rest/api/cognitiveservices/contentmoderator/list-management-image/get-all-image-ids). Images are stored in a one-way proprietary hash format, and there is no way to extract the actual images. | Call the [Delete all Images API](/rest/api/cognitiveservices/contentmoderator/list-management-image/delete-all-images). Or delete the Content Moderator resource using the Azure portal. |

+| Terms for custom matching | Cal the [Get all terms API](/rest/api/cognitiveservices/contentmoderator/list-management-term/get-all-terms) | Call the [Delete all terms API](/rest/api/cognitiveservices/contentmoderator/list-management-term/delete-all-terms). Or delete the Content Moderator resource using the Azure portal. |

+The Content Moderator provides a complete Image List Management API with operations for managing lists of custom images. Check out the [Image List .NET quickstart](image-lists-quickstart-dotnet.md) if you are familiar with Visual Studio and C#.

+Test drive the [Quickstart](client-libraries.md) and use the REST API code samples.

+* [**How-to guides**](video-moderation-api.md) contain instructions for using the service in more specific or customized ways.

+|[**Custom term lists**](term-lists-quickstart-dotnet.md)| Scans text against a custom list of terms along with the built-in terms. Use custom lists to block or allow content according to your own content policies.|

+|[**Custom image lists**](image-lists-quickstart-dotnet.md)| Scans images against a custom list of images. Use custom image lists to filter out instances of commonly recurring content that you don't want to classify again.|

+If the API detects any profane terms in any of the [supported languages](./language-support.md), those terms are included in the response. The response also contains their location (`Index`) in the original text. The `ListId` in the following sample JSON refers to terms found in custom term lists if available.

+The Content Moderator provides a [Term List API](/rest/api/cognitiveservices/contentmoderator/list-management-term-lists) with operations for managing custom term lists. Check out the [Term Lists .NET quickstart](term-lists-quickstart-dotnet.md) if you are familiar with Visual Studio and C#.

+Test out the APIs with the [Quickstart](client-libraries.md).

+ Title: "Custom categories (rapid) in Azure AI Content Safety"

+description: Learn about content incidents and how you can use Azure AI Content Safety to handle them on your platform.

+#

+# Custom categories (rapid)

+In content moderation scenarios, custom categories (rapid) is the process of identifying, analyzing, containing, eradicating, and recovering from cyber incidents that involve inappropriate or harmful content on online platforms.

+An incident may involve a set of emerging content patterns (text, image, or other modalities) that violate Microsoft community guidelines or the customers' own policies and expectations. These incidents need to be mitigated quickly and accurately to avoid potential live site issues or harm to users and communities.

+## Custom categories (rapid) API features

+One way to deal with emerging content incidents is to use [Blocklists](/azure/ai-services/content-safety/how-to/use-blocklist), but that only allows exact text matching and no image matching. The Azure AI Content Safety custom categories (rapid) API offers the following advanced capabilities:

+- semantic text matching using embedding search with a lightweight classifier

+- image matching with a lightweight object-tracking model and embedding search.

+## How it works

+First, you use the API to create an incident object with a description. Then you add any number of image or text samples to the incident. No training step is needed.

+Then, you can include your defined incident in a regular text analysis or image analysis request. The service will indicate whether the submitted content is an instance of your incident. The service can still do other content moderation tasks in the same API call.

+## Limitations

+### Language availability

+The text custom categories (rapid) API supports all languages that are supported by Content Safety text moderation. See [Language support](/azure/ai-services/content-safety/language-support).

+### Input limitations

+See the following table for the input limitations of the custom categories (rapid) API:

+| Object | Limitation |

+| : | :-- |

+| Maximum length of an incident name | 100 characters |

+| Maximum number of text/image samples per incident | 1000 |

+| Maximum size of each sample | Text: 500 characters<br>Image: 4 MBΓÇ» |

+| Maximum number of text or image incidents per resource| 100 |

+| Supported Image formats | BMP, GIF, JPEG, PNG, TIF, WEBP |

+### Region availability

+To use this API, you must create your Azure AI Content Safety resource in one of the supported regions. See [Region availability](/azure/ai-services/content-safety/overview#region-availability).

+## Next steps

+Follow the how-to guide to use the Azure AI Content Safety custom categories (rapid) API.

+* [Use the custom categories (rapid) API](../how-to/custom-categories-rapid.md)

+To use this API, you must create your Azure AI Content Safety resource in the supported regions. See [Region availability](/azure/ai-services/content-safety/overview#region-availability).

+See [Query rates](/azure/ai-services/content-safety/overview#query-rates).

+The maximum character limit for Prompt Shields allows for a user prompt of up to 10,000 characters, while the document array is restricted to a maximum of 5 documents with a combined total not exceeding 10,000 characters.

+### Regions

+To use this API, you must create your Azure AI Content Safety resource in the supported regions. See [Region availability](/azure/ai-services/content-safety/overview#region-availability).

+See [Query rates](/azure/ai-services/content-safety/overview#query-rates).

+ Title: "Use the custom categories (rapid) API"

+description: Learn how to use the custom categories (rapid) API to mitigate harmful content incidents quickly.

+#

+# Use the custom categories (rapid) API

+The custom categories (rapid) API lets you quickly respond to emerging harmful content incidents. You can define an incident with a few examples in a specific topic, and the service will start detecting similar content.

+Follow these steps to define an incident with a few examples of text content and then analyze new text content to see if it matches the incident.

+> [!IMPORTANT]

+> This new feature is only available in select Azure regions. See [Region availability](/azure/ai-services/content-safety/overview#region-availability).

+> [!CAUTION]

+> The sample data in this guide might contain offensive content. User discretion is advised.

+## Prerequisites

+* An Azure subscription - [Create one for free](https://azure.microsoft.com/free/cognitive-services/)

+* Once you have your Azure subscription, <a href="https://aka.ms/acs-create" title="Create a Content Safety resource" target="_blank">create a Content Safety resource </a> in the Azure portal to get your key and endpoint. Enter a unique name for your resource, select your subscription, and select a resource group, supported region (see [Region availability](/azure/ai-services/content-safety/overview#region-availability)), and supported pricing tier. Then select **Create**.

+ * The resource takes a few minutes to deploy. After it finishes, Select **go to resource**. In the left pane, under **Resource Management**, select **Subscription Key and Endpoint**. The endpoint and either of the keys are used to call APIs.

+* Also [create a blob storage container](https://ms.portal.azure.com/#create/Microsoft.StorageAccount-ARM) if you want to upload your images there. You can alternatively encode your images as Base64 strings and use them directly in the API calls.

+* One of the following installed:

+ * [cURL](https://curl.haxx.se/) for REST API calls.

+ * [Python 3.x](https://www.python.org/) installed

+<!--tbd env vars-->

+## Test the text custom categories (rapid) API

+Use the sample code in this section to create a text incident, add samples to the incident, deploy the incident, and then detect text incidents.

+### Create an incident object

+#### [cURL](#tab/curl)

+In the commands below, replace `<your_api_key>`, `<your_endpoint>`, and other necessary parameters with your own values.

+The following command creates an incident with a name and definition.

+```bash

+curl --location --request PATCH 'https://<endpoint>/contentsafety/text/incidents/<text-incident-name>?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>' \

+--header 'Content-Type: application/json' \

+--data '{

+ "incidentName": "<text-incident-name>",

+ "incidentDefinition": "string"

+}'

+```

+#### [Python](#tab/python)

+First, you need to install the required Python library:

+```bash

+pip install requests

+```

+Then, define the necessary variables with your own Azure resource details:

+```python

+import requests

+API_KEY = '<your_api_key>'

+ENDPOINT = '<your_endpoint>'

+headers = {

+ 'Ocp-Apim-Subscription-Key': API_KEY,

+ 'Content-Type': 'application/json'

+}

+```

+The following command creates an incident with a name and definition.

+```python

+import requests

+import json

+url = "https://<endpoint>/contentsafety/text/incidents/<text-incident-name>?api-version=2024-02-15-preview "

+payload = json.dumps({

+ "incidentName": "<text-incident-name>",

+ "incidentDefinition": "string"

+})

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>',

+ 'Content-Type': 'application/json'

+}

+response = requests.request("PATCH", url, headers=headers, data=payload)

+print(response.text)

+```

+### Add samples to the incident

+Use the following command to add text examples to the incident.

+#### [cURL](#tab/curl)

+```bash

+curl --location 'https://<endpoint>/contentsafety/text/incidents/<text-incident-name>:addIncidentSamples?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>' \

+--header 'Content-Type: application/json' \

+--data-raw '{

+ "IncidentSamples": [

+ { "text": "<text-example-1>"},

+ { "text": "<text-example-2>"},

+ ...

+ ]

+}'

+```

+#### [Python](#tab/python)

+```python

+import requests

+import json

+url = "https://<endpoint>/contentsafety/text/incidents/<text-incident-name>:addIncidentSamples?api-version=2024-02-15-preview "

+payload = json.dumps({

+ "IncidentSamples": [

+ {

+ "text": "<text-example-1>"

+ },

+ {

+ "text": "<text-example-1>"

+ },

+ ...

+ ]

+})

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>',

+ 'Content-Type': 'application/json'

+}

+response = requests.request("POST", url, headers=headers, data=payload)

+print(response.text)

+```

+### Deploy the incident

+Use the following command to deploy the incident, making it available for the analysis of new content.

+#### [cURL](#tab/curl)

+```bash

+curl --location 'https://<endpoint>/contentsafety/text/incidents/<text-incident-name>:deploy?api-version=2024-02-15-preview' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>' \

+--header 'Content-Type: application/json'

+```

+#### [Python](#tab/python)

+```python

+import requests

+import json

+url = "https://<endpoint>/contentsafety/text/incidents/<text-incident-name>:deploy?api-version=2024-02-15-preview"

+payload = {}

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>',

+ 'Content-Type': 'application/json'

+}

+response = requests.request("POST", url, headers=headers, data=payload)

+print(response.text)

+```

+### Detect text incidents

+Run the following command to analyze sample text content for the incident you just deployed.

+#### [cURL](#tab/curl)

+```bash

+curl --location 'https://<endpoint>/contentsafety/text:detectIncidents?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>' \

+--header 'Content-Type: application/json' \

+--data '{

+ "text": "<test-text>",

+ "incidentNames": [

+ "<text-incident-name>"

+ ]

+}'

+```

+#### [Python](#tab/python)

+```python

+import requests

+import json

+url = "https://<endpoint>/contentsafety/text:detectIncidents?api-version=2024-02-15-preview "

+payload = json.dumps({

+ "text": "<test-text>",

+ "incidentNames": [

+ "<text-incident-name>"

+ ]

+})

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>',

+ 'Content-Type': 'application/json'

+}

+response = requests.request("POST", url, headers=headers, data=payload)

+print(response.text)

+```

+## Test the image custom categories (rapid) API

+Use the sample code in this section to create an image incident, add samples to the incident, deploy the incident, and then detect image incidents.

+### Create an incident

+#### [cURL](#tab/curl)

+In the commands below, replace `<your_api_key>`, `<your_endpoint>`, and other necessary parameters with your own values.

+The following command creates an image incident:

+```bash

+curl --location --request PATCH 'https://<endpoint>/contentsafety/image/incidents/<image-incident-name>?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>' \

+--header 'Content-Type: application/json' \

+--data '{

+ "incidentName": "<image-incident-name>"

+}'

+```

+#### [Python](#tab/python)

+Make sure you've installed required Python libraries:

+```bash

+pip install requests

+```

+Define the necessary variables with your own Azure resource details:

+```python

+import requests

+API_KEY = '<your_api_key>'

+ENDPOINT = '<your_endpoint>'

+headers = {

+ 'Ocp-Apim-Subscription-Key': API_KEY,

+ 'Content-Type': 'application/json'

+}

+```

+The following command creates an image incident:

+```python

+import requests

+import json

+url = "https://<endpoint>/contentsafety/image/incidents/<image-incident-name>?api-version=2024-02-15-preview "

+payload = json.dumps({

+ "incidentName": "<image-incident-name>"

+})

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>',

+ 'Content-Type': 'application/json'

+}

+response = requests.request("PATCH", url, headers=headers, data=payload)

+print(response.text)

+```

+### Add samples to the incident

+Use the following command to add examples images to your incident. The image samples can be URLs pointing to images in an Azure blob storage container, or they can be Base64 strings.

+#### [cURL](#tab/curl)

+```bash

+curl --location 'https://<endpoint>/contentsafety/image/incidents/<image-incident-name>:addIncidentSamples?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>' \

+--header 'Content-Type: application/json' \

+--data '{

+ "IncidentSamples": [

+ {

+ "image": {

+ "content": "<base64-data>",

+ "bloburl": "<your-blob-storage-url>.png"

+ }

+ }

+ ]

+}'

+```

+#### [Python](#tab/python)

+```python

+import requests

+import json

+url = "https://<endpoint>/contentsafety/image/incidents/<image-incident-name>:addIncidentSamples?api-version=2024-02-15-preview "

+payload = json.dumps({

+ "IncidentSamples": [

+ {

+ "image": {

+ "content": "<base64-data>",

+ "bloburl": "<your-blob-storage-url>/image.png"

+ }

+ }

+ ]

+})

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>',

+ 'Content-Type': 'application/json'

+}

+response = requests.request("POST", url, headers=headers, data=payload)

+print(response.text)

+```

+### Deploy the incident

+Use the following command to deploy the incident, making it available for the analysis of new content.

+#### [cURL](#tab/curl)

+```bash

+curl --location 'https://<endpoint>/contentsafety/image/incidents/<image-incident-name>:deploy?api-version=2024-02-15-preview' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>' \

+--header 'Content-Type: application/json'

+```

+#### [Python](#tab/python)

+```python

+import requests

+import json

+url = "https://<endpoint>/contentsafety/image/incidents/<image-incident-name>:deploy?api-version=2024-02-15-preview"

+payload = {}

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>',

+ 'Content-Type': 'application/json'

+}

+response = requests.request("POST", url, headers=headers, data=payload)

+print(response.text)

+```

+### Detect image incidents

+Use the following command to upload a sample image and test it against the incident you deployed. You can either use a URL pointing to the image in an Azure blob storage container, or you can add the image data as a Base64 string.

+#### [cURL](#tab/curl)

+```bash

+curl --location 'https://<endpoint>/contentsafety/image:detectIncidents?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>' \

+--header 'Content-Type: application/json' \

+--data '{

+ "image": {

+ "url": "<your-blob-storage-url>/image.png",

+ "content": "<base64-data>"

+ },

+ "incidentNames": [

+ "<image-incident-name>"

+ ]

+ }

+}'

+```

+#### [Python](#tab/python)

+```python

+import requests

+import json

+url = "https://<endpoint>/contentsafety/image:detectIncidents?api-version=2024-02-15-preview "

+payload = json.dumps({

+ "image": {

+ "url": "<your-blob-storage-url>/image.png",

+ "content": "<base64-data>"

+ },

+ "incidentNames": [

+ "<image-incident-name>"

+ ]

+})

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>',

+ 'Content-Type': 'application/json'

+}

+response = requests.request("POST", url, headers=headers, data=payload)

+print(response.text)

+```

+## Other incident operations

+The following operations are useful for managing incidents and incident samples.

+### Text incidents API

+#### List all incidents

+#### [cURL](#tab/curl)

+```bash

+curl --location GET 'https://<endpoint>/contentsafety/text/incidents?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>'

+```

+#### [Python](#tab/python)

+```python

+import requests

+url = "https://<endpoint>/contentsafety/text/incidents?api-version=2024-02-15-preview "

+payload = {}

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>'

+}

+response = requests.request("GET", url, headers=headers, data=payload)

+print(response.text)

+```

+#### Get the incident details

+#### [cURL](#tab/curl)

+```bash

+curl --location GET 'https://<endpoint>/contentsafety/text/incidents/<text-incident-name>?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>'

+```

+#### [Python](#tab/python)

+```python

+import requests

+url = "https://<endpoint>/contentsafety/text/incidents/<text-incident-name>?api-version=2024-02-15-preview "

+payload = {}

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>'

+}

+response = requests.request("GET", url, headers=headers, data=payload)

+print(response.text)

+```

+#### Delete the incident

+#### [cURL](#tab/curl)

+```bash

+curl --location --request DELETE 'https://<endpoint>/contentsafety/text/incidents/<text-incident-name>?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>'

+```

+#### [Python](#tab/python)

+```python

+import requests

+url = "https://<endpoint>/contentsafety/text/incidents/<text-incident-name>?api-version=2024-02-15-preview "

+payload = {}

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>'

+}

+response = requests.request("DELETE", url, headers=headers, data=payload)

+print(response.text)

+```

+#### List all samples under an incident

+This command retrieves the unique IDs of all the samples associated with a given incident object.

+#### [cURL](#tab/curl)

+```bash

+curl --location GET 'https://<endpoint>/contentsafety/text/incidents/<text-incident-name>/incidentsamples?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>'

+```

+#### [Python](#tab/python)

+```python

+import requests

+url = "https://<endpoint>/contentsafety/text/incidents/<text-incident-name>/incidentsamples?api-version=2024-02-15-preview "

+payload = {}

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>'

+}

+response = requests.request("GET", url, headers=headers, data=payload)

+print(response.text)

+```

+#### Get an incident sample's details

+Use an incident sample ID to look up details about the sample.

+#### [cURL](#tab/curl)

+```bash

+curl --location GET 'https://<endpoint>/contentsafety/text/incidents/<text-incident-name>/incidentsamples/<your-incident-sample-id>?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>'

+```

+#### [Python](#tab/python)

+```python

+import requests

+url = "https://<endpoint>/contentsafety/text/incidents/<text-incident-name>/incidentsamples/<your-incident-sample-id>?api-version=2024-02-15-preview "

+payload = {}

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>'

+}

+response = requests.request("GET", url, headers=headers, data=payload)

+print(response.text)

+```

+#### Delete an incident sample

+Use an incident sample ID to retrieve and delete that sample.

+#### [cURL](#tab/curl)

+```bash

+curl --location 'https://<endpoint>/contentsafety/text/incidents/<text-incident-name>:removeIncidentSamples?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>' \

+--header 'Content-Type: application/json' \

+--data '{

+ "IncidentSampleIds": [

+ "<your-incident-sample-id>"

+ ]

+}'

+```

+#### [Python](#tab/python)

+```python

+import requests

+import json

+url = "https://<endpoint>/contentsafety/text/incidents/<text-incident-name>:removeIncidentSamples?api-version=2024-02-15-preview "

+payload = json.dumps({

+ "IncidentSampleIds": [

+ "<your-incident-sample-id>"

+ ]

+})

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>',

+ 'Content-Type': 'application/json'

+}

+response = requests.request("POST", url, headers=headers, data=payload)

+print(response.text)

+```

+### Image incidents API

+#### Get the incidents list

+#### [cURL](#tab/curl)

+```bash

+curl --location GET 'https://<endpoint>/contentsafety/image/incidents?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>'

+```

+#### [Python](#tab/python)

+```python

+import requests

+url = "https://<endpoint>/contentsafety/image/incidents?api-version=2024-02-15-preview "

+payload = {}

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>'

+}

+response = requests.request("GET", url, headers=headers, data=payload)

+print(response.text)

+```

+#### Get the incident details

+#### [cURL](#tab/curl)

+```bash

+curl --location GET 'https://<endpoint>/contentsafety/image/incidents/<image-incident-name>?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>'

+```

+#### [Python](#tab/python)

+```python

+import requests

+url = "https://<endpoint>/contentsafety/image/incidents/<image-incident-name>?api-version=2024-02-15-preview "

+payload = {}

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>'

+}

+response = requests.request("GET", url, headers=headers, data=payload)

+print(response.text)

+```

+#### Delete the incident

+#### [cURL](#tab/curl)

+```bash

+curl --location --request DELETE 'https://<endpoint>/contentsafety/image/incidents/<image-incident-name>?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>'

+```

+#### [Python](#tab/python)

+```python

+import requests

+url = "https://<endpoint>/contentsafety/image/incidents/<image-incident-name>?api-version=2024-02-15-preview "

+payload = {}

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>'

+}

+response = requests.request("DELETE", url, headers=headers, data=payload)

+print(response.text)

+```

+#### List all samples under an incident

+This command retrieves the unique IDs of all the samples associated with a given incident object.

+#### [cURL](#tab/curl)

+```bash

+curl --location GET 'https://<endpoint>/contentsafety/image/incidents/<image-incident-name>/incidentsamples?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>'

+```

+#### [Python](#tab/python)

+```python

+import requests

+url = "https://<endpoint>/contentsafety/image/incidents/<image-incident-name>/incidentsamples?api-version=2024-02-15-preview "

+payload = {}

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>'

+}

+response = requests.request("GET", url, headers=headers, data=payload)

+print(response.text)

+```

+#### Get the incident sample details

+Use an incident sample ID to look up details about the sample.

+#### [cURL](#tab/curl)

+```bash

+curl --location GET 'https://<endpoint>/contentsafety/image/incidents/<image-incident-name>/incidentsamples/<your-incident-sample-id>?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>'

+```

+#### [Python](#tab/python)

+```python

+import requests

+url = "https://<endpoint>/contentsafety/image/incidents/<image-incident-name>/incidentsamples/<your-incident-sample-id>?api-version=2024-02-15-preview "

+payload = {}

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>'

+}

+response = requests.request("GET", url, headers=headers, data=payload)

+print(response.text)

+```

+#### Delete the incident sample

+Use an incident sample ID to retrieve and delete that sample.

+#### [cURL](#tab/curl)

+```bash

+curl --location 'https://<endpoint>/contentsafety/image/incidents/<image-incident-name>:removeIncidentSamples?api-version=2024-02-15-preview ' \

+--header 'Ocp-Apim-Subscription-Key: <your-content-safety-key>' \

+--header 'Content-Type: application/json' \

+--data '{

+ "IncidentSampleIds": [

+ "<your-incident-sample-id>"

+ ]

+}'

+```

+#### [Python](#tab/python)

+```python

+import requests

+import json

+url = "https://<endpoint>/contentsafety/image/incidents/<image-incident-name>:removeIncidentSamples?api-version=2024-02-15-preview "

+payload = json.dumps({

+ "IncidentSampleIds": [

+ "<your-incident-sample-id>"

+ ]

+})

+headers = {

+ 'Ocp-Apim-Subscription-Key': '<your-content-safety-key>',

+ 'Content-Type': 'application/json'

+}

+response = requests.request("POST", url, headers=headers, data=payload)

+print(response.text)

+```

+## Related content

+- [Custom categories (rapid) concepts](../concepts/custom-categories-rapid.md)

+- [What is Azure AI Content Safety?](../overview.md)

+* Once you have your Azure subscription, <a href="https://aka.ms/acs-create" title="Create a Content Safety resource" target="_blank">create a Content Safety resource </a> in the Azure portal to get your key and endpoint. Enter a unique name for your resource, select your subscription, and select a resource group, supported region (see [Region availability](/azure/ai-services/content-safety/overview#region-availability)), and supported pricing tier. Then select **Create**.

+> "blocklistItems": [

+> {

+> "description": "string",

+> "text": "bleed"

+> },

+> {

+> "description": "string",

+> "text": "blood"

+> }

+> ]

+>}

+| Custom categories (rapid) API (preview) | Lets you define [emerging harmful content patterns](./concepts/custom-categories-rapid.md) and scan text and images for matches. [How-to guide](./how-to/custom-categories-rapid.md) |

+Currently, Azure AI Content Safety has an **F0 and S0** pricing tier. See the Azure [pricing page](https://aka.ms/content-safety-pricing) for more information.

+### Region availability

+To use the Content Safety APIs, you must create your Azure AI Content Safety resource in the supported regions. Currently, the Content Safety features are available in the following Azure regions:

+| Region | Moderation APIs | Prompt Shields | Protected material<br>detection | Groundedness<br>detection | Incident response | Blocklists |

+|||||||--|

+| East US | ✅ | ✅| ✅ |✅ |✅ |✅ |

+| East US 2 | ✅ | | | ✅ | | |

+| West US | | | | | ✅ | | |

+| West US 2 | ✅ | | | | | |

+| Central US | ✅ | | | | | |

+| North Central US | ✅ | | | | | |

+| South Central US | ✅ | | | | | |

+| Canada East | ✅ | | | | | |

+| Switzerland North | ✅ | | | | | |

+| Sweden Central | ✅ | | |✅ |✅ | |

+| UK South | ✅ | | | | | |

+| France Central | ✅ | | | | | |

+| West Europe | ✅ | ✅ |✅ | | |✅ |

+| Japan East | ✅ | | | | | |

+| Australia East| ✅ | ✅ | | | | |

+| Pricing Tier | Requests per 10 seconds |

+#### Prompt Shields

+| Pricing Tier | Requests per 10 seconds |

+| :-- | :- |

+| F0 | 1000 |

+| S0 | 1000 |

+#### Groundedness detection

+| Pricing Tier | Requests per 10 seconds |

+| :-- | : |

+| F0 | 50 |

+| S0 | 50 |

+* Once you have your Azure subscription, <a href="https://aka.ms/acs-create" title="Create a Content Safety resource" target="_blank">create a Content Safety resource </a> in the Azure portal to get your key and endpoint. Enter a unique name for your resource, select your subscription, and select a resource group, supported region (East US, East US2, West US, Sweden Central), and supported pricing tier. Then select **Create**.

+* The resource takes a few minutes to deploy. After it does, go to the new resource. In the left pane, under **Resource Management**, select **API Keys and Endpoints**. Copy one of the subscription key values and endpoint to a temporary location for later use.

+In the simple case without the _reasoning_ feature, the Groundedness detection API classifies the ungroundedness of the submitted content as `true` or `false`.

+ "reasoning": false

+Open a command prompt and run the cURL command.

+ "reasoning": false

+To test a summarization task instead of a question answering (QnA) task, use the following sample JSON body:

+```json

+{

+ "domain": "Medical",

+ "task": "Summarization",

+ "text": "Ms Johnson has been in the hospital after experiencing a stroke.",

+ "groundingSources": ["Our patient, Ms. Johnson, presented with persistent fatigue, unexplained weight loss, and frequent night sweats. After a series of tests, she was diagnosed with HodgkinΓÇÖs lymphoma, a type of cancer that affects the lymphatic system. The diagnosis was confirmed through a lymph node biopsy revealing the presence of Reed-Sternberg cells, a characteristic of this disease. She was further staged using PET-CT scans. Her treatment plan includes chemotherapy and possibly radiation therapy, depending on her response to treatment. The medical team remains optimistic about her prognosis given the high cure rate of HodgkinΓÇÖs lymphoma."],

+ "reasoning": false

+}

+```

+| **reasoning** | (Optional) Specifies whether to use the reasoning feature. The default value is `false`. If `true`, you need to bring your own Azure OpenAI GPT-4 Turbo (1106-preview) resources to provide an explanation. Be careful: using reasoning increases the processing time.| Boolean |

+| -**`text`** | The specific text that is ungrounded. | String |

+The Groundedness detection API provides the option to include _reasoning_ in the API response. With reasoning enabled, the response includes a `"reasoning"` field that details specific instances and explanations for any detected ungroundedness.

+> [!TIP]

+> At the moment, we only support **Azure OpenAI GPT-4 Turbo (1106-preview)** resources and do not support other GPT types. You have the flexibility to deploy your GPT-4 Turbo (1106-preview) resources in any region. However, to minimize potential latency and avoid any geographical boundary data privacy and risk concerns, we recommend situating them in the same region as your content safety resources. For comprehensive details on data privacy, please refer to the [Data, privacy and security guidelines for Azure OpenAI Service](/legal/cognitive-services/openai/data-privacy) and [Data, privacy, and security for Azure AI Content Safety](/legal/cognitive-services/content-safety/data-privacy?context=%2Fazure%2Fai-services%2Fcontent-safety%2Fcontext%2Fcontext).

+In order to use your Azure OpenAI GPT4-Turbo (1106-preview) resource to enable the reasoning feature, use Managed Identity to allow your Content Safety resource to access the Azure OpenAI resource:

+In your request to the Groundedness detection API, set the `"reasoning"` body parameter to `true`, and provide the other needed parameters:

+| **llmResource** | (Required) If you want to use your own Azure OpenAI GPT4-Turbo (1106-preview) resource to enable reasoning, add this field and include the subfields for the resources used. | String |

+| - `resourceType `| Specifies the type of resource being used. Currently it only allows `AzureOpenAI`. We only support Azure OpenAI GPT-4 Turbo (1106-preview) resources and do not support other GPT types. | Enum|

+ "utf8": 0,

+ "utf16": 0,

+ "utf8": 8,

+ "utf16": 8,

+| -**`text`** | The specific text that is ungrounded. | String |

+| -**`reason`** | Offers explanations for detected ungroundedness. | String |

+* Once you have your Azure subscription, <a href="https://aka.ms/acs-create" title="Create a Content Safety resource" target="_blank">create a Content Safety resource </a> in the Azure portal to get your key and endpoint. Enter a unique name for your resource, select your subscription, and select a resource group, supported region (see [Region availability](/azure/ai-services/content-safety/overview#region-availability)), and supported pricing tier. Then select **Create**.

+* Once you have your Azure subscription, <a href="https://aka.ms/acs-create" title="Create a Content Safety resource" target="_blank">create a Content Safety resource </a> in the Azure portal to get your key and endpoint. Enter a unique name for your resource, select your subscription, and select a resource group, supported region (see [Region availability](/azure/ai-services/content-safety/overview#region-availability)), and supported pricing tier. Then select **Create**.

+## May 2024

+### Custom categories (rapid) API

+The custom categories (rapid) API lets you quickly define emerging harmful content patterns and scan text and images for matches. See [Custom categories (rapid)](./concepts/custom-categories-rapid.md) to learn more.

+Jailbreak risk and Protected material detection are only available in select regions. See [Region availability](/azure/ai-services/content-safety/overview#region-availability).

+The **[ExportProject](/rest/api/customvision/training/projects/export?view=rest-customvision-training-v3.3&tabs=HTTP)** and **[ImportProject](/rest/api/customvision/training/projects/import?view=rest-customvision-training-v3.3&tabs=HTTP)** APIs enable this scenario by allowing you to copy projects from one Custom Vision account into others. This guide shows you how to use these REST APIs with cURL. You can also use an HTTP request service, like the [REST Client](https://marketplace.visualstudio.com/items?itemName=humao.rest-client) for Visual Studio Code, to issue the requests.

+First call **[GetProjects](/rest/api/customvision/training/projects/get?view=rest-customvision-training-v3.3&tabs=HTTP)** to see a list of your existing Custom Vision projects and their IDs. Use the training key and endpoint of your source account.

+Call **[ExportProject](/rest/api/customvision/training/projects/export?view=rest-customvision-training-v3.3&tabs=HTTP)** using the project ID and your source training key and endpoint.

+Call **[ImportProject](/rest/api/customvision/training/projects/import?view=rest-customvision-training-v3.3&tabs=HTTP)** using your target training key and endpoint, along with the reference token. You can also give your project a name in its new account.

+* [Use your exported CoreML model in a Swift iOS application](https://go.microsoft.com/fwlink/?linkid=857726)

+If you're deploying to an IoT device with an ARM processor, you'll need to select **ARM** as the target platform and **Remote Machine** as the target device. Provide the IP address of your device when prompted (it must be on the same network as your PC). You can get the IP Address from the Windows IoT default app once you boot the device and connect it to the network. Press F5 to run the program.

+Within a few minutes, the target will be assigned the selected role at the selected scope. For help with these steps, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.yml).

+From the **settings** tab of your project on the Custom Vision web portal, you can select a model domain for your project. You'll want to choose the domain that's closest to your use case scenario. If you're accessing Custom Vision through a client library or REST API, you'll need to specify a domain ID when creating the project. You can get a list of domain IDs with [Get Domains](/rest/api/customvision/training/domains/list?view=rest-customvision-training-v3.3&tabs=HTTP). Or, use the table below.

+For help with role assignments, see [Assign Azure roles using the Azure portal](../../role-based-access-control/role-assignments-portal.yml).

+When you call the [CreateProject](/rest/api/customvision/training/projects/create?view=rest-customvision-training-v3.3&tabs=HTTP) API, add the optional parameters _exportModelContainerUri_ and _notificationQueueUri_. Assign the URL values you got in the previous section.

+To update an existing project with Azure storage feature integration, call the [UpdateProject](/rest/api/customvision/training/projects/update?view=rest-customvision-training-v3.3&tabs=HTTP) API, using the ID of the project you want to update.

+When you're ready, call the [TrainProject](/rest/api/customvision/training/projects/train?view=rest-customvision-training-v3.3&tabs=HTTP) API on your project to do an ordinary training operation.

+When you're ready, call the [ExportIteration](/rest/api/customvision/training/iterations/export?view=rest-customvision-training-v3.3&tabs=HTTP) API to export a trained model into a specified platform.

+* [REST API reference documentation (training)](/rest/api/customvision/training/operation-groups?view=rest-customvision-training-v3.3)

+* [REST API reference documentation (prediction)](/rest/api/customvision/prediction/operation-groups?view=rest-customvision-prediction-v3.1)

+> This document demonstrates use of the .NET client library for C# to submit an image to the Prediction API. For more information and examples, see the [Prediction API reference](/rest/api/customvision/prediction/operation-groups?view=rest-customvision-prediction-v3.1).

+To enable local authentication, execute the PowerShell cmdlet **[Set-AzCognitiveServicesAccount](/powershell/module/az.cognitiveservices/set-azcognitiveservicesaccount)** with the parameter `-DisableLocalAuthΓÇ»$false`.ΓÇ» Allow a few minutes for the service to accept the change to allow local authentication requests.

+1. **Document type confidence score**: The document type confidence is an indicator of closely the analyzed document resembles documents in the training dataset. When the document type confidence is low, it's indicative of template or structural variations in the analyzed document. To improve the document type confidence, label a document with that specific variation and add it to your training dataset. Once the model is retrained, it should be better equipped to handle that class of variations.

+2. **Field level confidence**: Each labeled field extracted has an associated confidence score. This score reflects the model's confidence on the position of the value extracted. While evaluating confidence scores, you should also look at the underlying extraction confidence to generate a comprehensive confidence for the extracted result. Evaluate the `OCR` results for text extraction or selection marks depending on the field type to generate a composite confidence score for the field.

+3. **Word confidence score** Each word extracted within the document has an associated confidence score. The score represents the confidence of the transcription. The pages array contains an array of words and each word has an associated span and confidence score. Spans from the custom field extracted values match the spans of the extracted words.

+4. **Selection mark confidence score**: The pages array also contains an array of selection marks. Each selection mark has a confidence score representing the confidence of the selection mark and selection state detection. When a labeled field has a selection mark, the custom field selection combined with the selection mark confidence is an accurate representation of overall confidence accuracy.

+With the addition of table, row and cell confidence with the ```2024-02-29-preview``` API, here are some common questions that should help with interpreting the table, row, and cell scores:

+## Capabilities

+> * Not all add-on capabilities are supported by all models. For more information, *see* [model data extraction](concept-model-overview.md#model-analysis-features).

+>

+> * Add-on capabilities are currently not supported for Microsoft Office file types.

+## Version availability

+|Add-on Capability| Add-On/Free|[2024-02-29-preview](/rest/api/aiservices/operation-groups?view=rest-aiservices-2024-02-29-preview&preserve-view=true)|[`2023-07-31` (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)|[`2022-08-31` (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)|[v2.1 (GA)](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true)|

+✱ Add-On - Query fields are priced differently than the other add-on features. See [pricing](https://azure.microsoft.com/pricing/details/ai-document-intelligence/) for details.

+## Supported file formats

+* `PDF`

+* Images: `JPEG`/`JPG`, `PNG`, `BMP`, `TIFF`, `HEIF`

+✱ Microsoft Office files are currently not supported.

+### [REST API](#tab/rest-api)

+### [Sample code](#tab/sample-code)

+```Python

+# Analyze a document at a URL:

+formUrl = "https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Data/add-on/add-on-highres.png?raw=true"

+poller = document_intelligence_client.begin_analyze_document(

+ "prebuilt-layout",

+ AnalyzeDocumentRequest(url_source=formUrl),

+ features=[DocumentAnalysisFeature.OCR_HIGH_RESOLUTION], # Specify which add-on capabilities to enable.

+)

+result: AnalyzeResult = poller.result()

+# [START analyze_with_highres]

+if result.styles and any([style.is_handwritten for style in result.styles]):

+ print("Document contains handwritten content")

+else:

+ print("Document does not contain handwritten content")

+for page in result.pages:

+ print(f"-Analyzing layout from page #{page.page_number}-")

+ print(f"Page has width: {page.width} and height: {page.height}, measured with unit: {page.unit}")

+ if page.lines:

+ for line_idx, line in enumerate(page.lines):

+ words = get_words(page, line)

+ print(

+ f"...Line # {line_idx} has word count {len(words)} and text '{line.content}' "

+ f"within bounding polygon '{line.polygon}'"

+ )

+ for word in words:

+ print(f"......Word '{word.content}' has a confidence of {word.confidence}")

+ if page.selection_marks:

+ for selection_mark in page.selection_marks:

+ print(

+ f"Selection mark is '{selection_mark.state}' within bounding polygon "

+ f"'{selection_mark.polygon}' and has a confidence of {selection_mark.confidence}"

+ )

+if result.tables:

+ for table_idx, table in enumerate(result.tables):

+ print(f"Table # {table_idx} has {table.row_count} rows and " f"{table.column_count} columns")

+ if table.bounding_regions:

+ for region in table.bounding_regions:

+ print(f"Table # {table_idx} location on page: {region.page_number} is {region.polygon}")

+ for cell in table.cells:

+ print(f"...Cell[{cell.row_index}][{cell.column_index}] has text '{cell.content}'")

+ if cell.bounding_regions:

+ for region in cell.bounding_regions:

+ print(f"...content on page {region.page_number} is within bounding polygon '{region.polygon}'")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Add-on_capabilities/sample_analyze_addon_highres.py)

+### [Output](#tab/output)

+```json

+"styles": [true],

+"pages": [

+ {

+ "page_number": 1,

+ "width": 1000,

+ "height": 800,

+ "unit": "px",

+ "lines": [

+ {

+ "line_idx": 1,

+ "content": "This",

+ "polygon": [10, 20, 30, 40],

+ "words": [

+ {

+ "content": "This",

+ "confidence": 0.98

+ }

+ ]

+ }

+ ],

+ "selection_marks": [

+ {

+ "state": "selected",

+ "polygon": [50, 60, 70, 80],

+ "confidence": 0.91

+ }

+ ]

+ }

+],

+"tables": [

+ {

+ "table_idx": 1,

+ "row_count": 3,

+ "column_count": 4,

+ "bounding_regions": [

+ {

+ "page_number": 1,

+ "polygon": [100, 200, 300, 400]

+ }

+ ],

+ "cells": [

+ {

+ "row_index": 1,

+ "column_index": 1,

+ "content": "Content 1",

+ "bounding_regions": [

+ {

+ "page_number": 1,

+ "polygon": [110, 210, 310, 410]

+ }

+ ]

+ }

+ ]

+ }

+]

+```

+### [REST API](#tab/rest-api)

+### [Sample code](#tab/sample-code)

+```Python

+# Analyze a document at a URL:

+url = "(https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Data/add-on/add-on-highres.png?raw=true"

+poller = document_analysis_client.begin_analyze_document_from_url(

+ "prebuilt-layout", document_url=url, features=[AnalysisFeature.OCR_HIGH_RESOLUTION] # Specify which add-on capabilities to enable.

+)

+result = poller.result()

+# [START analyze_with_highres]

+if any([style.is_handwritten for style in result.styles]):

+ print("Document contains handwritten content")

+else:

+ print("Document does not contain handwritten content")

+for page in result.pages:

+ print(f"-Analyzing layout from page #{page.page_number}-")

+ print(

+ f"Page has width: {page.width} and height: {page.height}, measured with unit: {page.unit}"

+ )

+ for line_idx, line in enumerate(page.lines):

+ words = line.get_words()

+ print(

+ f"...Line # {line_idx} has word count {len(words)} and text '{line.content}' "

+ f"within bounding polygon '{format_polygon(line.polygon)}'"

+ )

+ for word in words:

+ print(

+ f"......Word '{word.content}' has a confidence of {word.confidence}"

+ )

+ for selection_mark in page.selection_marks:

+ print(

+ f"Selection mark is '{selection_mark.state}' within bounding polygon "

+ f"'{format_polygon(selection_mark.polygon)}' and has a confidence of {selection_mark.confidence}"

+ )

+for table_idx, table in enumerate(result.tables):

+ print(

+ f"Table # {table_idx} has {table.row_count} rows and "

+ f"{table.column_count} columns"

+ )

+ for region in table.bounding_regions:

+ print(

+ f"Table # {table_idx} location on page: {region.page_number} is {format_polygon(region.polygon)}"

+ )

+ for cell in table.cells:

+ print(

+ f"...Cell[{cell.row_index}][{cell.column_index}] has text '{cell.content}'"

+ )

+ for region in cell.bounding_regions:

+ print(

+ f"...content on page {region.page_number} is within bounding polygon '{format_polygon(region.polygon)}'"

+ )

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Add-on_capabilities/sample_analyze_addon_highres.py)

+### [Output](#tab/output)

+```json

+"styles": [true],

+"pages": [

+ {

+ "page_number": 1,

+ "width": 1000,

+ "height": 800,

+ "unit": "px",

+ "lines": [

+ {

+ "line_idx": 1,

+ "content": "This",

+ "polygon": [10, 20, 30, 40],

+ "words": [

+ {

+ "content": "This",

+ "confidence": 0.98

+ }

+ ]

+ }

+ ],

+ "selection_marks": [

+ {

+ "state": "selected",

+ "polygon": [50, 60, 70, 80],

+ "confidence": 0.91

+ }

+ ]

+ }

+],

+"tables": [

+ {

+ "table_idx": 1,

+ "row_count": 3,

+ "column_count": 4,

+ "bounding_regions": [

+ {

+ "page_number": 1,

+ "polygon": [100, 200, 300, 400]

+ }

+ ],

+ "cells": [

+ {

+ "row_index": 1,

+ "column_index": 1,

+ "content": "Content 1",

+ "bounding_regions": [

+ {

+ "page_number": 1,

+ "polygon": [110, 210, 310, 410]

+ }

+ ]

+ }

+ ]

+ }

+]

+```

+### [REST API](#tab/rest-api)

+### [Sample code](#tab/sample-code)

+```Python

+# Analyze a document at a URL:

+formUrl = "https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Data/add-on/layout-formulas.png?raw=true"

+poller = document_intelligence_client.begin_analyze_document(

+ "prebuilt-layout",

+ AnalyzeDocumentRequest(url_source=formUrl),

+ features=[DocumentAnalysisFeature.FORMULAS], # Specify which add-on capabilities to enable

+)

+result: AnalyzeResult = poller.result()

+# [START analyze_formulas]

+for page in result.pages:

+ print(f"-Formulas detected from page #{page.page_number}-")

+ if page.formulas:

+ inline_formulas = [f for f in page.formulas if f.kind == "inline"]

+ display_formulas = [f for f in page.formulas if f.kind == "display"]

+ # To learn the detailed concept of "polygon" in the following content, visit: https://aka.ms/bounding-region

+ print(f"Detected {len(inline_formulas)} inline formulas.")

+ for formula_idx, formula in enumerate(inline_formulas):

+ print(f"- Inline #{formula_idx}: {formula.value}")

+ print(f" Confidence: {formula.confidence}")

+ print(f" Bounding regions: {formula.polygon}")

+ print(f"\nDetected {len(display_formulas)} display formulas.")

+ for formula_idx, formula in enumerate(display_formulas):

+ print(f"- Display #{formula_idx}: {formula.value}")

+ print(f" Confidence: {formula.confidence}")

+ print(f" Bounding regions: {formula.polygon}")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Add-on_capabilities/sample_analyze_addon_formulas.py)

+### [Output](#tab/output)

+```json

+"content": ":formula:",

+ "pages": [

+ {

+ "pageNumber": 1,

+ "formulas": [

+ {

+ "kind": "inline",

+ "value": "\\frac { \\partial a } { \\partial b }",

+ "polygon": [...],

+ "span": {...},

+ "confidence": 0.99

+ },

+ {

+ "kind": "display",

+ "value": "y = a \\times b + a \\times c",

+ "polygon": [...],

+ "span": {...},

+ "confidence": 0.99

+ }

+ ]

+ }

+ ]

+```

+### [REST API](#tab/rest-api)

+### [Sample code](#tab/sample-code)

+```Python

+# Analyze a document at a URL:

+url = "https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Data/add-on/layout-formulas.png?raw=true"

+poller = document_analysis_client.begin_analyze_document_from_url(

+ "prebuilt-layout", document_url=url, features=[AnalysisFeature.FORMULAS] # Specify which add-on capabilities to enable

+)

+result = poller.result()

+# [START analyze_formulas]

+for page in result.pages:

+ print(f"-Formulas detected from page #{page.page_number}-")

+ inline_formulas = [f for f in page.formulas if f.kind == "inline"]

+ display_formulas = [f for f in page.formulas if f.kind == "display"]

+ print(f"Detected {len(inline_formulas)} inline formulas.")

+ for formula_idx, formula in enumerate(inline_formulas):

+ print(f"- Inline #{formula_idx}: {formula.value}")

+ print(f" Confidence: {formula.confidence}")

+ print(f" Bounding regions: {format_polygon(formula.polygon)}")

+ print(f"\nDetected {len(display_formulas)} display formulas.")

+ for formula_idx, formula in enumerate(display_formulas):

+ print(f"- Display #{formula_idx}: {formula.value}")

+ print(f" Confidence: {formula.confidence}")

+ print(f" Bounding regions: {format_polygon(formula.polygon)}")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Add-on_capabilities/sample_analyze_addon_formulas.py)

+### [Output](#tab/output)

+```json

+ "content": ":formula:",

+ "pages": [

+ {

+ "pageNumber": 1,

+ "formulas": [

+ {

+ "kind": "inline",

+ "value": "\\frac { \\partial a } { \\partial b }",

+ "polygon": [...],

+ "span": {...},

+ "confidence": 0.99

+ },

+ {

+ "kind": "display",

+ "value": "y = a \\times b + a \\times c",

+ "polygon": [...],

+ "span": {...},

+ "confidence": 0.99

+ }

+ ]

+ }

+ ]

+```

+### [REST API](#tab/rest-api)

+### [Sample code](#tab/sample-code)

+```Python

+# Analyze a document at a URL:

+formUrl = "https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Data/receipt/receipt-with-tips.png?raw=true"

+poller = document_intelligence_client.begin_analyze_document(

+ "prebuilt-layout",

+ AnalyzeDocumentRequest(url_source=formUrl),

+ features=[DocumentAnalysisFeature.STYLE_FONT] # Specify which add-on capabilities to enable.

+)

+result: AnalyzeResult = poller.result()

+# [START analyze_fonts]

+# DocumentStyle has the following font related attributes:

+similar_font_families = defaultdict(list) # e.g., 'Arial, sans-serif

+font_styles = defaultdict(list) # e.g, 'italic'

+font_weights = defaultdict(list) # e.g., 'bold'

+font_colors = defaultdict(list) # in '#rrggbb' hexadecimal format

+font_background_colors = defaultdict(list) # in '#rrggbb' hexadecimal format

+if result.styles and any([style.is_handwritten for style in result.styles]):

+ print("Document contains handwritten content")

+else:

+ print("Document does not contain handwritten content")

+ return

+print("\n-Fonts styles detected in the document-")

+# Iterate over the styles and group them by their font attributes.

+for style in result.styles:

+ if style.similar_font_family:

+ similar_font_families[style.similar_font_family].append(style)

+ if style.font_style:

+ font_styles[style.font_style].append(style)

+ if style.font_weight:

+ font_weights[style.font_weight].append(style)

+ if style.color:

+ font_colors[style.color].append(style)

+ if style.background_color:

+ font_background_colors[style.background_color].append(style)

+print(f"Detected {len(similar_font_families)} font families:")

+for font_family, styles in similar_font_families.items():

+ print(f"- Font family: '{font_family}'")

+ print(f" Text: '{get_styled_text(styles, result.content)}'")

+print(f"\nDetected {len(font_styles)} font styles:")

+for font_style, styles in font_styles.items():

+ print(f"- Font style: '{font_style}'")

+ print(f" Text: '{get_styled_text(styles, result.content)}'")

+print(f"\nDetected {len(font_weights)} font weights:")

+for font_weight, styles in font_weights.items():

+ print(f"- Font weight: '{font_weight}'")

+ print(f" Text: '{get_styled_text(styles, result.content)}'")

+print(f"\nDetected {len(font_colors)} font colors:")

+for font_color, styles in font_colors.items():

+ print(f"- Font color: '{font_color}'")

+ print(f" Text: '{get_styled_text(styles, result.content)}'")

+print(f"\nDetected {len(font_background_colors)} font background colors:")

+for font_background_color, styles in font_background_colors.items():

+ print(f"- Font background color: '{font_background_color}'")

+ print(f" Text: '{get_styled_text(styles, result.content)}'")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Add-on_capabilities/sample_analyze_addon_fonts.py)

+### [Output](#tab/output)

+```json

+"content": "Foo bar",

+"styles": [

+ {

+ "similarFontFamily": "Arial, sans-serif",

+ "spans": [ { "offset": 0, "length": 3 } ],

+ "confidence": 0.98

+ },

+ {

+ "similarFontFamily": "Times New Roman, serif",

+ "spans": [ { "offset": 4, "length": 3 } ],

+ "confidence": 0.98

+ },

+ {

+ "fontStyle": "italic",

+ "spans": [ { "offset": 1, "length": 2 } ],

+ "confidence": 0.98

+ },

+ {

+ "fontWeight": "bold",

+ "spans": [ { "offset": 2, "length": 3 } ],

+ "confidence": 0.98

+ },

+ {

+ "color": "#FF0000",

+ "spans": [ { "offset": 4, "length": 2 } ],

+ "confidence": 0.98

+ },

+ {

+ "backgroundColor": "#00FF00",

+ "spans": [ { "offset": 5, "length": 2 } ],

+ "confidence": 0.98

+ }

+ ]

+```

+### [REST API](#tab/rest-api)

+### [Sample code](#tab/sample-code)

+```Python

+# Analyze a document at a URL:

+url = "https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Data/receipt/receipt-with-tips.png?raw=true"

+poller = document_analysis_client.begin_analyze_document_from_url(

+ "prebuilt-layout", document_url=url, features=[AnalysisFeature.STYLE_FONT] # Specify which add-on capabilities to enable.

+)

+result = poller.result()

+# [START analyze_fonts]

+# DocumentStyle has the following font related attributes:

+similar_font_families = defaultdict(list) # e.g., 'Arial, sans-serif

+font_styles = defaultdict(list) # e.g, 'italic'

+font_weights = defaultdict(list) # e.g., 'bold'

+font_colors = defaultdict(list) # in '#rrggbb' hexadecimal format

+font_background_colors = defaultdict(list) # in '#rrggbb' hexadecimal format

+if any([style.is_handwritten for style in result.styles]):

+ print("Document contains handwritten content")

+else:

+ print("Document does not contain handwritten content")

+print("\n-Fonts styles detected in the document-")

+# Iterate over the styles and group them by their font attributes.

+for style in result.styles:

+ if style.similar_font_family:

+ similar_font_families[style.similar_font_family].append(style)

+ if style.font_style:

+ font_styles[style.font_style].append(style)

+ if style.font_weight:

+ font_weights[style.font_weight].append(style)

+ if style.color:

+ font_colors[style.color].append(style)

+ if style.background_color:

+ font_background_colors[style.background_color].append(style)

+print(f"Detected {len(similar_font_families)} font families:")

+for font_family, styles in similar_font_families.items():

+ print(f"- Font family: '{font_family}'")

+ print(f" Text: '{get_styled_text(styles, result.content)}'")

+print(f"\nDetected {len(font_styles)} font styles:")

+for font_style, styles in font_styles.items():

+ print(f"- Font style: '{font_style}'")

+ print(f" Text: '{get_styled_text(styles, result.content)}'")

+print(f"\nDetected {len(font_weights)} font weights:")

+for font_weight, styles in font_weights.items():

+ print(f"- Font weight: '{font_weight}'")

+ print(f" Text: '{get_styled_text(styles, result.content)}'")

+print(f"\nDetected {len(font_colors)} font colors:")

+for font_color, styles in font_colors.items():

+ print(f"- Font color: '{font_color}'")

+ print(f" Text: '{get_styled_text(styles, result.content)}'")

+print(f"\nDetected {len(font_background_colors)} font background colors:")

+for font_background_color, styles in font_background_colors.items():

+ print(f"- Font background color: '{font_background_color}'")

+ print(f" Text: '{get_styled_text(styles, result.content)}'")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Add-on_capabilities/sample_analyze_addon_fonts.py)

+### [Output](#tab/output)

+```json

+"content": "Foo bar",

+"styles": [

+ {

+ "similarFontFamily": "Arial, sans-serif",

+ "spans": [ { "offset": 0, "length": 3 } ],

+ "confidence": 0.98

+ },

+ {

+ "similarFontFamily": "Times New Roman, serif",

+ "spans": [ { "offset": 4, "length": 3 } ],

+ "confidence": 0.98

+ },

+ {

+ "fontStyle": "italic",

+ "spans": [ { "offset": 1, "length": 2 } ],

+ "confidence": 0.98

+ },

+ {

+ "fontWeight": "bold",

+ "spans": [ { "offset": 2, "length": 3 } ],

+ "confidence": 0.98

+ },

+ {

+ "color": "#FF0000",

+ "spans": [ { "offset": 4, "length": 2 } ],

+ "confidence": 0.98

+ },

+ {

+ "backgroundColor": "#00FF00",

+ "spans": [ { "offset": 5, "length": 2 } ],

+ "confidence": 0.98

+ }

+ ]

+```

+### [REST API](#tab/rest-api)

+### [Sample code](#tab/sample-code)

+```Python

+# Analyze a document at a URL:

+formUrl = "https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Data/add-on/add-on-barcodes.jpg?raw=true"

+poller = document_intelligence_client.begin_analyze_document(

+ "prebuilt-read",

+ AnalyzeDocumentRequest(url_source=formUrl),

+ features=[DocumentAnalysisFeature.BARCODES] # Specify which add-on capabilities to enable.

+)

+result: AnalyzeResult = poller.result()

+# [START analyze_barcodes]

+# Iterate over extracted barcodes on each page.

+for page in result.pages:

+ print(f"-Barcodes detected from page #{page.page_number}-")

+ if page.barcodes:

+ print(f"Detected {len(page.barcodes)} barcodes:")

+ for barcode_idx, barcode in enumerate(page.barcodes):

+ print(f"- Barcode #{barcode_idx}: {barcode.value}")

+ print(f" Kind: {barcode.kind}")

+ print(f" Confidence: {barcode.confidence}")

+ print(f" Bounding regions: {barcode.polygon}")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Add-on_capabilities/sample_analyze_addon_barcodes.py)

+### [Output](#tab/output)

+```json

+-Barcodes detected from page #1-

+Detected 2 barcodes:

+- Barcode #0: 123456

+ Kind: QRCode

+ Confidence: 0.95

+ Bounding regions: [10.5, 20.5, 30.5, 40.5]

+- Barcode #1: 789012

+ Kind: QRCode

+ Confidence: 0.98

+ Bounding regions: [50.5, 60.5, 70.5, 80.5]

+```

+### [REST API](#tab/rest-api)

+### [Sample code](#tab/sample-code)

+```Python

+# Analyze a document at a URL:

+url = "https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Data/add-on/add-on-barcodes.jpg?raw=true"

+poller = document_analysis_client.begin_analyze_document_from_url(

+ "prebuilt-layout", document_url=url, features=[AnalysisFeature.BARCODES] # Specify which add-on capabilities to enable.

+)

+result = poller.result()

+# [START analyze_barcodes]

+# Iterate over extracted barcodes on each page.

+for page in result.pages:

+ print(f"-Barcodes detected from page #{page.page_number}-")

+ print(f"Detected {len(page.barcodes)} barcodes:")

+ for barcode_idx, barcode in enumerate(page.barcodes):

+ print(f"- Barcode #{barcode_idx}: {barcode.value}")

+ print(f" Kind: {barcode.kind}")

+ print(f" Confidence: {barcode.confidence}")

+ print(f" Bounding regions: {format_polygon(barcode.polygon)}")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Add-on_capabilities/sample_analyze_addon_barcodes.py)

+### [Output](#tab/output)

+```json

+-Barcodes detected from page #1-

+Detected 2 barcodes:

+- Barcode #0: 123456

+ Kind: QRCode

+ Confidence: 0.95

+ Bounding regions: [10.5, 20.5, 30.5, 40.5]

+- Barcode #1: 789012

+ Kind: QRCode

+ Confidence: 0.98

+ Bounding regions: [50.5, 60.5, 70.5, 80.5]

+```

+### [REST API](#tab/rest-api)

+```bash

+{your-resource-endpoint}.cognitiveservices.azure.com/documentintelligence/documentModels/prebuilt-layout:analyze?api-version=2024-02-29-preview&features=languages

+```

+### [Sample code](#tab/sample-code)

+```Python

+# Analyze a document at a URL:

+formUrl = "https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Data/add-on/add-on-fonts_and_languages.png?raw=true"

+poller = document_intelligence_client.begin_analyze_document(

+ "prebuilt-layout",

+ AnalyzeDocumentRequest(url_source=formUrl),

+ features=[DocumentAnalysisFeature.LANGUAGES] # Specify which add-on capabilities to enable.

+)

+result: AnalyzeResult = poller.result()

+# [START analyze_languages]

+print("-Languages detected in the document-")

+if result.languages:

+ print(f"Detected {len(result.languages)} languages:")

+ for lang_idx, lang in enumerate(result.languages):

+ print(f"- Language #{lang_idx}: locale '{lang.locale}'")

+ print(f" Confidence: {lang.confidence}")

+ print(

+ f" Text: '{','.join([result.content[span.offset : span.offset + span.length] for span in lang.spans])}'"

+ )

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Add-on_capabilities/sample_analyze_addon_languages.py)

+### [Output](#tab/output)

+### [REST API](#tab/rest-api)

+### [Sample code](#tab/sample-code)

+```Python

+# Analyze a document at a URL:

+url = "https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Data/add-on/add-on-fonts_and_languages.png?raw=true"

+poller = document_analysis_client.begin_analyze_document_from_url(

+ "prebuilt-layout", document_url=url, features=[AnalysisFeature.LANGUAGES] # Specify which add-on capabilities to enable.

+)

+result = poller.result()

+# [START analyze_languages]

+print("-Languages detected in the document-")

+print(f"Detected {len(result.languages)} languages:")

+for lang_idx, lang in enumerate(result.languages):

+ print(f"- Language #{lang_idx}: locale '{lang.locale}'")

+ print(f" Confidence: {lang.confidence}")

+ print(f" Text: '{','.join([result.content[span.offset : span.offset + span.length] for span in lang.spans])}'")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Add-on_capabilities/sample_analyze_addon_languages.py)

+### [Output](#tab/output)

+```json

+"languages": [

+ {

+ "spans": [

+ {

+ "offset": 0,

+ "length": 131

+ }

+ ],

+ "locale": "en",

+ "confidence": 0.7

+ },

+]

+```

+### [REST API](#tab/rest-api)

+### [Sample code](#tab/sample-code)

+```Python

+# Analyze a document at a URL:

+formUrl = "https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Data/invoice/simple-invoice.png?raw=true"

+poller = document_intelligence_client.begin_analyze_document(

+ "prebuilt-layout",

+ AnalyzeDocumentRequest(url_source=formUrl),

+ features=[DocumentAnalysisFeature.QUERY_FIELDS], # Specify which add-on capabilities to enable.

+ query_fields=["Address", "InvoiceNumber"], # Set the features and provide a comma-separated list of field names.

+)

+result: AnalyzeResult = poller.result()

+print("Here are extra fields in result:\n")

+if result.documents:

+ for doc in result.documents:

+ if doc.fields and doc.fields["Address"]:

+ print(f"Address: {doc.fields['Address'].value_string}")

+ if doc.fields and doc.fields["InvoiceNumber"]:

+ print(f"Invoice number: {doc.fields['InvoiceNumber'].value_string}")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Add-on_capabilities/sample_analyze_addon_query_fields.py)

+### [Output](#tab/output)

+```json

+Address: 1 Redmond way Suite 6000 Redmond, WA Sunnayvale, 99243

+Invoice number: 34278587

+```

+> [!div class="nextstepaction"]

+> Find more samples:

+> [**Add-on capabilities**](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/main/Python(v4.0)/Add-on_capabilities)

+> [!div class="nextstepaction"]

+> Find more samples:

+> [**Add-on capabilities**](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/v3.1(2023-07-31-GA)/Python(v3.1)/Add-on_capabilities)

+The Document Intelligence business card model combines powerful Optical Character Recognition (OCR) capabilities with deep learning models to analyze and extract data from business card images. The API analyzes printed business cards; extracts key information such as first name, surname, company name, email address, and phone number; and returns a structured JSON data representation.

+Business cards are a great way to represent a business or a professional. The company logo, fonts, and background images found in business cards help promote the company branding and differentiate it from others. Applying OCR and machine-learning based techniques to automate scanning of business cards is a common image processing scenario. Enterprise systems used by sales and marketing teams typically have business card data extraction capability integration into for the benefit of their users.

+|**Business card model**| &bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=businessCard)<br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)<br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)<br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)<br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)<br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)|**prebuilt-businessCard**|

+1. View the results - see the key-value pairs extracted, line items, highlighted text extracted, and tables detected.

+* The supported file formats: JPEG, PNG, PDF, and TIFF

+* PDF and TIFF, up to 2,000 pages are processed. For free tier subscribers, only the first two pages are processed.

+| CompanyNames | Array of strings | Company name| |

+| Departments | Array of strings | Department or organization of contact | |

+| JobTitles | Array of strings | Listed Job title of contact | |

+| Emails | Array of strings | Contact email address | |

+| Websites | Array of strings | Company website | |

+| Addresses | Array of strings | Address extracted from business card | |

+| MobilePhones | Array of phone numbers | Mobile phone number from business card |+1 xxx xxx xxxx |

+| Faxes | Array of phone numbers | Fax phone number from business card | +1 xxx xxx xxxx |

+| WorkPhones | Array of phone numbers | Work phone number from business card | +1 xxx xxx xxxx |

+| OtherPhones | Array of phone numbers | Other phone number from business card | +1 xxx xxx xxxx |

+| Addresses | array of strings | Address extracted from business card | ["123 Main Street, Redmond, Washington 98052"] |

+|_**Custom model**_| &bullet; [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</br>&bullet; [REST API](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)</br>&bullet; [C# SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [Java SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [JavaScript SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [Python SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)|

+| _**Composed model**_| &bullet; [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects)</br>&bullet; [REST API](/rest/api/aiservices/document-models/compose-model?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)</br>&bullet; [C# SDK](/dotnet/api/azure.ai.formrecognizer.training.formtrainingclient.startcreatecomposedmodel)</br>&bullet; [Java SDK](/java/api/com.azure.ai.formrecognizer.training.formtrainingclient.begincreatecomposedmodel)</br>&bullet; [JavaScript SDK](/javascript/api/@azure/ai-form-recognizer/documentmodeladministrationclient?view=azure-node-latest#@azure-ai-form-recognizer-documentmodeladministrationclient-begincomposemodel&preserve-view=true)</br>&bullet; [Python SDK](/python/api/azure-ai-formrecognizer/azure.ai.formrecognizer.formtrainingclient?view=azure-python#azure-ai-formrecognizer-formtrainingclient-begin-create-composed-model&preserve-view=true)|

+| _**Composed model**_ |&bullet; [Document Intelligence labeling tool](https://fott-2-1.azurewebsites.net/)</br>&bullet; [REST API](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true)</br>&bullet; [C# SDK](/dotnet/api/azure.ai.formrecognizer.training.createcomposedmodeloperation?view=azure-dotnet&preserve-view=true)</br>&bullet; [Java SDK](/java/api/com.azure.ai.formrecognizer.models.createcomposedmodeloptions?view=azure-java-stable&preserve-view=true)</br>&bullet; JavaScript SDK</br>&bullet; [Python SDK](/python/api/azure-ai-formrecognizer/azure.ai.formrecognizer.formtrainingclient?view=azure-python#azure-ai-formrecognizer-formtrainingclient-begin-create-composed-model&preserve-view=true)|

+|**Contract model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)|**prebuilt-contract**|

+> Use the [**REST API**](/rest/api/aiservices/document-models/copy-model-to?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP) or [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/custommodel/projects) to copy a model to another region.

+Custom (template) models are generally available with the [v2.1 API](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true).

+| Custom model (template) | [Document Intelligence 2.1 ](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true)| [Document Intelligence SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-2.1.0&preserve-view=true?pivots=programming-language-python)| [Document Intelligence Sample labeling tool](https://fott-2-1.azurewebsites.net/)|

+| Custom form v2.1 | [Document Intelligence 2.1 GA API](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true) | [Document Intelligence SDK](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-2.1.0&preserve-view=true?pivots=programming-language-python)| [Sample labeling tool](https://fott-2-1.azurewebsites.net/)|

+> [!IMPORTANT]

+>

+> * There are separate URLs for Document Intelligence Studio sovereign cloud regions.

+> * Azure for US Government: [Document Intelligence Studio (Azure Fairfax cloud)](https://formrecognizer.appliedai.azure.us/studio)

+> * Microsoft Azure operated by 21Vianet: [Document Intelligence Studio (Azure in China)](https://formrecognizer.appliedai.azure.cn/studio)

+* Get sample code for the language-specific `SDKs` to integrate into your applications.

+Use the [Document Intelligence Studio quickstart](quickstarts/try-document-intelligence-studio.md) to get started analyzing documents with document analysis or prebuilt models. Build custom models and reference the models in your applications using one of the [language specific `SDKs`](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true) and other quickstarts.

+If you're visiting the Studio for the first time, follow the [getting started guide](studio-overview.md#get-started) to set up the Studio for use.

+* Use the custom extraction model labeling page to navigate through your training documents with ease by making use of the search, filter, and sort by feature.

+* **Custom extraction models**: Document Intelligence's custom models enable you to extract fields and values from models trained with your data, tailored to your forms and documents. To extract data from multiple form types, create standalone custom models or combine two, or more, custom models and create a composed model. Start with the [Studio Custom models feature](https://documentintelligence.ai.azure.com/studio/custommodel/projects). Use the help wizard, labeling interface, training step, and visualizations to understand how the feature works. Test the custom model with your sample documents and iterate to improve the model. To learn more, *see* the [Custom models overview](concept-custom.md) to learn more.

+* **Custom classification models**: Document classification is a new scenario supported by Document Intelligence. the document classifier API supports classification and splitting scenarios. Train a classification model to identify the different types of documents your application supports. The input file for the classification model can contain multiple documents and classifies each document within an associated page range. To learn more, *see* [custom classification models](concept-custom-classifier.md).

+* **Add-on Capabilities**: Document Intelligence now supports more sophisticated analysis capabilities. These optional capabilities can be enabled and disabled in the studio using the `Analze Options` button in each model page. There are four add-on capabilities available: highResolution, formula, font, and barcode extraction capabilities. To learn more, *see* [Add-on capabilities](concept-add-on-capabilities.md).

+|**General document model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)|**prebuilt-document**|

+|**Health insurance card model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)|**prebuilt-healthInsuranceCard.us**|

+|**ID document model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)|**prebuilt-idDocument**|

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Prebuilt_model/sample_analyze_identity_documents.py)

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Prebuilt_model/sample_analyze_identity_documents.py)

+* [Find more samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/main/Python(v4.0)/Prebuilt_model)

+* [Find more samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/v3.1(2023-07-31-GA)/Python(v3.1)/Prebuilt_model)

+The incremental classifier build request is similar to the [classify document build request](/rest/api/aiservices/document-classifiers?view=rest-aiservices-v4.0%20(2024-02-29-preview)&preserve-view=true) but includes the new `baseClassifierId` property. The `baseClassifierId` is set to the existing classifier that you want to extend. You also need to provide the `docTypes` for the different document types in the sample set. By providing a `docType` that exists in the baseClassifier, the samples provided in the request are added to the samples provided when the base classifier was trained. New `docType` values added in the incremental training are only added to the new classifier. The process to specify the samples remains unchanged. For more information, *see* [training a classifier model](concept-custom-classifier.md#training-a-model).

+|**Invoice model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)|**prebuilt-invoice**|

+The Document Intelligence invoice model `prebuilt-invoice` extracts the following fields.

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Prebuilt_model/sample_analyze_invoices.py)

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Prebuilt_model/sample_analyze_invoices.py)

+|:--|:-|:-|:-|

+| CustomerName |string | Invoiced customer|Microsoft Corp|

+| CustomerId |string | Customer reference ID |CID-12345 |

+| PurchaseOrder |string | Purchase order reference number |PO-3333 |

+| InvoiceId |string | ID for this specific invoice (often Invoice Number) |INV-100 |

+| InvoiceDate |date |date the invoice was issued | mm-dd-yyyy|

+| DueDate |date |date payment for this invoice is due |mm-dd-yyyy|

+| VendorName |string | Vendor who created this invoice |CONTOSO LTD.|

+| VendorAddress |address| Vendor mailing address| 123 456th St, New York, NY 10001 |

+| VendorAddressRecipient |string | Name associated with the VendorAddress |Contoso Headquarters |

+| CustomerAddress |address | Mailing address for the Customer | 123 Other St, Redmond WA, 98052|

+| CustomerAddressRecipient |string | Name associated with the CustomerAddress |Microsoft Corp |

+| BillingAddress |address | Explicit billing address for the customer | 123 Bill St, Redmond WA, 98052 |

+| BillingAddressRecipient |string | Name associated with the BillingAddress |Microsoft Services |

+| ShippingAddress |address | Explicit shipping address for the customer | 123 Ship St, Redmond WA, 98052|

+| ShippingAddressRecipient |string | Name associated with the ShippingAddress |Microsoft Delivery |

+|Sub&#8203;Total| currency| Subtotal field identified on this invoice | $100.00 |

+| TotalDiscount | currency | The total discount applied to an invoice | $5.00 |

+| TotalTax | currency| Total tax field identified on this invoice | $10.00 |

+| InvoiceTotal | currency | Total new charges associated with this invoice | $10.00 |

+| AmountDue | currency | Total Amount Due to the vendor | $610 |

+| PreviousUnpaidBalance | currency| Explicit previously unpaid balance | $500.00 |

+| RemittanceAddress |address| Explicit remittance or payment address for the customer |123 Remit St New York, NY, 10001 |

+| RemittanceAddressRecipient |string | Name associated with the RemittanceAddress |Contoso Billing |

+| ServiceAddress |address | Explicit service address or property address for the customer |123 Service St, Redmond WA, 98052 |

+| ServiceAddressRecipient |string | Name associated with the ServiceAddress |Microsoft Services |

+| ServiceStartDate |date | First date for the service period (for example, a utility bill service period) | mm-dd-yyyy |

+| ServiceEndDate |date | End date for the service period (for example, a utility bill service period) | mm-dd-yyyy|

+| VendorTaxId |string | The taxpayer number associated with the vendor |123456-7 |

+|CustomerTaxId|string|The taxpayer number associated with the customer|765432-1|

+| PaymentTerm |string | The terms of payment for the invoice |Net90 |

+| KVKNumber |string | A unique identifier for businesses registered in the Netherlands (NL-only)|12345678|

+| CurrencyCode |string | The currency code associated with the extracted amount | |

+| PaymentDetails | array | An array that holds Payment Option details such as `IBAN`,`SWIFT`, `BPayBillerCode(AU)`, `BPayReference(AU)` | |

+|TaxDetails|array|An array that holds tax details like amount and rate||

+| TaxDetails | array | AN array that holds added tax information such as `CGST`, `IGST`, and `SGST`. This line item is currently only available for the Germany (`de`), Spain (`es`), Portugal (`pt`), and English Canada (`en-CA`) locales| |

+### Line items array

+|Name| Type | Description | Value (standardized output) |

+|:--|:-|:-|:-|

+| Amount | currency | The amount of the line item | $60.00 |

+| Date | date| Date corresponding to each line item. Often it's a date the line item was shipped | 3/4/2021|

+| Description | string | The text description for the invoice line item | Consulting service|

+| Quantity | number | The quantity for this invoice line item | 2 |

+| ProductCode | string| Product code, product number, or SKU associated with the specific line item | A123|

+| Tax | currency | Tax associated with each line item. Possible values include tax amount and tax Y/N | $6.00 |

+| TaxRate | string | Tax Rate associated with each line item. | 18%|

+| Unit | string| The unit of the line item, e.g, kg, lb etc. | Hours|

+| UnitPrice | number | The net or gross price (depending on the gross invoice setting of the invoice) of one unit of this item | $30.00 |

+The following are complex fields extracted from an invoice in the JSON output response:

+### TaxDetails

+Tax details aims at breaking down the different taxes applied to the invoice total.

+|Name| Type | Description | Text (line item #1) | Value (standardized output) |

+|:--|:-|:-|:-| :-|

+| Items | string | Full string text line of the tax item | V.A.T. 15% $60.00 | |

+| Amount | number | The tax amount of the tax item | 60.00 | 60 |

+| Rate | string | The tax rate of the tax item | 15% | |

+### PaymentDetails

+List all the detected payment options detected on the field.

+|Name| Type | Description | Text (line item #1) | Value (standardized output) |

+|:--|:-|:-|:-| :-|

+| IBAN | string | Internal Bank Account Number | GB33BUKB20201555555555 | |

+| SWIFT | string | SWIFT code | BUKBGB22 | |

+| BPayBillerCode | string | Australian B-Pay Biller Code | 12345 | |

+| BPayReference | string | Australian B-Pay Reference Code | 98765432100 | |

+* [Find more samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/main/Python(v4.0)/Prebuilt_model)

+* [Find more samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/v3.1(2023-07-31-GA)/Python(v3.1)/Prebuilt_model)

+|**Layout model**|&bullet; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)|**prebuilt-layout**|

+#### [Sample code](#tab/sample-code)

+```Python

+# Analyze pages.

+for page in result.pages:

+ print(f"-Analyzing layout from page #{page.page_number}-")

+ print(

+ f"Page has width: {page.width} and height: {page.height}, measured with unit: {page.unit}"

+ )

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Layout_model/sample_analyze_layout.py)

+#### [Output](#tab/output)

+```json

+"pages": [

+ {

+ "pageNumber": 1,

+ "angle": 0,

+ "width": 915,

+ "height": 1190,

+ "unit": "pixel",

+ "words": [],

+ "lines": [],

+ "spans": []

+ }

+]

+```

+#### [Sample code](#tab/sample-code)

+```Python

+# Analyze pages.

+for page in result.pages:

+ print(f"-Analyzing layout from page #{page.page_number}-")

+ print(f"Page has width: {page.width} and height: {page.height}, measured with unit: {page.unit}")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Layout_model/sample_analyze_layout.py)

+#### [Output](#tab/output)

+```json

+"pages": [

+ {

+ "pageNumber": 1,

+ "angle": 0,

+ "width": 915,

+ "height": 1190,

+ "unit": "pixel",

+ "words": [],

+ "lines": [],

+ "spans": []

+ }

+]

+```

+#### [Sample code](#tab/sample-code)

+```Python

+# Analyze lines.

+for line_idx, line in enumerate(page.lines):

+ words = line.get_words()

+ print(

+ f"...Line # {line_idx} has word count {len(words)} and text '{line.content}' "

+ f"within bounding polygon '{format_polygon(line.polygon)}'"

+ )

+ # Analyze words.

+ for word in words:

+ print(

+ f"......Word '{word.content}' has a confidence of {word.confidence}"

+ )

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Layout_model/sample_analyze_layout.py)

+#### [Output](#tab/output)

+```json

+"words": [

+ {

+ "content": "While",

+ "polygon": [],

+ "confidence": 0.997,

+ "span": {}

+ },

+],

+"lines": [

+ {

+ "content": "While healthcare is still in the early stages of its Al journey, we",

+ "polygon": [],

+ "spans": [],

+ }

+]

+```

+#### [Sample code](#tab/sample-code)

+```Python

+# Analyze lines.

+if page.lines:

+ for line_idx, line in enumerate(page.lines):

+ words = get_words(page, line)

+ print(

+ f"...Line # {line_idx} has word count {len(words)} and text '{line.content}' "

+ f"within bounding polygon '{line.polygon}'"

+ )

+ # Analyze words.

+ for word in words:

+ print(f"......Word '{word.content}' has a confidence of {word.confidence}")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Layout_model/sample_analyze_layout.py)

+#### [Output](#tab/output)

+```json

+"words": [

+ {

+ "content": "While",

+ "polygon": [],

+ "confidence": 0.997,

+ "span": {}

+ },

+],

+"lines": [

+ {

+ "content": "While healthcare is still in the early stages of its Al journey, we",

+ "polygon": [],

+ "spans": [],

+ }

+]

+```

+```json

+{

+ "selectionMarks": [

+ {

+ "state": "unselected",

+ "polygon": [],

+ "confidence": 0.995,

+ "span": {

+ "offset": 1421,

+ "length": 12

+ }

+ }

+ ]

+}

+```

+#### [Sample code](#tab/sample-code)

+```Python

+# Analyze selection marks.

+for selection_mark in page.selection_marks:

+ print(

+ f"Selection mark is '{selection_mark.state}' within bounding polygon "

+ f"'{format_polygon(selection_mark.polygon)}' and has a confidence of {selection_mark.confidence}"

+ )

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Layout_model/sample_analyze_layout.py)

+#### [Output](#tab/output)

+#### [Sample code](#tab/sample-code)

+```Python

+# Analyze selection marks.

+if page.selection_marks:

+ for selection_mark in page.selection_marks:

+ print(

+ f"Selection mark is '{selection_mark.state}' within bounding polygon "

+ f"'{selection_mark.polygon}' and has a confidence of {selection_mark.confidence}"

+ )

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Layout_model/sample_analyze_layout.py)

+#### [Output](#tab/output)

+```json

+{

+ "selectionMarks": [

+ {

+ "state": "unselected",

+ "polygon": [],

+ "confidence": 0.995,

+ "span": {

+ "offset": 1421,

+ "length": 12

+ }

+ }

+ ]

+}

+```

+#### [Sample code](#tab/sample-code)

+```Python

+# Analyze tables.

+for table_idx, table in enumerate(result.tables):

+ print(

+ f"Table # {table_idx} has {table.row_count} rows and "

+ f"{table.column_count} columns"

+ )

+ for region in table.bounding_regions:

+ print(

+ f"Table # {table_idx} location on page: {region.page_number} is {format_polygon(region.polygon)}"

+ )

+ for cell in table.cells:

+ print(

+ f"...Cell[{cell.row_index}][{cell.column_index}] has text '{cell.content}'"

+ )

+ for region in cell.bounding_regions:

+ print(

+ f"...content on page {region.page_number} is within bounding polygon '{format_polygon(region.polygon)}'"

+ )

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Layout_model/sample_analyze_layout.py)

+#### [Output](#tab/output)

+```json

+{

+ "tables": [

+ {

+ "rowCount": 9,

+ "columnCount": 4,

+ "cells": [

+ {

+ "kind": "columnHeader",

+ "rowIndex": 0,

+ "columnIndex": 0,

+ "columnSpan": 4,

+ "content": "(In millions, except earnings per share)",

+ "boundingRegions": [],

+ "spans": []

+ },

+ ]

+ }

+ ]

+}

+```

+#### [Sample code](#tab/sample-code)

+```Python

+if result.tables:

+ for table_idx, table in enumerate(result.tables):

+ print(f"Table # {table_idx} has {table.row_count} rows and " f"{table.column_count} columns")

+ if table.bounding_regions:

+ for region in table.bounding_regions:

+ print(f"Table # {table_idx} location on page: {region.page_number} is {region.polygon}")

+ # Analyze cells.

+ for cell in table.cells:

+ print(f"...Cell[{cell.row_index}][{cell.column_index}] has text '{cell.content}'")

+ if cell.bounding_regions:

+ for region in cell.bounding_regions:

+ print(f"...content on page {region.page_number} is within bounding polygon '{region.polygon}'")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Layout_model/sample_analyze_layout.py)

+#### [Output](#tab/output)

+```json

+{

+ "tables": [

+ {

+ "rowCount": 9,

+ "columnCount": 4,

+ "cells": [

+ {

+ "kind": "columnHeader",

+ "rowIndex": 0,

+ "columnIndex": 0,

+ "columnSpan": 4,

+ "content": "(In millions, except earnings per share)",

+ "boundingRegions": [],

+ "spans": []

+ },

+ ]

+ }

+ ]

+}

+```

+#### [Sample code](#tab/sample-code)

+```Python

+document_intelligence_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))

+poller = document_intelligence_client.begin_analyze_document(

+ "prebuilt-layout",

+ AnalyzeDocumentRequest(url_source=url),

+ output_content_format=ContentFormat.MARKDOWN,

+)

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/samples/sample_analyze_documents_output_in_markdown.py)

+#### [Output](#tab/output)

+```Markdown

+<!-- PageHeader="This is the header of the document." -->

+This is title

+===

+# 1\. Text

+Latin refers to an ancient Italic language originating in the region of Latium in ancient Rome.

+# 2\. Page Objects

+## 2.1 Table

+Here's a sample table below, designed to be simple for easy understand and quick reference.

+| Name | Corp | Remark |

+| - | - | - |

+| Foo | | |

+| Bar | Microsoft | Dummy |

+Table 1: This is a dummy table

+## 2.2. Figure

+<figure>

+<figcaption>

+Figure 1: Here is a figure with text

+</figcaption>

+

+<!-- FigureContent="500 450 400 400 350 250 200 200 200- Feb" -->

+</figure>

+# 3\. Others

+Al Document Intelligence is an Al service that applies advanced machine learning to extract text, key-value pairs, tables, and structures from documents automatically and accurately:

+ :selected:

+clear

+ :selected:

+precise

+ :unselected:

+vague

+ :selected:

+coherent

+ :unselected:

+Incomprehensible

+Turn documents into usable data and shift your focus to acting on information rather than compiling it. Start with prebuilt models or create custom models tailored to your documents both on premises and in the cloud with the Al Document Intelligence studio or SDK.

+Learn how to accelerate your business processes by automating text extraction with Al Document Intelligence. This webinar features hands-on demos for key use cases such as document processing, knowledge mining, and industry-specific Al model customization.

+<!-- PageFooter="This is the footer of the document." -->

+<!-- PageFooter="1 | Page" -->

+```

+#### [Sample code](#tab/sample-code)

+```Python

+# Analyze figures.

+if result.figures:

+ for figures_idx,figures in enumerate(result.figures):

+ print(f"Figure # {figures_idx} has the following spans:{figures.spans}")

+ for region in figures.bounding_regions:

+ print(f"Figure # {figures_idx} location on page:{region.page_number} is within bounding polygon '{region.polygon}'")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Layout_model/sample_analyze_layout.py)

+#### [Output](#tab/output)

+#### [Sample code](#tab/sample-code)

+```Python

+document_intelligence_client = DocumentIntelligenceClient(endpoint=endpoint, credential=AzureKeyCredential(key))

+poller = document_intelligence_client.begin_analyze_document(

+ "prebuilt-layout",

+ AnalyzeDocumentRequest(url_source=url),

+ output_content_format=ContentFormat.MARKDOWN,

+)

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/documentintelligence/azure-ai-documentintelligence/samples/sample_analyze_documents_output_in_markdown.py)

+#### [Output](#tab/output)

+* [Find more samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/main/Python(v4.0)/Layout_model)

+* [Find more samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/v3.1(2023-07-31-GA)/Python(v3.1)/Layout_model)

+|**prebuilt-marriageCertificate.us**|&bullet; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=marriageCertificate.us&formType=marriageCertificate.us)</br>&bullet; [**REST API**](/rest/api/aiservices/operation-groups?view=rest-aiservices-2024-02-29-preview&preserve-view=true)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true)|**prebuilt-marriageCertificate.us**|

+|**Model Type**| **Model**|&bullet; [2024-02-29-preview](/rest/api/aiservices/document-models/build-model?view=rest-aiservices-2024-02-29-preview&preserve-view=true&branch=docintelligence&tabs=HTTP) <br> &bullet; [2023-10-31-preview](/rest/api/aiservices/operation-groups?view=rest-aiservices-2024-02-29-preview&preserve-view=true)|[2023-07-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)|[2022-08-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)|[v2.1 (GA)](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true)|

+|**Add-on Capability**| **Add-On/Free**|&bullet; [2024-02-29-preview](/rest/api/aiservices/document-models/build-model?view=rest-aiservices-2024-02-29-preview&preserve-view=true&branch=docintelligence&tabs=HTTP) <br>&bullet [2023-10-31-preview](/rest/api/aiservices/operation-groups?view=rest-aiservices-2024-02-29-preview&preserve-view=true|[`2023-07-31` (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)|[`2022-08-31` (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)|[v2.1 (GA)](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true)|

+* Uniform Residential Loan Application (Form 1003)

+* Uniform Underwriting and Transmittal Summary (Form 1008)

+* Closing Disclosure form

+## Field extraction 1003 Uniform Residential Loan Application (URLA)

+The following are the fields extracted from a 1003 URLA form in the JSON output response.

+The 1003 URLA key-value pairs and line items extracted are in the `documentResults` section of the JSON output.

+## Field extraction 1008 Uniform Underwriting and Transmittal Summary

+|**Read OCR model**|&bullet; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)|**prebuilt-read**|

+#### [Sample code](#tab/sample-code)

+```Python

+# Analyze pages.

+for page in result.pages:

+ print(f"-Analyzing document from page #{page.page_number}-")

+ print(

+ f"Page has width: {page.width} and height: {page.height}, measured with unit: {page.unit}"

+ )

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Read_model/sample_analyze_read.py)

+#### [Output](#tab/output)

+```json

+"pages": [

+ {

+ "pageNumber": 1,

+ "angle": 0,

+ "width": 915,

+ "height": 1190,

+ "unit": "pixel",

+ "words": [],

+ "lines": [],

+ "spans": []

+ }

+]

+```

+#### [Sample code](#tab/sample-code)

+```Python

+# Analyze pages.

+for page in result.pages:

+ print(f"-Analyzing document from page #{page.page_number}-")

+ print(f"Page has width: {page.width} and height: {page.height}, measured with unit: {page.unit}")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Read_model/sample_analyze_read.py)

+#### [Output](#tab/output)

+```json

+"pages": [

+ {

+ "pageNumber": 1,

+ "angle": 0,

+ "width": 915,

+ "height": 1190,

+ "unit": "pixel",

+ "words": [],

+ "lines": [],

+ "spans": []

+ }

+]

+```

+```json

+"words": [

+ {

+ "content": "While",

+ "polygon": [],

+ "confidence": 0.997,

+ "span": {}

+ },

+],

+"lines": [

+ {

+ "content": "While healthcare is still in the early stages of its Al journey, we",

+ "polygon": [],

+ "spans": [],

+ }

+]

+```

+#### [Sample code](#tab/sample-code)

+```Python

+# Analyze lines.

+for line_idx, line in enumerate(page.lines):

+ words = line.get_words()

+ print(

+ f"...Line # {line_idx} has {len(words)} words and text '{line.content}' within bounding polygon '{format_polygon(line.polygon)}'"

+ )

+ # Analyze words.

+ for word in words:

+ print(

+ f"......Word '{word.content}' has a confidence of {word.confidence}"

+ )

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Read_model/sample_analyze_read.py)

+#### [Output](#tab/output)

+#### [Sample code](#tab/sample-code)

+```Python

+# Analyze lines.

+if page.lines:

+ for line_idx, line in enumerate(page.lines):

+ words = get_words(page, line)

+ print(

+ f"...Line # {line_idx} has {len(words)} words and text '{line.content}' within bounding polygon '{line.polygon}'"

+ )

+ # Analyze words.

+ for word in words:

+ print(f"......Word '{word.content}' has a confidence of {word.confidence}")

+```

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Read_model/sample_analyze_read.py)

+#### [Output](#tab/output)

+```json

+"words": [

+ {

+ "content": "While",

+ "polygon": [],

+ "confidence": 0.997,

+ "span": {}

+ },

+],

+"lines": [

+ {

+ "content": "While healthcare is still in the early stages of its Al journey, we",

+ "polygon": [],

+ "spans": [],

+ }

+]

+```

+Find more samples on GitHub:

+> [!div class="nextstepaction"]

+> [Read model.](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/main/Python(v4.0)/Read_model)

+Find more samples on GitHub:

+> [!div class="nextstepaction"]

+> [Read model.](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/v3.1(2023-07-31-GA)/Python(v3.1)/Read_model)

+|**Receipt model**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)|**prebuilt-receipt**|

+

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Prebuilt_model/sample_analyze_receipts.py)

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Prebuilt_model/sample_analyze_receipts.py)

+* [Find more samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/main/Python(v4.0)/Prebuilt_model)

+* [Find more samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/v3.1(2023-07-31-GA)/Python(v3.1)/Prebuilt_model)

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Retrieval_Augmented_Generation_(RAG)_samples/sample_rag_langchain.ipynb)

+|**US tax form models**|&bullet; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com)</br>&bullet; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)</br>&bullet; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)</br>&bullet; [**JavaScript SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true)|**&bullet; prebuilt-tax.us.W-2</br>&bullet; prebuilt-tax.us.1098</br>&bullet; prebuilt-tax.us.1098E</br>&bullet; prebuilt-tax.us.1098T**|

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/v3.1(2023-07-31-GA)/Python(v3.1)/Prebuilt_model/sample_analyze_tax_us_w2.py)

+> [!div class="nextstepaction"]

+> [View samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/blob/main/Python(v4.0)/Prebuilt_model/sample_analyze_tax_us_w2.py)

+* [Find more samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/main/Python(v4.0)/Prebuilt_model)

+* [Find more samples on GitHub.](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/v3.1(2023-07-31-GA)/Python(v3.1)/Prebuilt_model)

+Support for containers is currently available with Document Intelligence version `2022-08-31 (GA)` for all models and `2023-07-31 (GA)` for Read, Layout, Invoice, Receipt and ID Document models:

+* [REST API `2022-08-31 (GA)`](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)

+* [REST API `2023-07-31 (GA)`](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.1%20(2023-07-31)&tabs=HTTP&preserve-view=true)

+Support for containers is currently available with Document Intelligence version `2022-08-31 (GA)` for all models and `2023-07-31 (GA)` for Read, Layout, Invoice, Receipt and ID Document models:

+* [REST API `2022-08-31 (GA)`](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)

+* [REST API `2023-07-31 (GA)`](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.1%20(2023-07-31)&tabs=HTTP&preserve-view=true)

+Support for containers is currently available with Document Intelligence version `2022-08-31 (GA)` for all models and `2023-07-31 (GA)` for Read, Layout, Invoice, Receipt and ID Document models:

+* [REST API `2022-08-31 (GA)`](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)

+* [REST API `2023-07-31 (GA)`](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.1%20(2023-07-31)&tabs=HTTP&preserve-view=true)

+| [**Invoice 3.1**](https://mcr.microsoft.com/product/azure-cognitive-services/form-recognizer/invoice-3.1/tags) |`mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice-3.1:latest`|

+| [**ID Document 3.1**](https://mcr.microsoft.com/product/azure-cognitive-services/form-recognizer/id-document-3.1/tags) | `mcr.microsoft.com/azure-cognitive-services/form-recognizer/id-document-3.1:latest` |

+| [**Receipt 3.1**](https://mcr.microsoft.com/product/azure-cognitive-services/form-recognizer/receipt-3.1/tags) |`mcr.microsoft.com/azure-cognitive-services/form-recognizer/receipt-3.1:latest`|

+* [REST API `2022-08-31 (GA)`](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)

+* [REST API `2023-07-31 (GA)`](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-v3.1%20(2023-07-31)&tabs=HTTP&preserve-view=true)

+* [Client libraries targeting `REST API 2022-08-31 (GA)`](../sdk-overview-v3-0.md)

+* [Client libraries targeting `REST API 2023-07-31 (GA)`](../sdk-overview-v3-1.md)

+✔️ See [**Install and run Document Intelligence containers**](?view=doc-intel-3.1.0&preserve-view=true) for supported container documentation.

+To get started, you need an active [**Azure account**](https://azure.microsoft.com/free/cognitive-services/). If you don't have one, you can [**create a free account**](https://azure.microsoft.com/free/).

+The following table lists one or more supporting containers for each Document Intelligence container you download. For more information, see the [Billing](#billing) section.

+Feature container | Supporting containers |

+* Ensure that the `EULA` value is set to *accept*.

+The following code sample is a self-contained `docker compose` example to run the Document Intelligence Layout container. With `docker compose`, you use a YAML file to configure your application's services. Then, with the `docker-compose up` command, you create and start all the services from your configuration. Enter {FORM_RECOGNIZER_ENDPOINT_URI} and {FORM_RECOGNIZER_KEY} values for your Layout container instance.

+ image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/read-3.1

+The following code sample is a self-contained `docker compose` example to run the Document Intelligence General Document container. With `docker compose`, you use a YAML file to configure your application's services. Then, with `docker-compose up` command, you create and start all the services from your configuration. Enter {FORM_RECOGNIZER_ENDPOINT_URI} and {FORM_RECOGNIZER_KEY} values for your General Document and Layout container instances.

+The following code sample is a self-contained `docker compose` example to run the Document Intelligence Layout container. With `docker compose`, you use a YAML file to configure your application's services. Then, with `docker-compose up` command, you create and start all the services from your configuration. Enter {FORM_RECOGNIZER_ENDPOINT_URI} and {FORM_RECOGNIZER_KEY} values for your Layout container instance.

+ image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.1

+The following code sample is a self-contained `docker compose` example to run the Document Intelligence Invoice container. With `docker compose`, you use a YAML file to configure your application's services. Then, with `docker-compose up` command, you create and start all the services from your configuration. Enter {FORM_RECOGNIZER_ENDPOINT_URI} and {FORM_RECOGNIZER_KEY} values for your Invoice and Layout container instances.

+You must use 3.1 GA Layout image as an upstream for both 3.0 GA and 3.1 GA Invoice models.

+ image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/invoice-3.1

+ image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/layout-3.1

+The following code sample is a self-contained `docker compose` example to run the Document Intelligence General Document container. With `docker compose`, you use a YAML file to configure your application's services. Then, with `docker-compose up` command, you create and start all the services from your configuration. Enter {FORM_RECOGNIZER_ENDPOINT_URI} and {FORM_RECOGNIZER_KEY} values for your Receipt and Read container instances.

+You can use 3.1 GA Layout image as an upstream instead of Read image.

+ image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/receipt-3.1

+ image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/read-3.1

+The following code sample is a self-contained `docker compose` example to run the Document Intelligence General Document container. With `docker compose`, you use a YAML file to configure your application's services. Then, with `docker-compose up` command, you create and start all the services from your configuration. Enter {FORM_RECOGNIZER_ENDPOINT_URI} and {FORM_RECOGNIZER_KEY} values for your ID and Read container instances.

+You can use 3.1 GA Layout image as an upstream instead of Read image.

+ image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/id-document-3.1

+ image: mcr.microsoft.com/azure-cognitive-services/form-recognizer/read-3.1

+#### Create a folder and store the following files

+#### Create a folder and store your input data

+2. The following code sample is a self-contained `docker compose` example to run Document Intelligence Layout, Studio, and Custom template containers together. With `docker compose`, you use a YAML file to configure your application's services. Then, with `docker-compose up` command, you create and start all the services from your configuration.

+Custom template containers require a few different configurations and support other optional configurations.

+|`EULA` | Yes | License acceptance Example: Eula=accept|

+| StorageTimeToLiveInMinutes | No| `TTL` duration to remove all intermediate and final files. Default: Two days, `TTL` can set between five minutes to seven days |

+You should now have a project created, ready for labeling. Upload your training data and get started labeling. If you're new to labeling, see [build and train a custom model](../how-to-guides/build-a-custom-model.md).

+description: Create a Document Intelligence resource in the Azure portal.

+ > * [Assign an Azure role for access to blob data](../../role-based-access-control/role-assignments-portal.yml?tabs=current) to assign a role that allows for read, write, and delete permissions for your Azure storage container. *See* [Storage Blob Data Contributor](../../role-based-access-control/built-in-roles.md#storage-blob-data-contributor).

+POST https://<your-resource-endpoint>/documentintelligence/documentModels:authorizeCopy?api-version=2024-02-29-preview

+POST https://<your-resource-endpoint>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2024-02-29-preview

+Operation-Location: https://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{operation-id}?api-version=2024-02-29-preview

+GET https://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{<operation-id>}?api-version=2024-02-29-preview

+GET https://<your-resource-endpoint>/documentintelligence/documentModels/{modelId}?api-version=2024-02-29-preview" -H "Ocp-Apim-Subscription-Key: <your-key>

+curl -i -X POST "<your-resource-endpoint>/documentintelligence/documentModels:authorizeCopy?api-version=2024-02-29-preview"

+curl -i -X POST "<your-resource-endpoint>/documentintelligence/documentModels/{modelId}:copyTo?api-version=2024-02-29-preview"

+Operation-Location: https://<your-resource-endpoint>.cognitiveservices.azure.com/documentintelligence/operations/{operation-id}?api-version=2024-02-29-preview

+* [REST API reference documentation](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true)

+When you use the Document Intelligence custom model, you provide your own training data to the [Train Custom Model](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true) operation, so that the model can train to your industry-specific forms. Follow this guide to learn how to collect and prepare data to train the model effectively.

+By default, the [Train Custom Model](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true) API only uses documents that are located at the root of your storage container. However, you can train with data in subfolders if you specify it in the API call. Normally, the body of the [Train Custom Model](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true) call has the following format, where `<SAS URL>` is the Shared access signature URL of your container:

+* Ensure and validate that the configuration works by selecting the Read API and analyzing a sample document. If the resource was configured correctly, the request successfully completes.

+* Ensure that you have the required permissions, the Studio sets the CORS setting required to access the storage account. If you don't have the permissions, you need to make certain that the CORS settings are configured on the Storage account before you can proceed.

+* Ensure and validate that the Studio is configured to access your training data. If you can see your documents in the labeling experience, all the required connections are established.

+* Configure managed identity on the Document Intelligence resource.

+* Disable public access to the Document Intelligence resource and create a private endpoint. Your resource is then only accessible from specific virtual networks and IP addresses.

+* Ensure and validate that you can train models and analyze documents from within the virtual network.

+## Secure the Storage account

+## Configure private endpoints for access from `VNET`s

+1. Remotely connect into the VM from your desktop and launch a browser session that accesses Document Intelligence Studio.

+ 1. [Configure CORS](quickstarts/try-document-intelligence-studio.md#configure-cors).

+ 1. Make sure the client computer can access Document Intelligence resource and storage account, either they are in the same `VNET`, or client IP address is allowed in **Networking > Firewalls and virtual networks** setting page of both Document Intelligence resource and storage account.

+ **Resolution**: Make sure the client computer can access Document Intelligence resource and storage account, either they are in the same `VNET`, or client IP address is allowed in **Networking > Firewalls and virtual networks** setting page of both Document Intelligence resource and storage account.

+ **Resolution**: Check to make sure there's connectivity between the computer accessing the Document Intelligence Studio and the Document Intelligence service. For example, you might need to allow the client IP address in **Networking > Firewalls and virtual networks** setting page of both Document Intelligence resource and storage account.

+description: Understand how to create and use managed identity with Document Intelligence.

+* Managed identities grant access to any resource that supports Microsoft Entra authentication, including your own applications. Unlike security keys and authentication tokens, managed identities eliminate the need for developers to manage credentials.

+* You can grant access to an Azure resource and assign an Azure role to a managed identity using [Azure role-based access control (Azure RBAC)](../../role-based-access-control/overview.md). There's no added cost to use managed identities in Azure.

+ Private Azure storage account access and authentication support [managed identities for Azure resources](../../active-directory/managed-identities-azure-resources/overview.md). If you have an Azure storage account, protected by a Virtual Network (`VNet`) or firewall, Document Intelligence can't directly access your storage account data. However, once a managed identity is enabled, Document Intelligence can access your storage account using an assigned managed identity credential.

+> * The `Analyze` [**Receipt**](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true), [**Business Card**](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true), [**Invoice**](/rest/api/aiservices/operation-groups?view=rest-aiservices-v2.1&preserve-view=true), [**ID document**](/rest/api/aiservices/operation-groups?view=rest-aiservices-v2.1&preserve-view=true), and [**Custom Form**](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true) APIs can extract data from a single document by posting requests as raw binary content. In these scenarios, there is no requirement for a managed identity credential.

+ * On the selected networks page, navigate to the **Exceptions** category and make certain that the [**`Allow Azure services on the trusted services list to access this storage account`**](../../storage/common/storage-network-security.md?tabs=azure-portal#manage-exceptions) checkbox is enabled.

+* A brief understanding of [**Azure role-based access control (Azure RBAC)**](../../role-based-access-control/role-assignments-portal.yml) using the Azure portal.

+You need to grant Document Intelligence access to your storage account before it can read blobs. Now that Document Intelligence access is enabled with a system-assigned managed identity, you can use Azure role-based access control (Azure RBAC), to give Document Intelligence access to Azure storage. The **Storage Blob Data Reader** role gives Document Intelligence (represented by the system-assigned managed identity) read and list access to the blob container and data.

+1. Next, you're going to assign a **Storage Blob Data Reader** role to your Document Intelligence service resource. In the **`Add role assignment`** pop-up window, complete the fields as follows and select **Save**:

+1. After you receive the _Added Role assignment_ confirmation message, refresh the page to see the added role assignment.

+ That's it! You completed the steps to enable a system-assigned managed identity. With managed identity and Azure RBAC, you granted Document Intelligence specific access rights to your storage resource without having to manage credentials such as SAS tokens.

+### Other role assignments for Document Intelligence Studio

+If you're going to use Document Intelligence Studio and your storage account is configured with network restriction such as firewall or virtual network, another role, **Storage Blob Data Contributor**, needs to be assigned to your Document Intelligence service. Document Intelligence Studio requires this role to write blobs to your storage account when you perform Auto label, Human in the loop, or Project sharing/upgrade operations.

+ :::image type="content" source="media/managed-identities/blob-data-contributor-role.png" alt-text="Screenshot of assigning storage blob data contributor role.":::

+Document analysis models enable text extraction from forms and documents and return structured business-ready content ready for your organization's action, use, or development.

+ [**Invoice**](#invoice) | Extract customer and vendor details.

+ [**Receipt**](#receipt) | Extract sales transaction details.

+ [**Identity**](#identity-id) | Extract verification details.

+ :::image type="icon" source="media/overview/icon-mortgage-1003.png" link="#invoice":::</br>

+ [**US mortgage 1003**](#us-mortgage-1003-form) | Extract loan application details.

+ :::image type="icon" source="media/overview/icon-mortgage-1008.png" link="#receipt":::</br>

+ [**US mortgage 1008**](#us-mortgage-1008-form) | Extract loan transmittal details.

+ :::image type="icon" source="media/overview/icon-mortgage-disclosure.png" link="#identity-id":::</br>

+ [**US mortgage disclosure**](#us-mortgage-disclosure-form) | Extract final closing loan terms.

+ [**Health Insurance card**](#health-insurance-card) | Extract insurance coverage details.

+ [**Contract**](#contract-model) | Extract agreement and party details.

+ :::image type="icon" source="media/overview/icon-payment-card.png" link="#contract-model":::</br>

+ [**Credit/Debit card**](#credit-card-model) | Extract payment card information.

+ :::image type="icon" source="media/overview/icon-marriage-certificate.png" link="#contract-model":::</br>

+ [**Marriage certificate**](#marriage-certificate-model) | Extract certified marriage information.

+ [**US Tax W-2 form**](#us-tax-w-2-model) | Extract taxable compensation details.

+ :::image type="icon" source="media/overview/icon-1098-e.png" link="#us-tax-1098-e-form":::</br>

+ :::image type="icon" source="media/overview/icon-1098-t.png" link="#us-tax-1098-t-form":::</br>

+ :::image type="icon" source="media/overview/icon-1099.png" link="#us-tax-1098-t-form":::</br>

+ [**US Tax 1099 form**](#us-tax-1099-and-variations-form) | Extract form 1099 variation details.

+ :::image type="icon" source="media/overview/icon-1040.png" link="#us-tax-1098-t-form":::</br>

+ [**US Tax 1040 form**](#us-tax-1040-form) | Extract form 1040 variation details.

+ :::image type="icon" source="media/overview/icon-1098-e.png" link="#us-tax-1098-e-form":::</br>

+ :::image type="icon" source="media/overview/icon-1098-t.png" link="#us-tax-1098-t-form":::</br>

+Document Intelligence supports optional features that can be enabled and disabled depending on the document extraction scenario. The following add-on capabilities are available for`2024-02-29-preview`, `2023-10-31-preview`, and later releases:

+|[**prebuilt-invoice**](concept-invoice.md) |&#9679; Extract key information from invoices.</br>&#9679; [Data and field extraction](concept-invoice.md#field-extraction) |&#9679; Accounts payable processing.</br>&#9679; Automated tax recording and reporting. |&#9679; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=invoice&formType=invoice)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+|[**prebuilt-receipt**](concept-receipt.md) |&#9679; Extract key information from receipts.</br>&#9679; [Data and field extraction](concept-receipt.md#field-extraction)</br>&#9679; Receipt model v3.0 supports processing of **single-page hotel receipts**.|&#9679; Expense management.</br>&#9679; Consumer behavior data analysis.</br>&#9679; Customer loyalty program.</br>&#9679; Merchandise return processing.</br>&#9679; Automated tax recording and reporting. |&#9679; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=receipt&formType=receipt)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+| Model ID | Description |Automation use cases | Development options |

+|-|--|-|--|

+|[**prebuilt-idDocument**](concept-id-document.md) |&#9679; Extract key information from passports and ID cards.</br>&#9679; [Document types](concept-id-document.md#supported-document-types)</br>&#9679; Extract endorsements, restrictions, and vehicle classifications from US driver's licenses. |&#9679; Know your customer (KYC) financial services guidelines compliance.</br>&#9679; Medical account management.</br>&#9679; Identity checkpoints and gateways.</br>&#9679; Hotel registration. |&#9679; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=idDocument&formType=idDocument)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+> [!div class="nextstepaction"]

+> [Return to model types](#prebuilt-models)

+### US mortgage 1003 form

+| Model ID | Description |Automation use cases | Development options |

+|-|--|-|--|

+|[**prebuilt-mortgage.us.1003**](concept-mortgage-documents.md)|&#9679; Extract key information from `1003` loan applications. </br>&#9679; [Data and field extraction](concept-mortgage-documents.md#field-extraction-1003-uniform-residential-loan-application-urla)|&#9679; Fannie Mae and Freddie Mac documentation requirements.| &#9679; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=mortgage.us.1003&formType=mortgage.us.1003)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+> [!div class="nextstepaction"]

+> [Return to model types](#prebuilt-models)

+### US mortgage 1008 form

+|[**prebuilt-mortgage.us.1008**](concept-mortgage-documents.md)|&#9679; Extract key information from Uniform Underwriting and Transmittal Summary. </br>&#9679; [Data and field extraction](concept-mortgage-documents.md#field-extraction-1008-uniform-underwriting-and-transmittal-summary)|&#9679; Loan underwriting processing using summary data.| &#9679; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=mortgage.us.1008&formType=mortgage.us.1008)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+> [!div class="nextstepaction"]

+> [Return to model types](#prebuilt-models)

+### US mortgage disclosure form

+| Model ID | Description |Automation use cases | Development options |

+|-|--|-|--|

+|[**prebuilt-mortgage.us.closingDisclosure**](concept-mortgage-documents.md)|&#9679; Extract key information from Uniform Underwriting and Transmittal Summary. </br>&#9679; [Data and field extraction](concept-mortgage-documents.md#field-extraction-mortgage-closing-disclosure)|&#9679; Mortgage loan final details requirements.| &#9679; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=mortgage.us.closingDisclosure&formType=mortgage.us.closingDisclosure)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+| [**prebuilt-healthInsuranceCard.us**](concept-health-insurance-card.md)|&#9679; Extract key information from US health insurance cards.</br>&#9679; [Data and field extraction](concept-health-insurance-card.md#field-extraction)|&#9679; Coverage and eligibility verification. </br>&#9679; Predictive modeling.</br>&#9679; Value-based analytics.|&#9679; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=healthInsuranceCard.us&formType=healthInsuranceCard.us)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+|[**prebuilt-contract**](concept-contract.md)|Extract contract agreement and party details.</br>&#9679; [Data and field extraction](concept-contract.md#field-extraction)|&#9679; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=contract&formType=contract)</br>&#9679; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+> [!div class="nextstepaction"]

+> [Return to model types](#prebuilt-models)

+### Credit card model

+| Model ID | Description| Development options |

+|-|--|-|

+|[**prebuilt-creditCard**](concept-credit-card.md)|Extract contract agreement and party details. </br>&#9679; [Data and field extraction](concept-credit-card.md#field-extraction)|&#9679; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=contract&formType=contract)</br>&#9679; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+### Marriage certificate model

+| Model ID | Description| Development options |

+|-|--|-|

+|[**prebuilt-marriageCertificate.us**](concept-marriage-certificate.md)|Extract contract agreement and party details. </br>&#9679; [Data and field extraction](concept-marriage-certificate.md#field-extraction)|&#9679; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=marriageCertificate.us&formType=marriageCertificate.us)</br>&#9679; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+|[**prebuilt-tax.us.W-2**](concept-tax-document.md) |&#9679; Extract key information from IRS US W2 tax forms (year 2018-2021).</br>&#9679; [Data and field extraction](concept-tax-document.md#field-extraction-w-2)|&#9679; Automated tax document management.</br>&#9679; Mortgage loan application processing. |&#9679; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=tax.us.w2&formType=tax.us.w2)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model) |

+|[**prebuilt-tax.us.1098**](concept-tax-document.md)|Extract mortgage interest information and details. </br>&#9679; [Data and field extraction](concept-tax-document.md#field-extraction-1098)|&#9679; [**Document Intelligence Studio**](https://formrecognizer.appliedai.azure.com/studio/prebuilt?formType=tax.us.1098)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+|[**prebuilt-tax.us.1098E**](concept-tax-document.md)|Extract student loan information and details. </br>&#9679; [Data and field extraction](concept-tax-document.md#field-extraction-1098)|&#9679; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=tax.us.1098&formType=tax.us.1098E)</br>&#9679; </br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+|[**prebuilt-tax.us.1098T**](concept-tax-document.md)|Extract tuition information and details. </br>&#9679; [Data and field extraction](concept-tax-document.md#field-extraction-1098)|&#9679; [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=tax.us.1098&formType=tax.us.1098T)</br>&#9679; [**REST API**](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)|

+### US tax 1099 (and variations) form

+|[**prebuilt-tax.us.1099{`variation`}**](concept-tax-document.md)|Extract information from 1099-form variations.|&#9679; </br>&#9679; [Data and field extraction](concept-tax-document.md#field-extraction-1099-nec) [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=tax.us.1099)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+### US tax 1040 form

+| Model ID |Description|Development options |

+|-|--|--|

+|**prebuilt-tax.us.1040**|Extract information from 1040-form variations.|&#9679; </br>&#9679; [Data and field extraction](concept-tax-document.md#field-extraction-1040-tax-form) [**Document Intelligence Studio**](https://documentintelligence.ai.azure.com/studio/prebuilt?formCategory=tax.us.1040)</br>&#9679; [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true&pivots=programming-language-rest-api#analyze-document-post-request)</br>&#9679; [**C# SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Python SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**Java SDK**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)</br>&#9679; [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-4.0.0&preserve-view=true#prebuilt-model)|

+* [**Find more samples on GitHub**](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/main).

+* [**Find more samples on GitHub**](https://github.com/Azure-Samples/document-intelligence-code-samples/tree/v3.1(2023-07-31-GA)).

+* An active [**Azure account**](https://azure.microsoft.com/free/cognitive-services/). If you don't have one, you can [**create a free account**](https://azure.microsoft.com/free/).

+> Create an Azure AI services resource if you plan to access multiple Azure AI services under a single endpoint/key. For Document Intelligence access only, create a Document Intelligence resource. Please note that you'll need a single-service resource if you intend to use [Microsoft Entra authentication](../../../active-directory/authentication/overview-authentication.md).

+>

+> Document Intelligence now supports AAD token authentication additional to local (key-based) authentication when accessing the Document Intelligence resources and storage accounts. Be sure to follow below instructions to setup correct access roles, especially if your resources are applied with `DisableLocalAuth` policy.

+For more information on authorization, *see* [Document Intelligence Studio authorization policies](../studio-overview.md#authorization-policies).

+> [!NOTE]

+> If local (key-based) authentication is disabled for your Document Intelligence service resource, be sure to obtain **Cognitive Services User** role and your AAD token will be used to authenticate requests on Document Intelligence Studio. The **Contributor** role only allows you to list keys but does not give you permission to use the resource when key-access is disabled.

+Prebuilt models help you add Document Intelligence features to your apps without having to build, train, and publish your own models. You can choose from several prebuilt models, each of which has its own set of supported data fields. The choice of model to use for the `analyze` operation depends on the type of document to be analyzed. Document Intelligence currently supports the following prebuilt models:

+* [**Health insurance card**](https://formrecognizer.appliedai.azure.com/studio): extract insurer, member, prescription, group number, and other key information from US health insurance cards.

+After you completed the prerequisites, navigate to [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio/).

+1. Select a Document Intelligence service feature from the Studio home page. This step is a one-time process unless you already selected the service resource from prior use. Select your Azure subscription, resource group, and resource. (You can change the resources anytime in "Settings" in the top menu.) Review and confirm your selections.

+1. Select the output section's Result tab and browse the JSON output to understand the service response format.

+1. Select the Code tab and browse the sample code for integration. Copy and download to get started.

+ * **Storage Account Contributor**: You need this role for the Storage Account to set up CORS settings (this action is a one-time effort if the same storage account is reused).

+1. Select your files to upload.

+1. Use the auto label feature to label using already trained model or one of our prebuilt models.

+* Explore our [**v3.0 SDK quickstarts**](get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true) to try the v3.0 features in your applications using the new client libraries.

+| [.NET/C# → 3.1.x (GA)](/dotnet/api/azure.ai.formrecognizer?view=azure-dotnet&preserve-view=true)|[NuGet](https://www.nuget.org/packages/Azure.AI.FormRecognizer)|[v2.1](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true)|[Windows, macOS, Linux, Docker](https://dotnet.microsoft.com/download)|

+|[Java → 3.1.x (GA)](https://azuresdkdocs.blob.core.windows.net/$web/java/azure-ai-formrecognizer/3.1.1/https://docsupdatetracker.net/index.html) |[Maven repository](https://mvnrepository.com/artifact/com.azure/azure-ai-formrecognizer/3.1.1) |[v2.1](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true)|[Windows, macOS, Linux](/java/openjdk/install)|

+|[JavaScript → 3.1.0 (GA)](https://azuresdkdocs.blob.core.windows.net/$web/javascript/azure-ai-form-recognizer/3.1.0/https://docsupdatetracker.net/index.html)| [npm](https://www.npmjs.com/package/@azure/ai-form-recognizer/v/3.1.0)|[v2.1](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true)| [Browser, Windows, macOS, Linux](https://nodejs.org/en/download/) |

+|[Python → 3.1.0 (GA)](https://azuresdkdocs.blob.core.windows.net/$web/python/azure-ai-formrecognizer/3.1.0/https://docsupdatetracker.net/index.html) | [PyPI](https://pypi.org/project/azure-ai-formrecognizer/3.1.0/)|[v2.1](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true)

+|[Windows, macOS, Linux](/azure/developer/python/configure-local-development-environment?tabs=windows%2Capt%2Ccmd#use-the-azure-cli)|

+For more information on other SDK versions, see:

+* [`2024-02-29` (preview)](sdk-overview-v4-0.md)

+* [`2023-07-31` v3.1 (GA)](sdk-overview-v3-1.md)

+* [`2022-08-31` v3.0 (GA)](sdk-overview-v3-0.md)

+There are two supported methods for authentication.

+For more information, *see* [Authenticate the client](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.FormRecognizer_4.0.0-beta.4/sdk/formrecognizer/Azure.AI.FormRecognizer#authenticate-the-client).

+For more information, *see* [Authenticate the client](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/formrecognizer/azure-ai-formrecognizer#authenticate-the-client).

+For more information, *see* [Authenticate the client](https://github.com/Azure/azure-sdk-for-python/tree/azure-ai-formrecognizer_3.2.0b5/sdk/formrecognizer/azure-ai-formrecognizer#authenticate-the-client).

+The [Microsoft Q & A](/answers/topics/azure-form-recognizer.html) and [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-form-recognizer) forums are available for the developer community to ask and answer questions about Azure AI Document Intelligence and other services. Microsoft monitors the forums and replies to questions that the community has yet to answer. To make sure that we see your question, tag it with **`azure-form-recognizer`**.

+> [**Explore Document Intelligence REST API v2.1**](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true)

+| [.NET/C# → 4.0.0 (GA)](https://azuresdkdocs.blob.core.windows.net/$web/dotnet/Azure.AI.FormRecognizer/4.0.0/https://docsupdatetracker.net/index.html)|[NuGet](https://www.nuget.org/packages/Azure.AI.FormRecognizer)|[v3.0](/rest/api/aiservices/operation-groups?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)|[Windows, macOS, Linux, Docker](https://dotnet.microsoft.com/download)|

+|[Java → 4.0.6 (GA)](https://azuresdkdocs.blob.core.windows.net/$web/java/azure-ai-formrecognizer/4.0.0/https://docsupdatetracker.net/index.html) |[Maven repository](https://mvnrepository.com/artifact/com.azure/azure-ai-formrecognizer/4.0.6) |[v3.0](/rest/api/aiservices/operation-groups?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)|[Windows, macOS, Linux](/java/openjdk/install)|

+|[JavaScript → 4.0.0 (GA)](https://azuresdkdocs.blob.core.windows.net/$web/javascript/azure-ai-form-recognizer/4.0.0/https://docsupdatetracker.net/index.html)| [npm](https://www.npmjs.com/package/@azure/ai-form-recognizer)| [v3.0](/rest/api/aiservices/operation-groups?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)| [Browser, Windows, macOS, Linux](https://nodejs.org/en/download/) |

+|[Python → 3.2.0 (GA)](https://azuresdkdocs.blob.core.windows.net/$web/python/azure-ai-formrecognizer/3.2.0/https://docsupdatetracker.net/index.html) | [PyPI](https://pypi.org/project/azure-ai-formrecognizer/3.2.0/)| [v3.0](/rest/api/aiservices/operation-groups?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)|[Windows, macOS, Linux](/azure/developer/python/configure-local-development-environment?tabs=windows%2Capt%2Ccmd#use-the-azure-cli)|

+For more information on other SDK versions, see:

+* [`2024-02-29` v4.0 (preview)](sdk-overview-v4-0.md)

+* [`2023-07-31` v3.1 (GA)](sdk-overview-v3-1.md)

+* [`v2.1` (GA)](sdk-overview-v2-1.md)

+There are two supported methods for authentication:

+For more information, *see* [Authenticate the client](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.FormRecognizer_4.0.0-beta.4/sdk/formrecognizer/Azure.AI.FormRecognizer#authenticate-the-client).

+For more information, *see* [Authenticate the client](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/formrecognizer/azure-ai-formrecognizer#authenticate-the-client).

+For more information, *see* [Authenticate the client](https://github.com/Azure/azure-sdk-for-python/tree/azure-ai-formrecognizer_3.2.0b5/sdk/formrecognizer/azure-ai-formrecognizer#authenticate-the-client).

+The [Microsoft Q & A](/answers/topics/azure-form-recognizer.html) and [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-form-recognizer) forums are available for the developer community to ask and answer questions about Azure AI Document Intelligence and other services. Microsoft monitors the forums and replies to questions that the community has yet to answer. To make sure that we see your question, tag it with **`azure-form-recognizer`**.

+> [**Explore Document Intelligence REST API v3.0**](/rest/api/aiservices/operation-groups?view=rest-aiservices-v3.0%20(2022-08-31)&preserve-view=true&tabs=HTTP)

+description: The Document Intelligence 2023-07-31 (GA) software development kits (SDKs) expose Document Intelligence models, features, and capabilities that are in active development for C#, Java, JavaScript, or Python programming language.

+# SDK target: REST API 2023-07-31 (GA)

+| [**.NET/C# → latest (GA)**](/dotnet/api/overview/azure/ai.formrecognizer-readme?view=azure-dotnet&preserve-view=true)|[NuGet](https://www.nuget.org/packages/Azure.AI.FormRecognizer/4.1.0)|[2023-07-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)|

+|[**Java → latest (GA)**](https://azuresdkdocs.blob.core.windows.net/$web/java/azure-ai-formrecognizer/4.1.0/https://docsupdatetracker.net/index.html) |[Maven repository](https://mvnrepository.com/artifact/com.azure/azure-ai-formrecognizer/4.1.0) |[2023-07-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)|[Windows, macOS, Linux](/java/openjdk/install)|

+|[**JavaScript → latest (GA)**](https://azuresdkdocs.blob.core.windows.net/$web/javascript/azure-ai-form-recognizer/5.0.0/https://docsupdatetracker.net/index.html)| [npm](https://www.npmjs.com/package/@azure/ai-form-recognizer)| [2023-07-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)| [Browser, Windows, macOS, Linux](https://nodejs.org/en/download/) |

+|[**Python → latest (GA)**](https://azuresdkdocs.blob.core.windows.net/$web/python/azure-ai-formrecognizer/3.3.0/https://docsupdatetracker.net/index.html) | [PyPI](https://pypi.org/project/azure-ai-formrecognizer/3.3.0/)| [2023-07-31 (GA)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2023-07-31&preserve-view=true&tabs=HTTP)|[Windows, macOS, Linux](/azure/developer/python/configure-local-development-environment?tabs=windows%2Capt%2Ccmd#use-the-azure-cli)|

+For more information on other SDK versions, see:

+* [`2024-02-29` v4.0 (preview)](sdk-overview-v4-0.md)

+* [`2022-08-31` v3.0 (GA)](sdk-overview-v3-0.md)

+* [`v2.1` (GA)](sdk-overview-v2-1.md)

+There are two supported methods for authentication:

+For more information, *see* [Authenticate the client](https://github.com/Azure/azure-sdk-for-net/tree/Azure.AI.FormRecognizer_4.0.0-beta.4/sdk/formrecognizer/Azure.AI.FormRecognizer#authenticate-the-client).

+For more information, *see* [Authenticate the client](https://github.com/Azure/azure-sdk-for-java/tree/main/sdk/formrecognizer/azure-ai-formrecognizer#authenticate-the-client).

+For more information, *see* [Authenticate the client](https://github.com/Azure/azure-sdk-for-python/tree/azure-ai-formrecognizer_3.2.0b5/sdk/formrecognizer/azure-ai-formrecognizer#authenticate-the-client).

+The [Microsoft Q & A](/answers/topics/azure-form-recognizer.html) and [Stack Overflow](https://stackoverflow.com/questions/tagged/azure-form-recognizer) forums are available for the developer community to ask and answer questions about Azure AI Document Intelligence and other services. Microsoft monitors the forums and replies to questions that the community has yet to answer. To make sure that we see your question, tag it with **`azure-form-recognizer`**.

+| [**.NET/C# → 1.0.0-beta.2 (preview)**](/dotnet/api/overview/azure/ai.documentintelligence-readme?view=azure-dotnet-preview&preserve-view=true)|[NuGet](https://www.nuget.org/packages/Azure.AI.DocumentIntelligence/1.0.0-beta.2)|[2024-02-29 (preview)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2024-02-29-preview&preserve-view=true&tabs=HTTP)|[Windows, macOS, Linux, Docker](https://dotnet.microsoft.com/download)|

+ |[**Java → 1.0.0-beta.2 (preview)**](/java/api/overview/azure/ai-documentintelligence-readme?view=azure-java-preview&preserve-view=true) |[Maven repository](https://mvnrepository.com/artifact/com.azure/azure-ai-documentintelligence/1.0.0-beta.2) |[2024-02-29 (preview)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2024-02-29-preview&preserve-view=true&tabs=HTTP)|[Windows, macOS, Linux](/java/openjdk/install)|

+|[**JavaScript → 1.0.0-beta.2 (preview)**](/javascript/api/overview/azure/ai-document-intelligence-rest-readme?view=azure-node-preview&preserve-view=true)| [npm](https://www.npmjs.com/package/@azure-rest/ai-document-intelligence)|[2024-02-29 (preview)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2024-02-29-preview&preserve-view=true&tabs=HTTP)| [Browser, Windows, macOS, Linux](https://nodejs.org/en/download/) |

+|[**Python → 1.0.0b2 (preview)**](/python/api/overview/azure/ai-documentintelligence-readme?view=azure-python-preview&preserve-view=true) | [PyPI](https://pypi.org/project/azure-ai-documentintelligence/)|[2024-02-29 (preview)](/rest/api/aiservices/document-models/analyze-document?view=rest-aiservices-2024-02-29-preview&preserve-view=true&tabs=HTTP)|[Windows, macOS, Linux](/azure/developer/python/configure-local-development-environment?tabs=windows%2Capt%2Ccmd#use-the-azure-cli)|

+For more information on other SDK versions, see:

+* [`2023-07-31` v3.1 (GA)](sdk-overview-v3-1.md)

+* [`2022-08-31` v3.0 (GA)](sdk-overview-v3-0.md)

+* [`v2.1` (GA)](sdk-overview-v2-1.md)

+|Document types supported|Read|Layout|Prebuilt models|Custom models|Add-on capabilities|

+|--|--|--|--|--|-|

+| PDF | ✔️ | ✔️ | ✔️ | ✔️ |✔️|

+| Images: `JPEG/JPG`, `PNG`, `BMP`, `TIFF`, `HEIF` | ✔️ | ✔️ | ✔️ | ✔️ |✔️|

+| Microsoft Office: `DOCX`, `PPTX`, `XLS` | ✔️ | ✔️ | ✖️ | ✖️ |✖️|

+✔️ = supported

+✖️ = Not supported

+| Images: `JPEG/JPG`, `PNG`, `BMP`, `TIFF`, `HEIF` | ✔️ | ✔️ | ✔️ | ✔️ |

+| Microsoft Office: `DOCX`, `PPTX`, `XLS` | ✔️ | ✖️ | ✖️ | ✖️ |

+✔️ = supported

+✖️ = Not supported

+Before requesting a quota increase (where applicable), ensure that it's necessary. Document Intelligence service uses autoscaling to bring the required computational resources `on-demand`, keep the customer costs low, and deprovision unused resources by not maintaining an excessive amount of hardware capacity.

+* Get sample code for the language specific `SDKs` to integrate into your applications.

+## Get started

+## Authorization policies

+Your organization can opt to disable local authentication and enforce Microsoft Entra (formerly Azure Active Directory) authentication for Azure AI Document Intelligence resources and Azure blob storage.

+* Using Microsoft Entra authentication requires that key based authorization is disabled. After key access is disabled, Microsoft Entra ID is the only available authorization method.

+* Microsoft Entra allows granting minimum privileges and granular control for Azure resources.

+* For more information *see* the following guidance:

+ * [Disable local authentication for Azure AI Services](../disable-local-auth.md).

+ * [Prevent Shared Key authorization for an Azure Storage account](../../storage/common/shared-key-authorization-prevent.md)

+* **Designating role assignments**. Document Intelligence Studio basic access requires the [`Cognitive Services User`](../../role-based-access-control/built-in-roles/ai-machine-learning.md#cognitive-services-user) role. For more information, *see* [Document Intelligence role assignments](quickstarts/try-document-intelligence-studio.md#azure-role-assignments) and [Document Intelligence Studio Permission](faq.yml#what-permissions-do-i-need-to-access-document-intelligence-studio-).

+## Authentication

+Navigate to the [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/). If it's your first time logging in, a popup window appears prompting you to configure your service resource. In accordance with your organization's policy, you have one or two options:

+* **Microsoft Entra authentication: access by Resource (recommended)**.

+ * Choose your existing subscription.

+ * Select an existing resource group within your subscription or create a new one.

+ * Select your existing Document Intelligence or Azure AI services resource.

+ :::image type="content" source="media/studio/configure-service-resource.png" alt-text="Screenshot of configure service resource form from the Document Intelligence Studio.":::

+* **Local authentication: access by API endpoint and key**.

+ * Retrieve your endpoint and key from the Azure portal.

+ * Go to the overview page for your resource and select **Keys and Endpoint** from the left navigation bar.

+ * Enter the values in the appropriate fields.

+ :::image type="content" source="media/studio/keys-and-endpoint.png" alt-text="Screenshot of the keys and endpoint page in the Azure portal.":::

+## Try a Document Intelligence model

+1. Once your resource is configured, you can try the different models offered by Document Intelligence Studio. From the front page, select any Document Intelligence model to try using with a no-code approach.

+1. To test any of the document analysis or prebuilt models, select the model and use one of the sample documents or upload your own document to analyze. The analysis result is displayed at the right in the content-result-code window.

+1. Custom models need to be trained on your documents. See [custom models overview](concept-custom.md) for an overview of custom models.

+1. After validating the scenario in the Document Intelligence Studio, use the [**C#**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true), [**Java**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true), [**JavaScript**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true), or [**Python**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true) client libraries or the [**REST API**](quickstarts/get-started-sdks-rest-api.md?view=doc-intel-3.0.0&preserve-view=true) to get started incorporating Document Intelligence models into your own applications.

+To learn more about each model, *see* our concept pages.

+### View resource details

+* To begin using the models presented by the service, visit [Document Intelligence Studio](https://formrecognizer.appliedai.azure.com/studio).

+1. The following code block calls the Document Intelligence [Analyze Layout](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true) API on the uploaded document. Fill in your endpoint and key values.

+Azure Logic Apps is a cloud-based platform that can be used to automate workflows without writing a single line of code. The platform enables you to easily integrate Microsoft and your applications with your apps, data, services, and systems. A Logic App is the Azure resource you create when you want to develop a workflow. Here are a few examples of what you can do with a Logic App:

+Let's quickly review what we completed before we test our flow:

+Now that we created the flow, the last thing to do is to test it and make sure that we're getting the expected behavior.

+Congratulations! You completed this tutorial.

+List models are extended to now return prebuilt and custom models. All prebuilt model names start with ```prebuilt-```. Only models with a status of succeeded are returned. To list models that either failed or are in progress, see [List Operations](/rest/api/aiservices/miscellaneous/list-operations?view=rest-aiservices-v3.0%20(2022-08-31)&tabs=HTTP&preserve-view=true).

+## May 2024

+The Document Intelligence Studio has added support for Microsoft Entra (formerly Azure Active Directory) authentication. For more information, *see* [Document Intelligence Studio overview](studio-overview.md#authentication).

+The Document Intelligence [**2024-02-29-preview**](/rest/api/aiservices/document-models?view=rest-aiservices-v4.0%20(2024-02-29-preview)&preserve-view=true) REST API is now available. This preview API introduces new and updated capabilities:

+The Document Intelligence [**2023-10-31-preview**](/rest/api/aiservices/document-models?view=rest-aiservices-v4.0%20(2024-02-29-preview)&preserve-view=true) REST API is now available. This preview API introduces new and updated capabilities:

+* Document Intelligence REST API Version **2023-02-28-preview** supports the public preview release client libraries. This release includes the following new features and capabilities available for .NET/C# (4.1.0-beta-1), Java (4.1.0-beta-1), JavaScript (4.1.0-beta-1), and Python (3.3.0b.1) client libraries:

+> **`2023-02-28-preview`** capabilities are currently only available in the following regions:

+* [**Custom classification model**](concept-custom-classifier.md) is a new capability within Document Intelligence starting with the ```2023-02-28-preview``` API.

+* Get started with the new v3.0 preview API.

+ * **REST API reference is available** - View the [`v2.1-preview.1 reference`](/rest/api/aiservices/analyzer?view=rest-aiservices-v2.1&preserve-view=true).

+## Data privacy for Immersive reader

+Immersive reader doesn't store any customer data.

+As you use this API in your application, see the [reference documentation](/rest/api/language) for additional information.

+Within a few minutes, the target will be assigned the selected role at the selected scope. For help with these steps, see [Assign Azure roles using the Azure portal](../../../role-based-access-control/role-assignments-portal.yml).

+ *[Language Runtime CLU APIs](/rest/api/language)

+When you send asynchronous requests, you'll incur charges based on number of text records you include in your request, for each feature use. For example, if you send a text record for sentiment analysis and NER, it will be counted as sending two text records, and you'll be charged for both according to your [pricing tier](https://azure.microsoft.com/pricing/details/cognitive-services/language-service/).

+To submit an asynchronous job, review the [reference documentation](/rest/api/language/analyze-text-submit-job) for the JSON body you'll send in your request.

+A successful call will return a 202 response code. The `operation-location` in the response header will be the URL you'll use to retrieve the API results. The value will look similar to the following URL:

+To [get the status and retrieve the results](/rest/api/language/analyze-text-job-status) of the request, send a GET request to the URL you received in the `operation-location` header from the previous API response. Remember to include your key in the `Ocp-Apim-Subscription-Key`. The response will include the results of your API call.