---
title: Detailed Responses
description: PingOne flows use the PingOne authorize endpoint to start the flow. The authorize request must include the response_mode property set to pi.flow, which tells the authorization server to return a 200 OK response with a payload that can be either verbose (HTML and scripts to render the sign-on forms) or minimal (concise JSON responses that show the data properties and their values). Configuring your responses to return HTML provides the frontend HTML you need to create the sign-on interface. It is the most direct way to render the interactive UI forms to collect user input.
component: pingone-api
page_id: pingone-api:auth:pingone-davinci/davinci-runtime-apis/pingflows-html
canonical_url: https://developer.pingidentity.com/pingone-api/auth/pingone-davinci/davinci-runtime-apis/pingflows-html.html
section_ids:
  davinci-and-pingone-configuration-requirements: DaVinci and PingOne configuration requirements
  flow-execution: Flow execution
  step-1-initiate-the-flow-through-a-pingone-authorize-request: "Step 1: Initiate the flow through a PingOne authorize request"
  step-2-execute-the-next-flow-action: "Step 2: Execute the next flow action"
  step-3-complete-the-flow: "Step 3: Complete the flow"
  davinci-connections-capabilities-html-data-model: DaVinci flow capabilities data model properties
---

# Detailed Responses

PingOne flows use the PingOne authorize endpoint to start the flow. The authorize request must include the `response_mode` property set to `pi.flow`, which tells the authorization server to return a `200 OK` response with a payload that can be either verbose (HTML and scripts to render the sign-on forms) or minimal (concise JSON responses that show the data properties and their values). Configuring your responses to return HTML provides the frontend HTML you need to create the sign-on interface. It is the most direct way to render the interactive UI forms to collect user input.

To return HTML, the authorize request sets the `response_mode` property to `pi.flow`, but it omits the `X-Requested-With` HTTP header.

For example, the PingOne authorize request configured without the `X-Requested-With` HTTP header returns the following response:

```none
{
  "id" : "howu8n9hsc",
  "companyId" : "499a5cea55...",
  "flowId" : "56cb88...",
  "connectionId" : "867ed43...",
  "capabilityName" : "customHTMLTemplate",
  "screen" : {
    "name" : "HTTP",
    "properties" : {
      "sktemplate" : {
        "type" : "string",
        "displayName" : "Template",
        "createdDate" : 1694542156374,
        "customerId" : "ecb9bf...",
        "companyId" : "singularkey"
      },
      "customHTML" : {
        "type" : "string",
        "displayName" : "HTML Template",
        "viewToggle" : true,
        "largePayload" : true,
        "value" : "<div class=\"app-container\" ..."
      },
      "validationRules" : {
        "type" : "object",
        "displayName" : "Form validation rules",
        "info" : "Rules to check to validate form inputs",
        "preferredControlType" : "validationRules"
      },
      "customCSS" : {
        "type" : "string",
        "displayName" : "CSS",
        "language" : "css",
        "maximizeToggle" : true,
        "largePayload" : true
      },
      "customScript" : {
        "type" : "string",
        "displayName" : "Script",
        "language" : "javascript",
        "maximizeToggle" : true,
        "info" : "Write custom JavaScript"."
      },
      "inputSchema" : {
        ...
      },
      "outputSchema" : {
        ...
      },
      "formFieldsList" : {
        "type" : "array",
        "constructType" : "formFieldsList",
        "displayName" : "Output Fields List",
        "preferredControlType" : "formFieldsList",
        "hideLabel" : false,
        "value" : [ {
          "preferredControlType" : "textField",
          "preferredDataType" : "string",
          "propertyName" : "username",
          "displayName" : "Username",
          "hashedVisibility" : false
        }, {
          "preferredControlType" : "textField",
          "preferredDataType" : "string",
          "propertyName" : "password",
          "displayName" : "Password",
          "hashedVisibility" : true
        }, {
          "preferredControlType" : "textField",
          "preferredDataType" : "string",
          "propertyName" : "buttonValue"
        } ]
      },
      "challenge" : {
        "type" : "string",
        "displayName" : "Challenge",
        "preferredControlType" : "textField",
        "enableParameters" : true
      },
      "button" : {
        "constructType" : "button",
        "displayName" : "Submit",
        "preferredControlType" : "button",
        "css" : {
          "backgroundColor" : "#1CAB42",
          "color" : "#ffffff"
        },
        "onClick" : {
          "constructType" : "skEvent",
          "eventName" : "continue",
          "eventType" : "post",
          "postProcess" : { }
        }
      },
      "showFooter" : {
        "value" : true
      },
      "returnRequestParameters" : {
        "value" : true
      },
      "messageTitle" : {
        "value" : "Information"
      },
      "message" : {
        "value" : ""
      },
      "showPoweredBy" : {
        "value" : false
      },
      "showContinueButton" : {
        "value" : false
      },
      "httpMethod" : {
        "value" : "GET"
      },
      "httpBody" : {
        "value" : "none"
      },
      "raw" : {
        "value" : ""
      },
      "signResponse" : {
        "value" : false
      },
      "additionalFieldsName" : {
        "value" : "additionalProperties"
      },
      "unsafeIgnoreTLSErrors" : {
        "value" : false
      },
      "delayTime" : {
        "value" : 50
      },
      "returnSuccess" : {
        "value" : true
      },
      "keepOutputIfNotValid" : {
        "value" : false
      },
      "fieldValidation" : {
        "value" : false
      },
      "outboundMtlsKey" : {
        "value" : "none"
      },
      "nodeTitle" : {
        "value" : "Username/Password Form"
      },
      "isLinkStyleSheetSupportEnabled" : {
        "value" : false
      }
    },
    "userViews" : [ {
      "screenTemplateName" : "CustomHTMLTemplate",
      "items" : [ {
        "propertyName" : "sktemplate"
      }, {
        "propertyName" : "customHTML"
      }, {
        "propertyName" : "validationRules"
      }, {
        "propertyName" : "customCSS"
      }, {
        "propertyName" : "customScript"
      }, {
        "propertyName" : "inputSchema"
      }, {
        "propertyName" : "outputSchema"
      }, {
        "propertyName" : "formFieldsList"
      }, {
        "propertyName" : "challenge"
      }, {
        "propertyName" : "button"
      } ]
    } ],
    "metadata" : {
      "colors" : {
        "canvas" : "#AFD5FF",
        "canvasText" : "#253746",
        "dark" : "#2E5EA6"
      },
      "logos" : {
        "canvas" : {
          "imageFileName" : "http.svg"
        }
      },
      "type" : "core",
      "vendor" : ""
    }
  },
  "interactionId" : "0344195d...7",
  "interactionToken" : "26bb08a75...",
  "skProxyApiEnvironmentId" : "us-west-2",
  "_links" : {
    "self" : {
      "href" : "https://auth.pingone.com/{{envID}}/davinci/policy/{{davinciFlowPolicyID}}/start"
    }
  }
}
```

## DaVinci and PingOne configuration requirements

In DaVinci, you must configure your application, the flow, and the flow policy to meet the requirements below:

* A DaVinci application.

* A DaVinci flow designated as a PingOne flow.

* A DaVinci flow policy that includes the PingOne flow.

* A PingOne OIDC application that is associated with the DaVinci flow policy.

|   |                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|   | For PingOne flows, in addition to defining an application in DaVinci, you must also configure a PingOne OIDC application and map it to a DaVinci flow policy ID. The PingOne application ID is the `client_id` parameter value in the authorize request. For information about DaVinci configuration, refer to [Launching a PingOne flow with a redirect](https://docs.pingidentity.com/davinci/integrating_flows_into_applications/davinci_launch_flow_redirect.html). |

## Flow execution

To execute a PingOne flow using APIs and receive verbose responses, follow these steps:

## Step 1: Initiate the flow through a PingOne authorize request

1. Use the PingOne `/as/authorize` OIDC endpoint to initiate authorization.

2. In the authorize request, set the `response_mode` property value to `pi.flow`. The `pi.flow` value specifies a non-redirect flow where the `redirect_uri` parameter is not required and authorization response data is returned directly to the client.

3. Set the `client_id` (the PingOne application client ID mapped to the DaVinci flow policy), the `response_type`, and `scopes` properties for the authorize request. For information about PingOne authorize endpoint properties, refer to [Authorization](../../openid-connect-oauth-2/authorize-intro.html).

## Step 2: Execute the next flow action

1. Use the resource link returned in the response (example shown below) to execute subsequent steps of the flow.

   ```json
      "_links": {
            "href": "{{authPath}}/{{envID}}/davinci/connections/{{connectionInstanceID}}/capabilities/{{capabilityName}}"
      },
   ```

   |   |                                                                                                                                                                                                                                 |
   | - | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   |   | In this link, the `{{connectionInstanceID}}` value is the `"connectionId"` capability property in the previous API response. The `{{capabilityName}}` is the `"capabilityName"` property returned in the previous API response. |

## Step 3: Complete the flow

1. On successful flow completion, the response includes the `ST-Cookie` and `ST-NO-SS` session cookies in the response headers to indicate that a session has been established.

2. The response returns the `returnSuccessResponseRedirect` capability and the following JSON structure to PingOne:

   ```json
    {
      "environment" : {
        "id" : "6baead75..."
      },
      "session" : {
        "id" : "8e918b54..."
      },
      "authorizeResponse" : {
        "access_token" : "eyJraWQiOiI3YT...",
        "id_token" : "eyJraWQiOiI3YTVh...",
        "token_type" : "Bearer",
        "expires_in" : 3600,
        "scope" : "openid profile"
      },
      "status" : "COMPLETED"
    }
   ```

## DaVinci flow capabilities data model properties

| Property                                   | Type?   | Required? | Mutable?  | Description                                                                                |
| ------------------------------------------ | ------- | --------- | --------- | ------------------------------------------------------------------------------------------ |
| `authorizeResponse`                        | Object  | N/A       | Read only | The response from the authorization server.                                                |
| `authorizeResponse.code`                   | String  | N/A       | Read only | The authorization code returned by the authorization server.                               |
| `companyId`                                | String  | N/A       | Read only | The company ID (same value as the PingOne environment ID).                                 |
| `capabilityName`                           | String  | N/A       | Read only | The name of the associated capability used by the node.                                    |
| `connectionId`                             | String  | N/A       | Read only | The connection ID of the connector used to send the event.                                 |
| `environment`                              | Object  | N/A       | Read only | The environment object.                                                                    |
| `environment.id`                           | String  | N/A       | Read only | The environment ID.                                                                        |
| `eventName`                                | String  | N/A       | Read only | The event name.                                                                            |
| `flowId`                                   | String  | N/A       | Read only | The flow ID.                                                                               |
| `form`                                     | Object  | Optional  | Mutable   | The form attributes object.                                                                |
| `form.name`                                | String  | Optional  | Mutable   | The form name.                                                                             |
| `form.description`                         | String  | Optional  | Mutable   | The form description.                                                                      |
| `form.category`                            | String  | Optional  | Mutable   | The form category.                                                                         |
| `form.components`                          | Object  | Optional  | Mutable   | The form components object.                                                                |
| `form.components.fields`                   | Object  | Optional  | Mutable   | The form fields object.                                                                    |
| `id`                                       | String  | N/A       | Read only | The resource ID.                                                                           |
| `interactionId`                            | String  | N/A       | Read only | A unique identifier for the flow execution.                                                |
| `interactionToken`                         | String  | N/A       | Read only | The flow execution interaction token.                                                      |
| `isResponseCompatibleWithMobileAndWebSdks` | Boolean | N/A       | Read only | Specifies whether the response is compatible with the mobile and web SDKs.                 |
| `parameters`                               | Object  | Required  | Mutable   | The form data attributes.                                                                  |
| `parameters.eventType`                     | String  | Required  | Mutable   | The event type. Options are `action`, and `submit`.                                        |
| `parameters.data`                          | Object  | Required  | Mutable   | The parameter data JSON object. Options are `action`, and `submit`.                        |
| `parameters.data.actionKey`                | String  | Required  | Mutable   | If the `parameters.eventType` is set to `action`, this property specifies the flow action. |
| `parameters.data.formData`                 | Object  | Required  | Mutable   | The form data attributes.                                                                  |
| `parameters.data.formData.{{attribute}}`   | String  | Required  | Mutable   | The form data attributes that are associated with fields in the form.                      |
| `resetCookie`                              | Boolean | N/A       | Read only | Specifies whether the reset cookie feature is enabled.                                     |
| `session`                                  | Object  | N/A       | Read only | The session object.                                                                        |
| `session.id`                               | String  | N/A       | Read only | The session ID.                                                                            |
| `status`                                   | String  | N/A       | Read only | The status of the DaVinci flow (for example, `COMPLETE`).                                  |
| `subFlowSettings`                          | Object  | N/A       | Read only | The subflow settings JSON object.                                                          |
| `success`                                  | Boolean | N/A       | Read only | Specifies whether the flow was successful.                                                 |