---
title: "Required field definitions"
method: POST
path: "/assistedSales/v1/opportunities/items/requiredFields/definitions"
tags: ["AppResellerOpportunities"]
---

# Required field definitions

`POST /assistedSales/v1/opportunities/items/requiredFields/definitions`

## Request

- Base URL: `https://marketplace.appdirect.com/api`
- URL: `https://marketplace.appdirect.com/api/assistedSales/v1/opportunities/items/requiredFields/definitions`
- Auth: none declared. Required headers: `Accept-Language`
- TypeScript: <https://skmtc.dev/appdirect/apis/companies/docs/assistedSales/v1/opportunities/items/requiredFields/definitions/post.ts> (a function with typed inputs; its response is checked against the schema)

For a customer/sales agent combination, returns the vendor-required fields for one or more products, and a description of the fields. Request can be made before or after an opportunity is created. It returns the fields that will be required, and any values previously saved on the AppDirect platform that can be prepopulated when an opportunity is created. It does not return required field values edited, added, or saved with an opportunity.

Some vendors (for example, Microsoft) have business rules that exclude required fields from the response when the vendor already has the information stored on their platform for the customer/sales agent/product combination.

Required: Accept-Language header with Locale format. For example: en-US

## Query parameters

- `userId` string, required
- `companyId` string, required
- `salesAgentUserId` string, required
- `salesAgentCompanyId` string, required

## Headers

- `Accept-Language` string, required

## Request body

- ProductIds[]
  - `productId` string, required: The product ID
  - `editionId` string, required: The edition code

## Response `200`

Required field definitions retrieved successfully

- RequiredFields[]
  - `productId` string: The product ID
  - `editionId` string: The edition code
  - `forms` Form[]: Groups of required fields. Forms are used to organize required fields into meaningful groups.
    - `isvIdentifier` string: The vendor's (ISV's) unique identifier
    - `context` string: Response organization. ITEM_LEVEL: Required fields listed for each product. CART_LEVEL: Products grouped by vendor (ISV) with one list of required fields that apply to all the vendor's products.
    - `title` string: The form title
    - `subTitle` string: Descriptive subtitle for the form
    - `fields` Field[]: All relevant information related to fields in the form
      - `inputCode` string: An identifier for the field. For example: domain, username, country, state. Can be used to reference this field and the value in it (for example, see Suffix option).
      - `inputTitle` string: Descriptive title for the field
      - `subTitle` string: Descriptive subtitle for the field
      - `tooltip` string: Descriptive tooltip for the field
      - `value` string: The field value
      - `fieldType` string: The type of input field associated with the form field. For example: DOMAIN (has 'http'), STRING, EMAIL (has '@').
      - `validations` RequiredFieldValidationDefinitions: Required field definitions. Used to validate field values.
        - `required` boolean: Indicates whether field is mandatory
        - `readonly` boolean: Indicates whether field is writable
        - `minLength` string: Minimum number of characters for the field
        - `maxLength` string: Maximum number of characters for the field
        - `expression` string: Describes the regular expression used to validate the field value
      - `options` Options: Field options
        - `suffix` Suffix: The suffix label that appears to the right of the form field. For example, for a domain field, the suffix might be .com. Optional. The suffix can be populated by text OR the value in another form field referenced by an input code.
          - `text` string: The suffix value
          - `inputCode` string: Unique identifier for the field. Possible values are DOMAIN, USERNAME, COUNTRY, STATE, etc.
        - `placeholder` string: Tip that appears in an unpopulated text field. For example: Enter your domain here. Optional.

## Other responses

- `400`: Missing or invalid required parameter
- `401`: Unauthorized
- `404`: Product ID not found

## Changes

- **2026-11-06** `1fc240f06971`: 7 breaking, 15 info
  - added the new required request property `items/editionId`
  - added the new required request property `items/productId`
  - the `items/` request property type changed from no type to `object`
  - the response's body type changed from no type to `object` for status `400`
  - …18 more

[Operation history](https://skmtc.dev/appdirect/apis/companies/changes/assistedSales/v1/opportunities/items/requiredFields/definitions/post.md)

---

[API](https://skmtc.dev/appdirect/apis/companies.md) - [All operations](https://skmtc.dev/appdirect/apis/companies/llms.txt) - [OpenAPI document](https://skmtc.dev/appdirect/apis/companies/revisions/1fc240f06971?raw)