Manage data sharing consents
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/finicity-data-sharing-consent-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Open Finance Data Sharing Consent API
description: 'OpenAPI specification for Finicity APIs.
Open Finance (formerly Open Banking) solutions in the US are provided by
Finicity, a Mastercard company.'
contact:
name: API Support
email: apisupport@mastercard.com
url: https://developer.mastercard.com/open-finance-us/documentation/support/
version: 1.43.0
servers:
- url: https://api.finicity.com
description: Production
security:
- FinicityAppKey: []
FinicityAppToken: []
tags:
- name: Data Sharing Consent
description: Manage data sharing consents
paths:
/data-sharing-consents:
get:
tags:
- Data Sharing Consent
summary: Get Customer Data Sharing Consents By Customer ID
description: 'Retrieve data sharing consents for a partner by customer ID. _Supported regions_: '
operationId: GetDataSharingConsentsByCustomerId
parameters:
- $ref: '#/components/parameters/CustomerIdsQueryParameter'
- $ref: '#/components/parameters/DataSharingConsentStatusQueryParam'
- $ref: '#/components/parameters/SortByParameter'
- $ref: '#/components/parameters/SortOrderParameter'
- $ref: '#/components/parameters/ConsentStartParameter'
- $ref: '#/components/parameters/ConsentLimitParameter'
- $ref: '#/components/parameters/DataSharingConsentContextParam'
responses:
'200':
$ref: '#/components/responses/DataSharingConsentsByCustomerIdResponse'
'400':
$ref: '#/components/responses/ConsentBadRequestErrorResponse'
'404':
$ref: '#/components/responses/DataSharingConsentNotFoundError'
'401':
$ref: '#/components/responses/ConsentUnauthorizedErrorResponse'
security:
- FinicityAppKey: []
FinicityAppToken: []
/data-sharing-consents/{consent_receipt_id}:
get:
tags:
- Data Sharing Consent
summary: Get Customer Data Sharing Consent By ID
description: 'Retrieve a data sharing consent for a partner by consent receipt ID. _Supported regions_: '
operationId: GetDataSharingConsentsByID
parameters:
- $ref: '#/components/parameters/DataSharingConsentReceiptIdPathParam'
responses:
'200':
$ref: '#/components/responses/DataSharingConsentResponse'
'404':
$ref: '#/components/responses/DataSharingConsentNotFoundError'
'401':
$ref: '#/components/responses/ConsentUnauthorizedErrorResponse'
security:
- FinicityAppKey: []
FinicityAppToken: []
delete:
tags:
- Data Sharing Consent
summary: Revoke Data Sharing Consent by ID
description: 'Upon revoking, the status of all institutions within the given consent will be revoked and the consent status will be changed to ''INACTIVE''.
_Supported regions_: '
operationId: RevokeDataSharingConsentById
parameters:
- $ref: '#/components/parameters/DataSharingConsentReceiptIdPathParam'
- $ref: '#/components/parameters/DataSharingConsentUpdateByHeaderParam'
responses:
'204':
description: No content
'404':
$ref: '#/components/responses/DataSharingConsentNotFoundError'
'401':
$ref: '#/components/responses/ConsentUnauthorizedErrorResponse'
security:
- FinicityAppKey: []
FinicityAppToken: []
/data-sharing-consents/{consent_receipt_id}/institutionLogins/{institution_login_id}:
delete:
tags:
- Data Sharing Consent
summary: Revoke Data Sharing Consent for an Institution by Institution Login ID
description: 'Upon revoking by institution login ID, the status of the given institution will be revoked.
_Supported regions_: '
operationId: RevokeDataSharingConsentByInstitutionLoginID
parameters:
- $ref: '#/components/parameters/DataSharingConsentReceiptIdPathParam'
- $ref: '#/components/parameters/DataSharingConsentUpdateByHeaderParam'
- $ref: '#/components/parameters/ConsentInstitutionLoginIdParameter'
responses:
'204':
description: No content
'404':
$ref: '#/components/responses/DataSharingConsentNotFoundError'
'401':
$ref: '#/components/responses/ConsentUnauthorizedErrorResponse'
security:
- FinicityAppKey: []
FinicityAppToken: []
components:
parameters:
ConsentLimitParameter:
name: limit
in: query
required: false
description: Maximum number of results per page
schema:
type: integer
format: int32
default: 25
maximum: 1000
minimum: 1
example: 25
ConsentStartParameter:
name: start
in: query
required: false
description: Index of the page of results to return.
schema:
type: integer
format: int32
default: 1
minimum: 1
example: 1
SortOrderParameter:
name: sort_order
in: query
description: 'Ascending or Descending
Possible values are
1. Asc for Ascending
2. Desc for Descending
'
example: Asc
required: false
schema:
type: string
default: Desc
ConsentInstitutionLoginIdParameter:
description: The institution login ID
name: institution_login_id
in: path
required: true
schema:
$ref: '#/components/schemas/ConsentInstitutionLoginId'
example: '1007302745'
DataSharingConsentUpdateByHeaderParam:
name: Update-By
in: header
description: "Describes the entity who is invoking the request. Possible values are:\n 1. CUSTOMER - when the update is made by customer, e.g. arrangement is revoked.\n 2. PARTNER - when the update is made by a partner, e.g. customer is deleted.\n"
schema:
type: string
example: CUSTOMER
DataSharingConsentReceiptIdPathParam:
name: consent_receipt_id
description: A unique identifier of the consent given for a particular purpose.
in: path
required: true
schema:
type: string
example: 123e4567-e89b-42d3-a456-556642440000
CustomerIdsQueryParameter:
name: customer_id
description: A Mastercard Open Finance customer ID
in: query
required: true
schema:
$ref: '#/components/schemas/ConsentCustomerId'
example: '1005061234'
SortByParameter:
name: sort_by
in: query
description: 'Sort by consent creation or expiration date
Possible values are
1. startDate - Consent creation date
2. endDate - Consent expiration date
3. status - Consent status
'
example: startDate
required: false
schema:
type: string
default: startDate
DataSharingConsentContextParam:
name: context
in: query
schema:
type: string
description: 'Represents the context in which consent receipt was created.
Possible values are
1. partner - User grants consent to access account data
2. crossPartner - User grants consent to access account data fromdup
connections manager to another partner or associated applications
'
example: crossPartner
DataSharingConsentStatusQueryParam:
name: status
in: query
schema:
type: string
description: 'Represents the status of consent. Possible values are
1. ACTIVE - when consent is active with at least one active data holder.
2. INACTIVE - when there are no active data holders within the consent.
'
example: ACTIVE
schemas:
DataHandling:
required:
- postUsageStorage
- statement
type: object
properties:
postUsageStorage:
type: string
pattern: ^(\S)*$
description: What to do with the data after expiration of the consent access period. For Example - deIdentification
example: deIdentification
statement:
type: string
description: The purpose for which the partner is using the De-Idenified data
example: To improve the fraud detection
InstitutionInfo:
required:
- institutionId
- institutionName
- statusDetails
- accessPeriod
- isBusinessConsumerStatement
- accountOwnerCategory
- dataScopes
- createdDate
description: Represents the institution which has data that the user consents to share
properties:
institutionId:
type: string
description: Unique identifier representing a financial institution
minLength: 1
maxLength: 40
pattern: \d+
example: '2000003'
institutionLoginId:
type: string
pattern: \d+
minLength: 1
maxLength: 40
description: Unique identifier for account login credentials
example: '111566'
institutionName:
type: string
description: Name of the financial institution
minLength: 1
maxLength: 50
example: FinBank
accounts:
type: array
items:
$ref: '#/components/schemas/ConsentAccountDetails'
description: The list of account details
createdDate:
type: string
example: '2022-03-10T06:06:20Z'
description: The ISO-8601 format date when data holder was added to consent receipt
dataHandling:
$ref: '#/components/schemas/DataHandling'
lastUpdatedBy:
type: string
example: CUSTOMER
description: "Represents who updated the status of the Institution and the possible values are:\n\n 1. CUSTOMER - when the update is made by customer, e.g. arrangement is revoked.\n 2. PARTNER - when the update is made by a partner, e.g customer is deleted.\n 3. INSTITUTION - when the update is made by the institution, e.g. the arrangement is revoked by the institution on behalf of customer.\n 4. SYSTEM - when the update is made by the automated processes in the Mastercard Open Banking system, e.g. arrangement expires.\n 5. INTERNAL - when the update is made via internal Mastercard services, e.g. dispute resolution team revokes the consent on the customer’s request.\n"
statusDetails:
$ref: '#/components/schemas/InstitutionArrangementStatusDetails'
accessPeriod:
$ref: '#/components/schemas/InstitutionArrangementAccessPeriod'
isBusinessConsumerStatement:
type: string
description: 'Indicates that customer has given Business type of declaration
'
example: 'false'
accountOwnerCategory:
type: string
description: 'Indicates whether account owner type is INDIVIDUAL or a BUSINESS entity. Possible values are INDIVIDUAL, BUSINESS or undefined
'
example: INDIVIDUAL
dataScopes:
$ref: '#/components/schemas/DataScopes'
ConsentAccountDetails:
required:
- id
- status
properties:
id:
type: string
description: A Mastercard Open Banking account ID
minLength: 1
maxLength: 40
pattern: \d+
example: 453453
realAccountNumberLast4:
type: string
description: 'The account number from a financial institution in truncated format
'
minLength: 1
maxLength: 4
example: '8555'
type:
type: string
description: Account type from any of the supported account types
minLength: 1
maxLength: 40
example: mortgage
name:
type: string
description: 'The account name from the institution
'
minLength: 1
maxLength: 40
example: Spend account
status:
type: string
description: "This is the account level status, which can have below values for example.\n 1 . ACTIVE - when the account is added, it goes to active\nstate\n 2 . INACTIVE - when the account is removed it goes to\nINACTIVE state\n"
minLength: 5
maxLength: 10
example: ACTIVE
ConsentAccountId:
type: string
description: A unique identifier of an account within the Mastercard Open Banking system.
example: '11894700'
DataScopes:
type: array
description: List of data scopes requested or granted for this operation.
items:
type: object
properties:
id:
type: string
description: Unique identifier for the data scope.
name:
type: string
description: Human‑readable description of the data scope.
required:
- id
- name
example:
- id: ACCOUNT_DETAILED
name: Account Information - Basic + account balances, credit limits, due dates, interest rates, rewards balances, recurrences
- id: CUSTOMER_PERSONAL
name: Name, Email, Address, Phone, Date of Birth, Tax ID, SSN on file with this institution
- id: ACCOUNT_BASIC
name: Account display name, masked account number, type, description
- id: STATEMENTS
name: Periodic PDF statement showing personal information, account and transaction details
DataSharingConsentReceipt:
required:
- consentReceiptId
- receiptVersion
- customerId
- customerCategory
- purpose
- partnerId
- statusDetails
- accessPeriod
- createdDate
type: object
description: The consent receipt
properties:
consentReceiptId:
type: string
description: A unique identifier of the consent given for a particular purpose
minLength: 36
maxLength: 36
example: 123e4567-e89b-42d3-a456-556642440000
receiptVersion:
type: integer
description: Latest revision number for the given consent receipt
minLength: 1
maxLength: 4
example: 1
customerId:
type: string
minLength: 1
maxLength: 22
pattern: ^[0-9]*$
description: Id of the customer
example: '1005061234'
customerCategory:
type: string
minLength: 1
maxLength: 20
description: 'Indicates whether the service will be provided to the customer as an
individual or a business entity. Possible values are BUSINESS, INDIVIDUAL
'
example: BUSINESS
default: INDIVIDUAL
purpose:
type: string
description: Purpose for this consent
example: Lending
purposeStatement:
type: string
description: This field shows the purpose for which consent is created with the given institution
minLength: 1
maxLength: 255
example: to manage your budget
applicationId:
type: string
description: Represents identifier of the application for which partner has registered
example: f8bde4ef-1b6c-4822-93f0-5df7182e5285
applicationName:
type: string
description: The name of the application that created by the partner.
example: My Banking App
context:
$ref: '#/components/schemas/DataSharingConsentContext'
allowedTrnxHistoryInDays:
type: integer
description: "Number of days into the past to which the consent allows access to transactions. For example, if this value is set to 60, the consent allows access to transactions from the last 60 days from the start time of the consent agreement.\n\n If the value is 0 (zero), the consent does not allow\naccessing the transactions that happened prior to the starting date of the consent.\n\n The maximum allowed value is 365.\n\n If the value is more than 0, this information should be displayed\nto the customers in the consent agreement.\n"
maximum: 365
minimum: 0
example: 365
createdDate:
type: string
description: 'Date and time when the consent was created.
Date and time in ISO 8601 format.
'
example: 2022-07-16 06:06:20+00:00
disclosures:
type: array
description: List of entities to whom the consented data has been disclosed
items:
$ref: '#/components/schemas/DisclosureDetails'
statusDetails:
$ref: '#/components/schemas/ConsentStatusDetails'
institutions:
type: array
description: Products and scopes for which Financial-Consent is given to the recipient
items:
$ref: '#/components/schemas/InstitutionInfo'
accessPeriod:
$ref: '#/components/schemas/ConsentAccessPeriod'
ConsentAccessPeriod:
required:
- startDate
- endDate
type: object
description: 'A period of time allowed for accessing the customer’s data granted by this consent.
If the consent contains more than one institution arrangement, then this period is defined by the longest one.
This information is displayed to the customers in the consent agreement and consent receipt.'
properties:
startDate:
$ref: '#/components/schemas/ISODateTime'
endDate:
$ref: '#/components/schemas/ISODateTime'
ConsentErrorMessage:
required:
- code
type: object
properties:
code:
type: object
description: An error code (can be returned as a number or a string)
example: '10001'
status:
type: string
description: A status code
example: '401'
title:
type: string
description: A title for the error
example: Connecting accounts error
level:
type: string
description: An error level
example: error
message:
type: string
description: An error message
example: Invalid authorization credentials
user_message:
type: string
description: Some more details about the error
example: The session has expired or is invalid
assetId:
$ref: '#/components/schemas/AssetId'
accountId:
$ref: '#/components/schemas/ConsentAccountId'
DisclosureDetails:
required:
- type
- name
properties:
type:
type: string
description: 'For US, the value should be an empty array.
Possible values: Empty array for US partners.
'
example: []
name:
type: string
description: Name of the third party entity to whom that data is being disclosed.
example: Partner Name
ConsentInstitutionLoginId:
type: string
pattern: ^[0-9]+$
minLength: 1
maxLength: 20
description: A unique identifier of the authentication session with the Financial Institution within the Mastercard Open Banking system.
example: '1007302745'
InstitutionArrangementStatusDetails:
type: object
description: 'Details of the Institution status.
'
required:
- status
- statusDate
properties:
status:
type: string
description: 'Status of the Institution. Possible values are:
ACTIVE - Accounts data of an Institution can be accessed.
REVOKED - When the status of the Institution is revoked. Accounts data of an Institution can''t be accessed anymore.
EXPIRED - When the status of the Institution is expired. Accounts data of an institution can''t be accessed anymore.
'
example: ACTIVE
statusDate:
type: string
description: 'Date and time (in ISO 8601 format) when the consent was updated.
'
example: 2022-07-16 06:06:20+00:00
DataSharingConsentReceipts:
type: object
description: List of consent receipts
required:
- consents
- found
- displaying
- moreAvailable
properties:
found:
type: integer
description: The total number of results matching search criteria
example: 100
displaying:
type: integer
description: The number of results returned
example: 10
moreAvailable:
description: 'If `true`, you can fetch the next page of results
'
type: boolean
example: true
consents:
type: array
description: List of consent receipts
items:
$ref: '#/components/schemas/DataSharingConsentReceipt'
ISODateTime:
type: string
description: 'A date and time in ISO 8601 format (YYYY-MM-DDThh:mm:ssTZD). See also: [How do I handle Dates and Times?](https://developer.mastercard.com/open-finance-us/documentation/errors/best-practices/).'
example: '2022-07-16T06:06:20Z'
ConsentStatusDetails:
type: object
required:
- status
- statusDate
description: 'Details on the status of the consent.
'
properties:
status:
type: string
description: "Status of the consent. Possible values are:\n\n\n ACTIVE - One of the institution arrangements under the consent is\nACTIVE.\n Customer’s data can be accessed using this consent.\n\n INACTIVE - None of the institution arrangements under the consent\nis ACTIVE. Customer’s data cannot be accessed further using this consent.\n"
minLength: 5
maxLength: 10
example: ACTIVE
statusDate:
type: string
description: 'Date and time (in ISO 8601 format) when the consent was updated.
'
example: 2022-07-16 06:06:20+00:00
AssetId:
type: string
description: An asset ID. Generated by Data Connect or by using the Store Customer Pay Statement API.
example: 097545c5-1c2a-4f20-a5ef-77f0820344c9-2018601178
ConsentCustomerId:
type: string
pattern: ^[0-9]+$
description: 'A Mastercard Open Finance customer ID. See also: "Add Customer".'
example: '1005061234'
minLength: 1
DataSharingConsentContext:
type: string
description: 'Represents the context in which consent receipt was created.
Possible values are
1. partner - User grants consent to access account data
2. crossPartner - User grants consent to access account data from
connections manager to another partner or associated applications
Context is mandatory in .
'
example: crossPartner
InstitutionArrangementAccessPeriod:
type: object
description: 'A period of time allowed for accessing the customer’s data for the particular institution. This information must be displayed to the customers in the consent agreement.
'
required:
- startDate
- endDate
properties:
startDate:
$ref: '#/components/schemas/ISODateTime'
endDate:
$ref: '#/components/schemas/ISODateTime'
examples:
ConsentExpiredTokenExample:
value:
code: '10022'
status: '401'
message: Invalid (App-Token)
user_message: ''
ConsentInvalidFieldExample:
value:
code: '10100'
status: '400'
message: Invalid parameter - sortBy
user_message: ''
ConsentGenericBadRequestExample:
value:
code: '14020'
status: '400'
message: Bad request. One or more request parameters are invalid or missing.
user_message: Please review the request and ensure all required parameters are provided and valid.
ConsentMissingAppKeyExample:
value:
code: '10026'
status: '401'
message: Missing parameter (App-Key)
user_message: ''
DataSharingConsentNotFoundError:
value:
code: '10215'
status: '404'
message: Consent receipt not found
user_message: ''
responses:
DataSharingConsentResponse:
description: Data sharing consent retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/DataSharingConsentReceipt'
ConsentUnauthorizedErrorResponse:
description: The request lacks valid authentication credentials. Check "App-Key" or "App-Token".
content:
application/json:
schema:
$ref: '#/components/schemas/ConsentErrorMessage'
examples:
ExpiredTokenExample:
$ref: '#/components/examples/ConsentExpiredTokenExample'
MissingAppKeyExample:
$ref: '#/components/examples/ConsentMissingAppKeyExample'
DataSharingConsentNotFoundError:
description: Consent receipt not found
content:
application/json:
schema:
$ref: '#/components/schemas/ConsentErrorMessage'
examples:
DataSharingConsentNotFoundError:
$ref: '#/components/examples/DataSharingConsentNotFoundError'
DataSharingConsentsByCustomerIdResponse:
description: List of consent receipts
content:
application/json:
schema:
$ref: '#/components/schemas/DataSharingConsentReceipts'
ConsentBadRequestErrorResponse:
description: The request was rejected
content:
application/json:
schema:
$ref: '#/components/schemas/ConsentErrorMessage'
examples:
InvalidFieldExample:
$ref: '#/components/examples/ConsentInvalidFieldExample'
GenericBadRequestExample:
$ref: '#/components/examples/ConsentGenericBadRequestExample'
securitySchemes:
FinicityAppKey:
name: Finicity-App-Key
type: apiKey
in: header
description: The "Finicity-App-Key" from the developer dashboard
FinicityAppToken:
name: Finicity-App-Token
type: apiKey
in: header
description: A token returned by the `/authentication` API