Version Control

Version	Date	Author	Comments
3.0-draft1	18-Apr-2018	OB R/W API Team	Initial draft for Version 3.0
3.0-draft3	22 May 2018	OB R/W API Team	Draft3 changes: Switched headings under Usage Examples for Account Owner and Authorised User - as these were documented incorrectly.
3.0-draft4	04 Jun 2018	OB R/W API Team	Clarified use of Idempotency Key in endpoint table.
3.0-draft5	13 Jun 2018	OB R/W API Team	Updated examples to change UTC to GMT to be in line with https://tools.ietf.org/html/rfc7231#page-66
3.0-draft6/rc1	27 Jun 2018	OB R/W API Team	Draft6 Changes: For consistency - added a Permission Codes section to clarify expected behaviour.
3.0-draft7	17 Jul 2018	OB R/W API Team	Draft 7 Changes: Changed Examples to Usage Examples for consistency
3.0-RC2	19 Jul 2018	OB R/W API Team	Errata: Updated Usage Example to include "Country" as this is a mandatory field
3.0-RC3	06 Aug 2018	OB R/W API Team	No Change
3.0	07 Sep 2018	OB R/W API Team	This is the baseline version. No change from RC3.

Endpoints

Endpoints for the resource - and available methods.

	Resource	HTTP Operation	Endpoint	Mandatory?	Scope	Grant Type	Idempotency Key	Parameters	Request Object	Response Object
1	party	GET	GET /accounts/{AccountId}/party	Conditional	accounts	Authorization Code	No			OBReadParty1
2	party	GET	GET /party	Conditional	accounts	Authorization Code	No			OBReadParty1

GET /accounts/{AccountId}/party

If the ASPSP has chosen to implement the /accounts/{AccountId}/party endpoint - the ASPSP must return details on the account owner:

In the case of a business - this will be the details of the business
In the case of a joint account - this will be the party that has given authorisation to the AISP to view the account. If the AISP wishes to access details of other parties linked to the AccountId, the AISP must go through an authorisation flow with the other parties.

GET /party

If the ASPSP has chosen to implement the the /party endpoint - the ASPSP must return details on the user that has authorised the account-request with the ASPSP:

In the case of a business account - this will be the details of the party that has given authorisation to the AISP to view the account
In the case of a joint account - this will be the party that has given authorisation to the AISP to view the account

Data Model

The OBReadParty1 object will be used for the call to:

GET /accounts/{AccountId}/party
GET /party

Resource Definition

A resource that contains a set of elements that describes the party linked to a specific account (AccountId).

The response to GET /accounts/{AccountId}/party and GET /party (if available) must contain at most one party.

UML Diagram

Permission Codes

The ReadParty permission is required to access GET /accounts/{AccountId}/party. The resource response payload does not differ depending on the permissions granted.

The ReadPartyPSU permission is required to access GET /party. The resource response payload does not differ depending on the permissions granted.

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes	Pattern
OBReadParty1		OBReadParty1		OBReadParty1
Data	1..1	OBReadParty1/Data		OBReadDataParty1
Party	0..1	OBReadParty1/Data/Party		OBParty1
PartyId	1..1	OBReadParty1/Data/Party/PartyId	A unique and immutable identifier used to identify the customer resource. This identifier has no meaning to the account owner.	Max40Text
PartyNumber	0..1	OBReadParty1/Data/Party/PartyNumber	Number assigned by an agent to identify its customer.	Max35Text
PartyType	0..1	OBReadParty1/Data/Party/PartyType	Party type, in a coded form.	OBExternalPartyType1Code	Delegate Joint Sole
Name	0..1	OBReadParty1/Data/Party/Name	Name by which a party is known and which is usually used to identify that party.	Max70Text
EmailAddress	0..1	OBReadParty1/Data/Party/EmailAddress	Address for electronic mail (e-mail).	Max256Text
Phone	0..1	OBReadParty1/Data/Party/Phone	Collection of information that identifies a phone number, as defined by telecom services.	PhoneNumber		\+[0-9]{1,3}-[0-9()+\-]{1,30}
Mobile	0..1	OBReadParty1/Data/Party/Mobile	Collection of information that identifies a mobile phone number, as defined by telecom services.	PhoneNumber		\+[0-9]{1,3}-[0-9()+\-]{1,30}
Address	0..n	OBReadParty1/Data/Party/Address	Postal address of a party.	OBPostalAddress8
AddressType	0..1	OBReadParty1/Data/Party/Address/AddressType	Identifies the nature of the postal address.	OBAddressTypeCode	Business Correspondence DeliveryTo MailTo POBox Postal Residential Statement
AddressLine	0..5	OBReadParty1/Data/Party/Address/AddressLine	Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text.	Max70Text
StreetName	0..1	OBReadParty1/Data/Party/Address/StreetName	Name of a street or thoroughfare.	Max70Text
BuildingNumber	0..1	OBReadParty1/Data/Party/Address/BuildingNumber	Number that identifies the position of a building on a street.	Max16Text
PostCode	0..1	OBReadParty1/Data/Party/Address/PostCode	Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.	Max16Text
TownName	0..1	OBReadParty1/Data/Party/Address/TownName	Name of a built-up area, with defined boundaries, and a local government.	Max35Text
CountrySubDivision	0..1	OBReadParty1/Data/Party/Address/CountrySubDivision	Identifies a subdivision of a country eg, state, region, county.	Max35Text
Country	1..1	OBReadParty1/Data/Party/Address/Country	Nation with its own government, occupying a particular territory.	CountryCode		^[A-Z]{2,2}$

Usage Examples

Account Owner

Request

Get Party Request

GET /accounts/22289/party HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

Response

Get Party Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "Party": {
      "PartyId": "PABC123",
      "PartyType": "Sole",
      "Name": "Semiotec",
      "Email": "contact@semiotec.co.jp",
	  "Address": {
		"AddressType": "Business",
		"StreetName": "Street",
		"BuildingNumber": "15",
		"PostCode": "NW1 1AB",
		"TownName": "London",
		"Country": "GB"
      }
    }
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v2.0/accounts/22289/party/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Authorised User