Skip to main content
Create Hosted Consent Request
curl --request POST \
  --url https://api.yapily.com/hosted/consent-requests \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json;charset=UTF-8' \
  --data '
{
  "userId": "ca412fdf-5a30-43a2-88b7-5964a24a8e55",
  "applicationUserId": "string",
  "institutionIdentifiers": {
    "institutionId": "modelo-sandbox",
    "institutionCountryCode": "GB"
  },
  "userSettings": {
    "language": "en",
    "location": "GB"
  },
  "redirectUrl": "https://tpp-application.com/",
  "authorisationExpiresAt": "2021-06-10T11:36:54.887Z",
  "oneTimeToken": false,
  "accountRequest": {
    "transactionFrom": "2023-07-01T00:00:00.000Z",
    "transactionTo": "2023-08-01T00:00:00.000Z",
    "expiresAt": "2023-11-01T00:00:00.000Z",
    "featureScope": [
      "ACCOUNTS",
      "ACCOUNT",
      "ACCOUNT_BALANCES",
      "ACCOUNT_TRANSACTIONS",
      "IDENTITY"
    ]
  }
}
'
import requests

url = "https://api.yapily.com/hosted/consent-requests"

payload = {
    "userId": "ca412fdf-5a30-43a2-88b7-5964a24a8e55",
    "applicationUserId": "string",
    "institutionIdentifiers": {
        "institutionId": "modelo-sandbox",
        "institutionCountryCode": "GB"
    },
    "userSettings": {
        "language": "en",
        "location": "GB"
    },
    "redirectUrl": "https://tpp-application.com/",
    "authorisationExpiresAt": "2021-06-10T11:36:54.887Z",
    "oneTimeToken": False,
    "accountRequest": {
        "transactionFrom": "2023-07-01T00:00:00.000Z",
        "transactionTo": "2023-08-01T00:00:00.000Z",
        "expiresAt": "2023-11-01T00:00:00.000Z",
        "featureScope": ["ACCOUNTS", "ACCOUNT", "ACCOUNT_BALANCES", "ACCOUNT_TRANSACTIONS", "IDENTITY"]
    }
}
headers = {
    "Authorization": "Basic <encoded-value>",
    "Content-Type": "application/json;charset=UTF-8"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
  method: 'POST',
  headers: {
    Authorization: 'Basic <encoded-value>',
    'Content-Type': 'application/json;charset=UTF-8'
  },
  body: JSON.stringify({
    userId: 'ca412fdf-5a30-43a2-88b7-5964a24a8e55',
    applicationUserId: 'string',
    institutionIdentifiers: {institutionId: 'modelo-sandbox', institutionCountryCode: 'GB'},
    userSettings: {language: 'en', location: 'GB'},
    redirectUrl: 'https://tpp-application.com/',
    authorisationExpiresAt: '2021-06-10T11:36:54.887Z',
    oneTimeToken: false,
    accountRequest: {
      transactionFrom: '2023-07-01T00:00:00.000Z',
      transactionTo: '2023-08-01T00:00:00.000Z',
      expiresAt: '2023-11-01T00:00:00.000Z',
      featureScope: ['ACCOUNTS', 'ACCOUNT', 'ACCOUNT_BALANCES', 'ACCOUNT_TRANSACTIONS', 'IDENTITY']
    }
  })
};

fetch('https://api.yapily.com/hosted/consent-requests', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.yapily.com/hosted/consent-requests",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'userId' => 'ca412fdf-5a30-43a2-88b7-5964a24a8e55',
    'applicationUserId' => 'string',
    'institutionIdentifiers' => [
        'institutionId' => 'modelo-sandbox',
        'institutionCountryCode' => 'GB'
    ],
    'userSettings' => [
        'language' => 'en',
        'location' => 'GB'
    ],
    'redirectUrl' => 'https://tpp-application.com/',
    'authorisationExpiresAt' => '2021-06-10T11:36:54.887Z',
    'oneTimeToken' => false,
    'accountRequest' => [
        'transactionFrom' => '2023-07-01T00:00:00.000Z',
        'transactionTo' => '2023-08-01T00:00:00.000Z',
        'expiresAt' => '2023-11-01T00:00:00.000Z',
        'featureScope' => [
                'ACCOUNTS',
                'ACCOUNT',
                'ACCOUNT_BALANCES',
                'ACCOUNT_TRANSACTIONS',
                'IDENTITY'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Basic <encoded-value>",
    "Content-Type: application/json;charset=UTF-8"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.yapily.com/hosted/consent-requests"

	payload := strings.NewReader("{\n  \"userId\": \"ca412fdf-5a30-43a2-88b7-5964a24a8e55\",\n  \"applicationUserId\": \"string\",\n  \"institutionIdentifiers\": {\n    \"institutionId\": \"modelo-sandbox\",\n    \"institutionCountryCode\": \"GB\"\n  },\n  \"userSettings\": {\n    \"language\": \"en\",\n    \"location\": \"GB\"\n  },\n  \"redirectUrl\": \"https://tpp-application.com/\",\n  \"authorisationExpiresAt\": \"2021-06-10T11:36:54.887Z\",\n  \"oneTimeToken\": false,\n  \"accountRequest\": {\n    \"transactionFrom\": \"2023-07-01T00:00:00.000Z\",\n    \"transactionTo\": \"2023-08-01T00:00:00.000Z\",\n    \"expiresAt\": \"2023-11-01T00:00:00.000Z\",\n    \"featureScope\": [\n      \"ACCOUNTS\",\n      \"ACCOUNT\",\n      \"ACCOUNT_BALANCES\",\n      \"ACCOUNT_TRANSACTIONS\",\n      \"IDENTITY\"\n    ]\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Basic <encoded-value>")
	req.Header.Add("Content-Type", "application/json;charset=UTF-8")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api.yapily.com/hosted/consent-requests")
  .header("Authorization", "Basic <encoded-value>")
  .header("Content-Type", "application/json;charset=UTF-8")
  .body("{\n  \"userId\": \"ca412fdf-5a30-43a2-88b7-5964a24a8e55\",\n  \"applicationUserId\": \"string\",\n  \"institutionIdentifiers\": {\n    \"institutionId\": \"modelo-sandbox\",\n    \"institutionCountryCode\": \"GB\"\n  },\n  \"userSettings\": {\n    \"language\": \"en\",\n    \"location\": \"GB\"\n  },\n  \"redirectUrl\": \"https://tpp-application.com/\",\n  \"authorisationExpiresAt\": \"2021-06-10T11:36:54.887Z\",\n  \"oneTimeToken\": false,\n  \"accountRequest\": {\n    \"transactionFrom\": \"2023-07-01T00:00:00.000Z\",\n    \"transactionTo\": \"2023-08-01T00:00:00.000Z\",\n    \"expiresAt\": \"2023-11-01T00:00:00.000Z\",\n    \"featureScope\": [\n      \"ACCOUNTS\",\n      \"ACCOUNT\",\n      \"ACCOUNT_BALANCES\",\n      \"ACCOUNT_TRANSACTIONS\",\n      \"IDENTITY\"\n    ]\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.yapily.com/hosted/consent-requests")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Basic <encoded-value>'
request["Content-Type"] = 'application/json;charset=UTF-8'
request.body = "{\n  \"userId\": \"ca412fdf-5a30-43a2-88b7-5964a24a8e55\",\n  \"applicationUserId\": \"string\",\n  \"institutionIdentifiers\": {\n    \"institutionId\": \"modelo-sandbox\",\n    \"institutionCountryCode\": \"GB\"\n  },\n  \"userSettings\": {\n    \"language\": \"en\",\n    \"location\": \"GB\"\n  },\n  \"redirectUrl\": \"https://tpp-application.com/\",\n  \"authorisationExpiresAt\": \"2021-06-10T11:36:54.887Z\",\n  \"oneTimeToken\": false,\n  \"accountRequest\": {\n    \"transactionFrom\": \"2023-07-01T00:00:00.000Z\",\n    \"transactionTo\": \"2023-08-01T00:00:00.000Z\",\n    \"expiresAt\": \"2023-11-01T00:00:00.000Z\",\n    \"featureScope\": [\n      \"ACCOUNTS\",\n      \"ACCOUNT\",\n      \"ACCOUNT_BALANCES\",\n      \"ACCOUNT_TRANSACTIONS\",\n      \"IDENTITY\"\n    ]\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "meta": {
    "tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
  },
  "data": {
    "consentRequestId": "507e515f-c22d-4bab-9801-606c94e7f749",
    "userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
    "applicationUserId": "string",
    "applicationId": "64949de6-6510-4d70-9500-d4aa094c506c",
    "institutionIdentifiers": {
      "institutionId": "modelo-sandbox",
      "institutionCountryCode": "GB"
    },
    "userSettings": {
      "language": "en",
      "location": "GB"
    },
    "redirectUrl": "https://tpp-application.com/",
    "accountRequestDetails": {
      "featureScope": [
        "ACCOUNTS",
        "ACCOUNT",
        "ACCOUNT_BALANCES",
        "ACCOUNT_TRANSACTIONS",
        "IDENTITY"
      ]
    },
    "hostedUrl": "https://prototypes.yapily.com/auth-link1.html",
    "createdAt": "2024-09-13T11:14:04.766Z",
    "authorisationExpiresAt": "2024-09-13T11:24:04.000Z"
  }
}
{
  "error": {
    "tracingId": "0c2d0973bdd24224a65e5d0f7d1b6154",
    "code": 400,
    "status": "BAD_REQUEST",
    "supportUrl": "https://support.yapily.com/",
    "source": "YAPILY",
    "issues": [
      {
        "type": "BAD_REQUEST",
        "code": 10600,
        "message": "The server could not understand the request due to invalid syntax"
      }
    ]
  }
}
{
  "error": {
    "tracingId": "0c2d0973bdd24224a65e5d0f7d1b6154",
    "code": 401,
    "status": "UNAUTHORIZED",
    "supportUrl": "https://support.yapily.com/",
    "source": "YAPILY",
    "issues": [
      {
        "type": "CREDENTIALS",
        "code": 10700,
        "message": "Authorization header invalid or credentials not authenticated"
      }
    ]
  }
}
{
  "error": {
    "tracingId": "0c2d0973bdd24224a65e5d0f7d1b6154",
    "code": 500,
    "status": "INTERNAL SERVER ERROR",
    "supportUrl": "https://support.yapily.com/",
    "source": "YAPILY",
    "issues": [
      {
        "type": "INTERNAL_SERVER_ERROR",
        "code": 11000,
        "message": "Unexpected server error"
      }
    ]
  }
}
{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}
Learn more: Hosted Consent Pages

Authorizations

​
Authorization
string
header
required

Use HTTP Basic Authentication with your Application ID as username and Application Secret as password. Manage credentials in the Yapily Console. See Authentication for details.

Headers

​
sub-application
string<uuid>

The sub-application ID to which event type is being subscribed to

Body

application/json;charset=UTF-8
​
institutionIdentifiers
object
required

Specifies the institution requirements for making the payment. Skips the bank selection screen in payment flow if the institutionId and institutionCountryCode are provided.

​
redirectUrl
string
required

URL of your server to redirect the user after completion of the consent flow.

Example:

"https://tpp-application.com"

​
userId
string<uuid>

Conditional. Yapily Identifier for the User returned by the create user step POST /users. You must provide either a userId or applicationUserId.

​
applicationUserId
string

Conditional. Your own User reference. This field allows you to use your own unique references for individual users. Where the User reference doesn't have an associated Yapily userId, a new userId is created and linked to it. You must provide either a userId or applicationUserId.

​
userSettings
object

Specifies the language and location preferences of the user.

​
oneTimeToken
boolean

Used to receive a oneTimeToken rather than a consentToken at the redirectUrl for additional security.

Example:

"false"

​
accountRequest
object

Conditional. Used to further specify details of the Consent to request

Conditions:

  1. Mandatory to specify the individual scopes to request from the user at the Institution for an account authorisation
  2. Mandatory to specify an expiry time on the created Consent at which time will render it unusable
  3. Mandatory to specify the date range that the created Consent will be able to access transactions for (given the range is support for the Institution)

Response

Created

​
meta
object
​
data
object