Version Control

Version	Date	Author	Comments
3.1	03 Dec 2018	OB R/W API Team	This is the baseline version.
4.0-draft1	18 Dec 2018	OB R/W API Team	No changes.
4.0-draft4	25 Jan 2019	OB R/W API Team	4.0-draft4 changes: Updated `account-request` reference to `account-access-consent`.
4.0-draft6	26 Feb 2019	OB R/W API Team	4.0-draft6 changes: Changed code snippet titles for consistency with other pages. Renamed page to "Parties" to reflect the new end-point name. Additional parties endpoint, data model and example.
4.0-draft7	18 Mar 2019	OB R/W API Team	Replace `x-fapi-customer-last-logged-time` with `x-fapi-auth-date` Removed all references to `x-fapi-financial-id`
3.1.2-RC1	25 Mar 2019	OB R/W API Team	v3.1.2-RC1 changes: Corrected examples. Release version renamed to 3.1.2

Endpoints

Endpoints for the resource and available methods.

	Resource	HTTP Operation	Endpoint	Mandatory?	Scope	Grant Type	Idempotency Key	Response Object
1	parties	GET	GET /accounts/{AccountId}/parties	Conditional	accounts	Authorization Code	No	OBReadParty3
2	parties	GET	GET /accounts/{AccountId}/party	Conditional	accounts	Authorization Code	No	OBReadParty2
3	parties	GET	GET /party	Conditional	accounts	Authorization Code	No	OBReadParty2

GET /accounts/{AccountId}/parties

If the ASPSP has chosen to implement the /accounts/{AccountId}/parties endpoint, the ASPSP may return details on the account owner(s)/holder(s) and operator(s).

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/holder:

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.

GET /party

If the ASPSP has chosen to implement the /party endpoint, the ASPSP must return details on the user that has authorised the account-access-consent 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 data dictionary section gives the detail on the payload content for the Party endpoints.

Reused Classes

OBParty2

This section describes the OBParty2 class which is reused as the Party resource in the OBReadParty2 and OBReadParty3 payloads.

The Party resource contains a set of elements that describes a party. The party may be linked to a specific account.

UML Diagram

Notes

Each ASPSP must determine appropriate format for the full legal name. This format should be documented on ASPSP developer portals.

Data Dictionary

Name	Occurence	XPath	EnhancedDefinition	Class	Codes	Pattern
OBParty2		OBParty2		OBParty2
PartyId	1..1	OBParty2/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	OBParty2/PartyNumber	Number assigned by an agent to identify its customer.	Max35Text
PartyType	0..1	OBParty2/PartyType	Party type	OBExternalPartyType1Code	Delegate Joint Sole
Name	0..1	OBParty2/Name	Name by which a party is known and which is usually used to identify that party.	Max70Text
FullLegalName	0..1	OBParty2/FullLegalName	The full legal name of the party.	Max350Text
LegalStructure	0..1	OBParty2/LegalStructure	Legal standing of the party.	OBExternalLegalStructureType1Code
BeneficialOwnership	0..1	OBParty2/BeneficialOwnership	A flag to indicate a party's beneficial ownership of the related account.	xs:boolean
AccountRole	0..1	OBParty2/AccountRole	A party's role with respect to the related account.	OBExternalAccountRole1Code
EmailAddress	0..1	OBParty2/EmailAddress	Address for electronic mail (e-mail).	Max256Text
Phone	0..1	OBParty2/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	OBParty2/Mobile	Collection of information that identifies a mobile phone number as defined by telecom services.	PhoneNumber		\+[0-9]{1,3}-[0-9()+\-]{1,30}
Relationships	0..1	OBParty2/Relationships	The Party's relationships with other resources.	OBPartyRelationships1
Account	0..1	OBParty2/Relationships/Account	Relationship to the Account resource.	OBRelationship1
Related	1..1	OBParty2/Relationships/Account/Related	Absolute URI to the related resource.	xs:anyURI
Id	1..1	OBParty2/Relationships/Account/Id	Unique identification as assigned by the ASPSP to uniquely identify the related resource.	Max40Text
Address	0..n	OBParty2/Address	Postal address of a party.	OBPostalAddress8
AddressType	0..1	OBParty2/Address/AddressType	Identifies the nature of the postal address.	OBAddressTypeCode	Business Correspondence DeliveryTo MailTo POBox Postal Residential Statement
AddressLine	0..5	OBParty2/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	OBParty2/Address/StreetName	Name of a street or thoroughfare.	Max70Text
BuildingNumber	0..1	OBParty2/Address/BuildingNumber	Number that identifies the position of a building on a street.	Max16Text
PostCode	0..1	OBParty2/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	OBParty2/Address/TownName	Name of a built-up area, with defined boundaries, and a local government.	Max35Text
CountrySubDivision	0..1	OBParty2/Address/CountrySubDivision	Identifies a subdivision of a country eg, state, region, county.	Max35Text
Country	1..1	OBParty2/Address/Country	Nation with its own government, occupying a particular territory.	CountryCode		^[A-Z]{2,2}$

OBReadParty2

The OBReadParty2 object will be used for the call to:

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

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

UML Diagram

Data Dictionary

Name	Occurrence	XPath	Class
OBReadParty2		OBReadParty2	OBReadParty2
Data	1..1	OBReadParty2/Data	OBReadDataParty2
Party	0..1	OBReadParty2/Data/Party	OBParty2

OBReadParty3

The OBReadParty3 object will be used for the call to:

GET /accounts/{AccountId}/parties

The response to GET /accounts/{AccountId}/parties may contain multiple parties.

UML Diagram

Data Dictionary

Name	Occurrence	XPath	Class
OBReadParty3		OBReadParty3	OBReadParty3
Data	1..1	OBReadParty3/Data	OBReadDataParty3
Party	0..n	OBReadParty3/Data/Party	OBParty2

Permission Codes

The ReadParty permission is required to access GET /accounts/{AccountId}/party or GET /accounts/{AccountId}/parties. 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.

Usage Examples

All Parties

Request

Get Account Parties Request

GET /accounts/22289/parties HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-auth-date:  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 Account Parties 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",
                "FullLegalName": "Semiotec Limited",
                "LegalStructure": "UK.OBIE.PrivateLimitedCompany",
                "BeneficialOwnership": true,
                "AccountRole": "UK.OBIE.Principal",
                "EmailAddress": "contact@semiotec.co.jp",
                "Relationships": {
                    "Account": {
                        "Related": "https://api.alphabank.com/open-banking/v4.0/aisp/accounts/22289",
                        "Id": "22289"
                    }
                },
                "Address": [
                    {
                        "AddressType": "Business",
                        "StreetName": "Street",
                        "BuildingNumber": "15",
                        "PostCode": "NW1 1AB",
                        "TownName": "London",
                        "Country": "GB"
                    }
                ]
            },
            {
                "PartyId": "PXSIF023",
                "PartyNumber": "0000007456",
                "PartyType": "Delegate",
                "Name": "Kevin Atkinson",
                "FullLegalName": "Mr Kevin Bartholmew Atkinson",
                "LegalStructure": "UK.OBIE.Individual",
                "BeneficialOwnership": false,
                "AccountRole": "UK.OBIE.Administrator",
                "EmailAddress": "kev@semiotec.co.jp",
                "Relationships": {
                    "Account": {
                        "Related": "https://api.alphabank.com/open-banking/v4.0/aisp/accounts/22289",
                        "Id": "22289"
                    }
                }
            }
        ]
    },
    "Links": {
        "Self": "https://api.alphabank.com/open-banking/v4.0/aisp/accounts/22289/parties"
    },
    "Meta": {
        "TotalPages": 1
    }
}

All Parties

Request

Get Parties Request

GET /accounts/89019/parties HTTP/1.1
Authorization: Bearer k4tsuc4r1
x-fapi-auth-date:  Sun, 10 Sep 2018 19:43:31 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 0761c465-0f8c-43d1-8952-f2cd7fa1aa8b
Accept: application/json

Response

Get Parties Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 0761c465-0f8c-43d1-8952-f2cd7fa1aa8b
Content-Type: application/json

{
    "Data": {
        "Party": [
            {
                "PartyId": "1982001",
                "PartyNumber": "20202001",
                "PartyType": "Sole",
                "Name": "Roses and Thorns Limited",
                "FullLegalName": "Roses and Thorns Limited",
                "LegalStructure": "UK.OBIE.PrivateLimitedCompany",
                "BeneficialOwnership": true,
                "AccountRole": "UK.OBIE.Principal",
                "EmailAddress": "speakup@rosesandthorns.co.uk",
                "Phone": "++4455565411099",
                "Mobile": "+4455565411098",
                "Relationships": [
                    {
                        "Related": "https://api.alphabank.com/open-banking/v4.0/aisp/accounts/89019",
                        "Id": "89019"
                    }
                ],
                "Address": [
                    {
                        "AddressType": "Business",
                        "StreetName": "Thomas More Square",
                        "BuildingNumber": "2",
                        "PostCode": "E1W 1YN",
                        "TownName": "London",
                        "Country": "GB"
                    }
                ]
            },
            {
                "PartyId": "1982002",
                "PartyNumber": "20202002",
                "Name": "Neil Example",
                "FullLegalName": "Mr Neil Paul Example",
                "LegalStructure": "UK.OBIE.Individual",
                "BeneficialOwnership": false,
                "AccountRole": "UK.OBIE.SeniorManagingOfficial",
                "EmailAddress": "neil@rosesandthorns.co.uk",
                "Phone": "+4455565411097",
                "Mobile": "+4455565411096",
                "Relationships": [
                    {
                        "Related": "https://api.alphabank.com/open-banking/v4.0/aisp/accounts/89019",
                        "Id": "89019"
                    }
                ],
                "Address": [
                    {
                        "AddressType": "Residential",
                        "StreetName": "Thomas More Square",
                        "BuildingNumber": "1",
                        "PostCode": "E1W 1YN",
                        "TownName": "London",
                        "Country": "GB"
                    }
                ]
            }
        ]
    },
    "Links": {
        "Self": "https://api.alphabank.com/open-banking/v4.0/aisp/accounts/89019/parties"
    },
    "Meta": {
        "TotalPages": 1
    }
}

Account Owner

Request

Get Account Party Request

GET /accounts/22289/party HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-auth-date:  Sun, 10 Sep 2017 19:43:31 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 7f570e68-c7f0-44e2-a934-a854d2ca8cca
Accept: application/json

Response

Get Account Party Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 7f570e68-c7f0-44e2-a934-a854d2ca8cca
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/v4.0/aisp/accounts/22289/party/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Authorised User

Request

Get Party Request

GET /party HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-auth-date:  Sun, 10 Sep 2017 19:43:31 GMT
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 7903ae4f-bbdf-4291-bb23-bd44daf7bc24
Accept: application/json

Response

Get Party Response

HTTP/1.1 200 OK
x-fapi-interaction-id: 7903ae4f-bbdf-4291-bb23-bd44daf7bc24
Content-Type: application/json

{
  "Data": {
    "Party": {
      "PartyId": "PXSIF023",
      "PartyType": "Delegate",
      "Name": "Mr D User",
      "EmailAddress": "d.user@semiotec.co.jp"
    }
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v4.0/aisp/party/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Developer Zone

Parties v3.1.2

Version Control

Endpoints

GET /accounts/{AccountId}/parties

GET /accounts/{AccountId}/party

GET /party

Data Model

Reused Classes

OBParty2

UML Diagram

Notes

Data Dictionary

OBReadParty2

UML Diagram

Data Dictionary

OBReadParty3

UML Diagram

Data Dictionary

Permission Codes

Usage Examples

All Parties

All Parties

Account Owner

Authorised User