> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yapily.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data tutorial using Yapily Hosted Pages

> Tutorial for accessing financial data using Yapily Hosted Pages. Create a data session and retrieve account information through the hosted open banking UI.

<Note>
  Hosted Pages is available as a [Beta version](/getting-started/overview#yapily-hosted-pages-beta).
  Please contact your Customer Success Manager if you would like to access it.
</Note>

## Introduction

This tutorial explains how to use Yapily Hosted Pages to access data.

**Note:** All requests made to the Yapily API require [basic authentication](/getting-started/integration-setup/api-authentication).

***

<Steps>
  <Step title="Create hosted consent request">
    Make a request to [POST /hosted/consent-requests](/api-reference/hosted-consent-pages/create-hosted-consent-request), including the institution country code, redirect URL and user ID or application User ID.

    You must provide the `institutionIdentifiers.institutionCountryCode` field. This controls the country of the institution to access the account data.

    In addition, you can optionally provide the ID of a specific institution in `institutionIdentifiers.institutionId` field to only allow data access from this institution. This skips the bank selection screen in the hosted flow.

    You can optionally provide `userSettings` to set the user's preferred language and location.

    <CodeGroup>
      ```bash Request theme={null}
      curl --location 'https://api.yapily.com/hosted/consent-requests' \
      --header 'Content-Type: application/json;charset=UTF-8' \
      --header 'Accept: application/json;charset=UTF-8' \
      --header 'Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ=' \
      --data '{
      	"redirectUrl": "https://tpp-application.com/",
      	"institutionIdentifiers": {
      		"institutionCountryCode": "GB"
      	},
      	"applicationUserId": "john.doe@company.com",
      	"userSettings": {
      		"language": "EN",
      		"location": "GB"
      	}
      }'
      ```

      ```json Response theme={null}
      {
      	"meta": {
      		"tracingId": "bffd676d6f804357b54eab07f1f41448"
      	},
      	"data": {
      		"consentRequestId": "fd19a5f3-b5ea-4cf0-8035-7e853a264f36",
      		"userId": "034b2e9c-0b16-4b60-b948-ff3c49d50741",
      		"applicationUserId": "john.doe@company.com",
      		"applicationId": "2e760724-289f-43ef-8bd7-d54dbf9dd5b1",
      		"institutionIdentifiers": {
      			"institutionCountryCode": "GB"
      		},
      		"userSettings": {
      			"language": "EN",
      			"location": "GB"
      		},
      		"redirectUrl": "https://tpp-application.com",
      		"hostedUrl": "https://consents.yapily.com?consentRequestId=fd19a5f3-b5ea-4cf0-8035-7e853a264f36&applicationId=2e760724-289f-43ef-8bd7-d54dbf9dd5b1#authToken=eyJraWQiOiIwNmViZTQ1Yy1hYzU5LTRiM2MtOWY5NC03MDljMDM5ZTQxYWIiLCJhbGciOiJFUzI1NiJ9.eyJhdWQiOiJwcm9kdWN0aW9uIiwic3ViIjoiMmU3NjA3MjQtMjg5Zi00M2VmLThiZDctZDU0ZGJmOWRkNWIxIiwib3JnIjoiMTg0ZTNiMTktY2YyMC00OTJiLTg5NWItOGRjYTFiYjFkNWE5IiwiY29uc2VudFJlcXVlc3RJZCI6ImZkMTlhNWYzLWI1ZWEtNGNmMC04MDM1LTdlODUzYTI2NGYzNiIsImlzcyI6Imhvc3RlZC1jb25zZW50IiwidHlwIjoiQVBQTElDQVRJT04iLCJleHAiOjE3MjgwNTA0NjgsImlhdCI6MTcyODA0OTg2OCwianRpIjoiNjk5YWFiOWQtOTJkMi00NjQ3LWE1ODktMjQxOTFhMjQzZjc0In0._DigB_vpIZOr3X7uR3KZb5lPGICVx96QwPH9XqGW1UnjY8XH0iVoGHr4y2Z1030psFOIaVq_HyU1OfMU8Hbb2g",
      		"createdAt": "2024-10-04T13:51:08.703Z",
      		"authorisationExpiresAt": "2024-10-04T14:01:08.000Z"
      	}
      }
      ```
    </CodeGroup>

    Store the `hostedUrl` returned in the response to use in step 2.
  </Step>

  <Step title="Redirect the user to the hosted URL">
    Redirect the end user from your application to the Yapily Hosted Pages URL. This initiates the user journey for the account consent request.
  </Step>

  <Step title="End user completes the account consent flow">
    The end user follows the Yapily hosted screens to complete the account consent request.

    A typical journey includes bank selection, redirection to their chosen bank, account consent confirmation and redirection back to your application.

    See [UI screens](/tools-and-services/hosted-pages/ui-screens) for more details.

    The user will be automatically redirected to the `redirectUrl` specified in the initial consent request in Step 1 once the consent flow is complete. We recommend you redirect the user back to your application to create a good user experience.

    The `consentRequestId` is returned as part of the `redirectUrl`. You can use this to check the status of the account consent in step 4.
  </Step>

  <Step title="Retrieve details of the account consent request">
    On an end user's completion of the hosted pages flow, you should check the consent status to confirm the consent has initiated successfully before proceeding with any further actions.

    You can retrieve details of the account consent request using [GET /hosted/consent-requests/{consentRequestId}](/api-reference/hosted-consent-pages/get-hosted-consent-request) specifying the `consentRequestId` in the path.

    <CodeGroup>
      ```bash Request theme={null}
      curl --location 'https://api.yapily.com/hosted/consent-requests/consentRequestId' \
      --header 'Accept: application/json;charset=UTF-8' \
      --header 'Authorization: Basic VXNlcm5hbWU6UGFzc3dvcmQ'
      ```

      ```json Response theme={null}
      {
      	"meta": {
      		"tracingId": "e8cf92170a22496799ec6e8e7a4bedb3"
      	},
      	"data": {
      		"consentRequestId": "b6c28cea-5544-46c6-ba3b-8a20adfce636",
      		"consentId": "2e2848b9-a838-4759-a259-6a3915f81902",
      		"userId": "034b2e9c-0b16-4b60-b948-ff3c49d50741",
      		"applicationUserId": "john.doe@company.com",
      		"applicationId": "2e760724-289f-43ef-8bd7-d54dbf9dd5b1",
      		"institutionIdentifiers": {
      			"institutionId": "modelo-sandbox",
      			"institutionCountryCode": "GB"
      		},
      		"userSettings": {
      			"language": "EN",
      			"location": "GB"
      		},
      		"redirectUrl": "https://display-parameters.com",
      		"createdAt": "2024-10-04T14:08:05.104Z",
      		"authorisationExpiresAt": "2024-10-04T14:18:05.000Z",
      		"status": "AUTHORIZED",
      		"phases": [
      			{
      				"phaseName": "INITIATED",
      				"phaseCreatedAt": "2024-10-04T14:08:05.104Z"
      			},
      			{
      				"phaseName": "INSTITUTION_SUBMITTED",
      				"phaseCreatedAt": "2024-10-04T14:08:11.686Z"
      			},
      			{
      				"phaseName": "AUTHORISATION_INITIATED",
      				"phaseCreatedAt": "2024-10-04T14:08:12.030Z"
      			},
      			{
      				"phaseName": "AUTHORISATION_CREATED",
      				"phaseCreatedAt": "2024-10-04T14:08:12.367Z"
      			},
      			{
      				"phaseName": "CONSENT_POLLING_STARTED",
      				"phaseCreatedAt": "2024-10-04T14:08:28.404Z"
      			},
      			{
      				"phaseName": "CONSENT_POLLING_ENDED",
      				"phaseCreatedAt": "2024-10-04T14:08:28.892Z"
      			},
      			{
      				"phaseName": "AUTHORISED",
      				"phaseCreatedAt": "2024-10-04T14:08:28.893Z"
      			},
      			{
      				"phaseName": "FINISHED",
      				"phaseCreatedAt": "2024-10-04T14:08:28.893Z"
      			}
      		],
      		"consentToken": "eyJraWQiOiIwNmViZTQ1Yy1hYzU5LTRiM2MtOWY5NC03MDljMDM5ZTQxYWIiLCJhbGciOiJFUzI1NiJ9.eyJJTlNUSVRVVElPTiI6Im1vZGVsby1zYW5kYm94IiwiQ09OU0VOVCI6IjJlMjg0OGI5LWE4MzgtNDc1OS1hMjU5LTZhMzkxNWY4MTkwMiIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJqb2huLmRvZUBjb21wYW55LmNvbSIsIlVTRVIiOiIwMzRiMmU5Yy0wYjE2LTRiNjAtYjk0OC1mZjNjNDlkNTA3NDEifQ.OsSU5Jr7W6L-k0c3MRpX8M-ASwGyAaf-vrgbrFJD2oz4bpWm2eE-58gzd3nO50RS7zEYCUmrGt2PTkJEgagZOQ"
      	}
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Retrieve account information">
    [Retrieve account information](/api-reference/financial-data/get-accounts), specifying the `consentToken` in the header.
  </Step>
</Steps>