The Parties API from UK Open Banking — 3 operation(s) for parties.
openapi: 3.0.0
info:
title: Account and Transaction API Specification Account Access Consents Parties API
description: 'Swagger for Account and Transaction API Specification.
**Please Note**: There are no optional fields, if a field is not marked as “Required” it is a Conditional field.
'
termsOfService: https://www.openbanking.org.uk/terms
contact:
name: Service Desk
email: ServiceDesk@openbanking.org.uk
license:
name: open-licence
url: https://www.openbanking.org.uk/open-licence
version: 4.0.1
servers:
- url: /open-banking/v4.0/aisp
tags:
- name: Parties
paths:
/accounts/{AccountId}/parties:
get:
tags:
- Parties
summary: Get Parties for an AccountId
description: Enables an AISP to retrieve details about the PSU account-holder(s)/operator(s).
operationId: GetAccountsAccountIdParties
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/x-fapi-auth-date'
- $ref: '#/components/parameters/x-fapi-customer-ip-address'
- $ref: '#/components/parameters/x-fapi-interaction-id'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/x-customer-user-agent'
- $ref: '#/components/parameters/x-client-id'
responses:
'200':
$ref: '#/components/responses/200AccountsAccountIdPartiesRead'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'405':
$ref: '#/components/responses/405Error'
'406':
$ref: '#/components/responses/406Error'
'429':
$ref: '#/components/responses/429Error'
'500':
$ref: '#/components/responses/500Error'
security:
- PSUOAuth2Security:
- accounts
/accounts/{AccountId}/party:
get:
tags:
- Parties
summary: Get Party for an AccountId
description: Enables an AISP to retrieve details about the party that gave permission to the AISP to view a specific PSU account.
operationId: GetAccountsAccountIdParty
parameters:
- $ref: '#/components/parameters/AccountId'
- $ref: '#/components/parameters/x-fapi-auth-date'
- $ref: '#/components/parameters/x-fapi-customer-ip-address'
- $ref: '#/components/parameters/x-fapi-interaction-id'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/x-customer-user-agent'
- $ref: '#/components/parameters/x-client-id'
responses:
'200':
$ref: '#/components/responses/200AccountsAccountIdPartyRead'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'405':
$ref: '#/components/responses/405Error'
'406':
$ref: '#/components/responses/406Error'
'429':
$ref: '#/components/responses/429Error'
'500':
$ref: '#/components/responses/500Error'
security:
- PSUOAuth2Security:
- accounts
/party:
get:
tags:
- Parties
summary: Get Party
description: Retrieve details about the party that gave permission to the AISP to view an account(s).
operationId: GetParty
parameters:
- $ref: '#/components/parameters/x-fapi-auth-date'
- $ref: '#/components/parameters/x-fapi-customer-ip-address'
- $ref: '#/components/parameters/x-fapi-interaction-id'
- $ref: '#/components/parameters/Authorization'
- $ref: '#/components/parameters/x-customer-user-agent'
- $ref: '#/components/parameters/x-client-id'
responses:
'200':
$ref: '#/components/responses/200PartyRead'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'405':
$ref: '#/components/responses/405Error'
'406':
$ref: '#/components/responses/406Error'
'429':
$ref: '#/components/responses/429Error'
'500':
$ref: '#/components/responses/500Error'
security:
- PSUOAuth2Security:
- accounts
components:
schemas:
TownName:
description: Name of a built-up area, with defined boundaries, and a local government.
type: string
example: London
minLength: 1
maxLength: 140
PostCode:
description: Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.
type: string
example: EC2N 4AG
minLength: 1
maxLength: 16
PartyId:
description: A unique and immutable identifier used to identify the customer resource. This identifier has no meaning to the account owner.
type: string
example: PXSIF023
minLength: 1
maxLength: 40
Meta:
title: MetaData
type: object
description: Meta Data relevant to the payload
properties:
TotalPages:
type: integer
format: int32
FirstAvailableDateTime:
$ref: '#/components/schemas/ISODateTime'
LastAvailableDateTime:
$ref: '#/components/schemas/ISODateTime'
additionalProperties: false
LEI:
description: Legal entity identification as an alternate identification for a party. Legal Entity Identifier is a code allocated to a party as described in ISO 17442 "Financial Services - Legal Entity Identifier (LEI)".
type: string
example: IZ9Q00LZEVUKWCQY6X15
minLength: 1
maxLength: 20
pattern: ^[A-Z0-9]{18,18}[0-9]{2,2}$
Floor:
description: Number that identifies the level within a building
type: string
example: '11'
minLength: 1
maxLength: 70
PostBox:
description: Information that locates and identifies a box in a post office assigned to a person or organization, where letters for them are kept until called for.
type: string
example: PO Box 123456
minLength: 1
maxLength: 16
PhoneNumber_1:
description: Collection of information that identifies a mobile phone number, as defined by telecom services.
type: string
example: +44-7700900000
pattern: \+[0-9]{1,3}-[0-9()+\-]{1,30}
OBInternalPartyType1Code:
description: Party type, in a coded form. For a full list see `OBInternalPartyType1Code` in *OB_Internal_CodeSet* [here](https://github.com/OpenBankingUK/External_Internal_CodeSets)
type: string
example: Joint
enum:
- Delegate
- Joint
- Sole
PartyNumber:
description: Number assigned by an agent to identify its customer.
type: string
example: '20202002'
minLength: 1
maxLength: 35
UnitNumber:
description: Number that identifies the unit of a specific address .
type: string
example: A88
minLength: 1
maxLength: 16
OBExternalStatusReason1Code:
description: Low level textual error code, for all enum values see `OBExternalStatusReason1Code` in *OB_Internal_CodeSet* [here](https://github.com/OpenBankingUK/External_Internal_CodeSets)
type: string
minLength: 4
maxLength: 4
example: U001
CareOf:
description: The 'care of' address is used whenever sending mail to a person or organisation who does not actually live or work at the address. They will receive the mail for the individual.
type: string
example: Jane Smith
minLength: 1
maxLength: 140
OBInternalLegalStructureType1Code:
description: Legal standing of the party. For a full list refer to `OBInternalLegalStructureType1Code` in *OB_Internal_CodeSet* [here](https://github.com/OpenBankingUK/External_Internal_CodeSets)
type: string
example: UK.OBIE.Individual
x-namespaced-enum:
- UK.OBIE.CIC
- UK.OBIE.CIO
- UK.OBIE.Charity
- UK.OBIE.CoOp
- UK.OBIE.GeneralPartnership
- UK.OBIE.Individual
- UK.OBIE.LimitedLiabilityPartnership
- UK.OBIE.LimitedPartnership
- UK.OBIE.PrivateLimitedCompany
- UK.OBIE.PublicLimitedCompany
- UK.OBIE.ScottishLimitedPartnership
- UK.OBIE.Sole
FullLegalName:
description: The full legal name of the party.
type: string
example: Jane Smith
minLength: 1
maxLength: 350
OBParty2:
type: object
required:
- PartyId
properties:
PartyId:
$ref: '#/components/schemas/PartyId'
PartyNumber:
$ref: '#/components/schemas/PartyNumber'
PartyType:
$ref: '#/components/schemas/OBInternalPartyType1Code'
Name:
$ref: '#/components/schemas/Name_3'
FullLegalName:
$ref: '#/components/schemas/FullLegalName'
LegalStructure:
$ref: '#/components/schemas/OBInternalLegalStructureType1Code'
LEI:
$ref: '#/components/schemas/LEI'
BeneficialOwnership:
description: A flag to indicate a party's beneficial ownership of the related account
type: boolean
AccountRole:
$ref: '#/components/schemas/OBInternalAccountRole1Code'
EmailAddress:
$ref: '#/components/schemas/EmailAddress'
Phone:
$ref: '#/components/schemas/PhoneNumber_0'
Mobile:
$ref: '#/components/schemas/PhoneNumber_1'
Relationships:
$ref: '#/components/schemas/OBPartyRelationships1'
Address:
type: array
items:
$ref: '#/components/schemas/OBPostalAddress7'
additionalProperties: false
StreetName:
description: Name of a street or thoroughfare.
type: string
example: Bank Street
minLength: 1
maxLength: 140
Links:
type: object
description: Links relevant to the payload
properties:
Self:
type: string
format: uri
First:
type: string
format: uri
Prev:
type: string
format: uri
Next:
type: string
format: uri
Last:
type: string
format: uri
additionalProperties: false
required:
- Self
OBInternalAccountRole1Code:
description: A party’s role with respect to the related account. For a full list refer to `OBInternalAccountRole1Code` in *OB_Internal_CodeSet* [here](https://github.com/OpenBankingUK/External_Internal_CodeSets)
type: string
x-namespaced-enum:
- UK.OBIE.Administrator
- UK.OBIE.Beneficiary
- UK.OBIE.CustodianForMinor
- UK.OBIE.Granter
- UK.OBIE.LegalGuardian
- UK.OBIE.OtherParty
- UK.OBIE.PowerOfAttorney
- UK.OBIE.Principal
- UK.OBIE.Protector
- UK.OBIE.RegisteredShareholderName
- UK.OBIE.SecondaryOwner
- UK.OBIE.SeniorManagingOfficial
- UK.OBIE.Settlor
- UK.OBIE.SuccessorOnDeath
OBPostalAddress7:
type: object
description: Information that locates and identifies a specific address, as defined by postal services.
properties:
AddressType:
$ref: '#/components/schemas/OBAddressType2Code'
Department:
description: Identification of a division of a large organisation or building.
example: Finance
type: string
minLength: 1
maxLength: 70
SubDepartment:
description: Identification of a sub-division of a large organisation or building.
example: Payroll
type: string
minLength: 1
maxLength: 70
StreetName:
$ref: '#/components/schemas/StreetName'
BuildingNumber:
$ref: '#/components/schemas/BuildingNumber'
BuildingName:
$ref: '#/components/schemas/BuildingName'
Floor:
$ref: '#/components/schemas/Floor'
UnitNumber:
$ref: '#/components/schemas/UnitNumber'
Room:
$ref: '#/components/schemas/Room'
PostBox:
$ref: '#/components/schemas/PostBox'
TownLocationName:
$ref: '#/components/schemas/TownName'
DistrictName:
$ref: '#/components/schemas/DistrictName'
CareOf:
$ref: '#/components/schemas/CareOf'
PostCode:
$ref: '#/components/schemas/PostCode'
TownName:
$ref: '#/components/schemas/TownName'
CountrySubDivision:
description: Identifies a subdivision of a country such as state, region, county.
type: string
minLength: 1
maxLength: 35
Country:
description: Nation with its own government.
type: string
pattern: ^[A-Z]{2,2}$
AddressLine:
type: array
items:
description: Information that locates and identifies a specific address, as defined by postal services, presented in free format text.
type: string
minLength: 1
maxLength: 70
minItems: 0
maxItems: 7
EmailAddress:
description: Address for electronic mail (e-mail).
type: string
example: d.user@semiotec.co.jp
minLength: 1
maxLength: 256
ISODateTime:
description: "All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone. An example is below:\n2017-04-05T10:43:07+00:00"
type: string
format: date-time
OBAddressType2Code:
description: Identifies the nature of the postal address. <br /> For a full set of codes see `OBAddressType2Code` in *OB_Internal_CodeSet* [here](https://github.com/OpenBankingUK/External_Internal_CodeSets).
type: string
example: BIZZ
enum:
- BIZZ
- DLVY
- MLTO
- PBOX
- ADDR
- HOME
- CORR
- STAT
PhoneNumber_0:
description: Collection of information that identifies a phone number, as defined by telecom services.
example: +44-2079460000
type: string
pattern: \+[0-9]{1,3}-[0-9()+\-]{1,30}
Room:
description: Information that locates and identifies a room to form part of an address
type: string
example: Basement 03
minLength: 1
maxLength: 70
BuildingName:
description: Name of a referenced building.
type: string
minLength: 1
maxLength: 140
Name_3:
description: Name by which a party is known and which is usually used to identify that party.
type: string
example: Mx Jane Smith
minLength: 1
maxLength: 350
OBPartyRelationships1:
type: object
description: The Party's relationships with other resources.
properties:
Account:
type: object
required:
- Related
- Id
description: Relationship to the Account resource.
properties:
Related:
description: Absolute URI to the related resource.
type: string
example: https://api.alphabank.com/open-banking/v4.0/aisp/accounts/89019
format: uri
Id:
description: Unique identification as assigned by the ASPSP to uniquely identify the related resource.
type: string
example: '89019'
minLength: 1
maxLength: 40
OBErrorResponse1:
description: An array of detail error codes, and messages, and URLs to documentation to help remediation.
type: object
properties:
Id:
description: A unique reference for the error instance, for audit purposes, in case of unknown/unclassified errors.
type: string
minLength: 1
maxLength: 40
Code:
description: Deprecated <br />High level textual error code, to help categorise the errors.
type: string
minLength: 1
example: 400 BadRequest
maxLength: 40
Message:
description: Deprecated <br />Brief Error message
type: string
minLength: 1
example: There is something wrong with the request parameters provided
maxLength: 500
Errors:
items:
$ref: '#/components/schemas/OBError1'
type: array
minItems: 1
required:
- Errors
additionalProperties: false
BuildingNumber:
description: Number that identifies the position of a building on a street.
type: string
example: '11'
minLength: 1
maxLength: 16
OBReadParty2:
type: object
required:
- Data
properties:
Data:
type: object
properties:
Party:
$ref: '#/components/schemas/OBParty2'
Links:
$ref: '#/components/schemas/Links'
Meta:
$ref: '#/components/schemas/Meta'
additionalProperties: false
OBError1:
type: object
properties:
ErrorCode:
$ref: '#/components/schemas/OBExternalStatusReason1Code'
Message:
description: 'A description of the error that occurred. e.g., ''A mandatory field isn''t supplied'' or ''RequestedExecutionDateTime must be in future''
OBL doesn''t standardise this field'
type: string
minLength: 1
maxLength: 500
Path:
description: Recommended but optional reference to the JSON Path of the field with error, e.g., Data.Initiation.InstructedAmount.Currency
type: string
minLength: 1
maxLength: 500
Url:
description: URL to help remediate the problem, or provide more information, or to API Reference, or help etc
type: string
required:
- ErrorCode
additionalProperties: false
minProperties: 1
DistrictName:
description: Number that of the regional area, known as a district, which forms part of an address
type: string
example: Greater London
minLength: 1
maxLength: 140
OBReadParty3:
type: object
required:
- Data
properties:
Data:
type: object
properties:
Party:
type: array
items:
$ref: '#/components/schemas/OBParty2'
Links:
$ref: '#/components/schemas/Links'
Meta:
$ref: '#/components/schemas/Meta'
additionalProperties: false
responses:
200AccountsAccountIdPartyRead:
description: Parties Read
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
required: true
schema:
type: string
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/OBReadParty2'
application/json:
schema:
$ref: '#/components/schemas/OBReadParty2'
application/jose+jwe:
schema:
$ref: '#/components/schemas/OBReadParty2'
400Error:
description: Bad request
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
required: true
schema:
type: string
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/OBErrorResponse1'
application/json:
schema:
$ref: '#/components/schemas/OBErrorResponse1'
application/jose+jwe:
schema:
$ref: '#/components/schemas/OBErrorResponse1'
401Error:
description: Unauthorized
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
required: true
schema:
type: string
404Error:
description: Not found
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
required: true
schema:
type: string
405Error:
description: Method Not Allowed
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
required: true
schema:
type: string
429Error:
description: Too Many Requests
headers:
Retry-After:
description: Number in seconds to wait
schema:
type: integer
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
schema:
type: string
403Error:
description: Forbidden
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
required: true
schema:
type: string
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/OBErrorResponse1'
application/json:
schema:
$ref: '#/components/schemas/OBErrorResponse1'
application/jose+jwe:
schema:
$ref: '#/components/schemas/OBErrorResponse1'
200PartyRead:
description: Parties Read
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
required: true
schema:
type: string
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/OBReadParty2'
application/json:
schema:
$ref: '#/components/schemas/OBReadParty2'
application/jose+jwe:
schema:
$ref: '#/components/schemas/OBReadParty2'
200AccountsAccountIdPartiesRead:
description: Parties Read
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
required: true
schema:
type: string
RateLimit-Policy:
$ref: '#/components/headers/RateLimit-Policy'
RateLimit:
$ref: '#/components/headers/RateLimit'
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/OBReadParty3'
application/json:
schema:
$ref: '#/components/schemas/OBReadParty3'
application/jose+jwe:
schema:
$ref: '#/components/schemas/OBReadParty3'
500Error:
description: Internal Server Error
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
required: true
schema:
type: string
content:
application/json; charset=utf-8:
schema:
$ref: '#/components/schemas/OBErrorResponse1'
application/json:
schema:
$ref: '#/components/schemas/OBErrorResponse1'
application/jose+jwe:
schema:
$ref: '#/components/schemas/OBErrorResponse1'
406Error:
description: Not Acceptable
headers:
x-fapi-interaction-id:
description: An RFC4122 UID used as a correlation id.
required: true
schema:
type: string
parameters:
x-client-id:
in: header
name: x-client-id
required: false
description: "Only used if an ASPSP requires the client ID in order to return rate limit headers. \n\nTPPs __must__ refer to ASPSP developer portals for further information on any rate limit policies, if the headers are supported and any additional requirements.\n\nThis header __must not__ be used for client authentication\n"
schema:
type: string
x-fapi-auth-date:
in: header
name: x-fapi-auth-date
required: false
description: "The time when the PSU last logged in with the TPP. \nAll dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: \nSun, 10 Sep 2017 19:43:31 UTC"
schema:
type: string
pattern: ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} (GMT|UTC)$
AccountId:
name: AccountId
in: path
description: AccountId
required: true
schema:
type: string
Authorization:
in: header
name: Authorization
required: true
description: An Authorisation Token as per https://tools.ietf.org/html/rfc6750
schema:
type: string
x-fapi-interaction-id:
in: header
name: x-fapi-interaction-id
required: false
description: An RFC4122 UID used as a correlation id.
schema:
type: string
x-fapi-customer-ip-address:
in: header
name: x-fapi-customer-ip-address
required: false
description: The PSU's IP address if the PSU is currently logged in with the TPP.
schema:
type: string
x-customer-user-agent:
in: header
name: x-customer-user-agent
description: Indicates the user-agent that the PSU is using.
required: false
schema:
type: string
headers:
RateLimit-Policy:
required: false
description: 'TPPs __must__ refer to ASPSP developer portals for further information on any rate limit policies, if the headers are supported and any additional requirements.
A non-empty list of Quota Policy Items. The Item value __MUST__ be a String.
Example:
`RateLimit-Policy: "default";q=100;w=10`
The **REQUIRED** "q" parameter indicates the quota allocated by this policy measured in quota units.
The **OPTIONAL** "w" parameter value conveys a time window.
'
schema:
type: string
RateLimit:
required: false
description: 'TPPs __must__ refer to ASPSP developer portals for further information on any rate limit policies, if the headers are supported and any additional requirements.
A server uses the "RateLimit" response header field to communicate the current service limit for a quota policy for a particular partition key.
Example:
`RateLimit: "default";r=50;t=30`
The **REQUIRED** "r" parameter value conveys the remaining quota units for the identified policy.
The **OPTIONAL** "t" parameter value conveys the time window reset time for the identified policy.
'
schema:
type: string
securitySchemes:
TPPOAuth2Security:
type: oauth2
description: TPP client credential authorisation flow with the ASPSP
flows:
clientCredentials:
tokenUrl: https://authserver.example/token
scopes:
accounts: Ability to read Accounts information
PSUOAuth2Security:
type: oauth2
description: OAuth flow, it is required when the PSU needs to perform SCA with the ASPSP when a TPP wants to access an ASPSP resource owned by the PSU
flows:
authorizationCode:
authorizationUrl: https://authserver.example/authorization
tokenUrl: https://authserver.example/token
scopes:
accounts: Ability to read Accounts information