# Parties - v3.1.5

  1. Overview
  2. Endpoints
    1. GET /accounts/{AccountId}/parties
    2. GET /accounts/{AccountId}/party
    3. GET /party
  3. Data Model
    1. Reused Classes
      1. OBParty2
        1. UML Diagram
        2. Notes
        3. Data Dictionary
    2. OBReadParty2
      1. UML Diagram
      2. Data Dictionary
    3. OBReadParty3
      1. UML Diagram
      2. Data Dictionary
    4. Permission Codes
  4. Usage Examples
    1. All Parties
      1. Get Account Parties Request
      2. Get Account Parties Response
    2. All Parties
      1. Get Parties Request
      2. Get Parties Response
    3. Account Owner
      1. Get Account Party Request
      2. Get Account Party Response
    4. Authorised User
      1. Get Party Request
      2. Get Party Response

# Overview

The parties resource is used by an AISP to retrieve the details on the account owner(s)/holder(s) and operator(s) for a specific account identified by AccountId.

The party resource is used by an AISP to retrieve the details on the account owner/holder for a specific account identified by AccountId:

  • 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.

This resource description should be read in conjunction with a compatible Account Information Services API Profile.

# Endpoints

Endpoints for the resource and available methods.

Resource HTTP Operation Endpoint Mandatory? Scope Grant Type Idempotency Key Parameters Request Object 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 theOBParty2class 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

 OBParty2.gif

# 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

 OBReadParty2.gif

# Data Dictionary

Name Occurrence XPath EnhancedDefinition Class Codes Pattern
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

 OBReadParty3.gif

# Data Dictionary

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

# Permission Codes

The ReadPartypermission 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

# 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

# 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

# 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

# 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": "+44-55565411099",
                "Mobile": "+44-55565411098",
                "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": "+44-55565411097",
                "Mobile": "+44-55565411096",
                "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

# 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

# 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",
      "EmailAddress": "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

# 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

# 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
  }
}