# # Parties - v4.0-draft1

- Overview
- Endpoints
  - GET /accounts/{AccountId}/parties
  - GET /accounts/{AccountId}/party
  - GET /party
- Data Model
  - Reused Classes
    - OBParty2
      - UML Diagram
      - Notes
      - Data Dictionary
    - OBPostalAddress6
  - OBReadParty2
    - UML Diagram
    - Data Dictionary
  - OBReadParty3
    - UML Diagram
    - Data Dictionary
  - OBPostalAddress6
  - Permission Codes
- Usage Examples
  - All Parties
    - Get Account Parties Request
    - Get Account Parties Response
  - All Parties
    - Get Parties Request
    - Get Parties Response
  - Account Owner
    - Get Account Party Request
    - Get Account Party Response
  - Authorised User
    - Get Party Request
    - 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 | Pagination |  | OBReadParty3
2 | parties | GET | GET /accounts/{AccountId}/party | Conditional | accounts | Authorization Code | No | Pagination |  | OBReadParty2
3 | parties | GET | GET /party | Conditional | accounts | Authorization Code | No | Pagination |  | 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

###### # 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. | Max350Text |  |
FullLegalName | 0..1 | OBParty2/FullLegalName | The full legal name of the party. | Max350Text |  |
LegalStructure | 0..1 | OBParty2/LegalStructure | Legal standing of the party. | OBExternalLegalStructureType1Code |  |
LEI | 0..1 | OBParty2/LEI | 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)". | Max20Text |  | [A-Z0-9]{18,18}[0-9]{2,2}
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. | OBPostalAddress6 |  |

#### # OBPostalAddress6

The OBPostalAddress6 class is defined in the payment-initiation-api-profile page

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

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

### # OBPostalAddress6

The OBPostalAddress6 class is defined in the account-and-transaction-api-profile page.

### # 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.OB.PrivateLimitedCompany",
                    "BeneficialOwnership": true,
                    "AccountRole": "UK.OB.Principal",
                    "EmailAddress": "contact@semiotec.co.jp",
                    "LEI": "068700IA8DVYPS77MD05",
                    "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.OB.Individual",
                    "BeneficialOwnership": false,
                    "LEI": "068700IA8DVHGY77MD85",
                    "AccountRole": "UK.OB.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.OB.PrivateLimitedCompany",
                    "LEI": "068700IA8DVYPS77MD05",
                    "BeneficialOwnership": true,
                    "AccountRole": "UK.OB.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.OB.Individual",
                    "BeneficialOwnership": false,
                    "LEI": "068700IA8DVHGY77MD85",
                    "AccountRole": "UK.OB.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",
           "LEI": "068700IA8DVYPS77MD05",
    	  "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",
          "LEI": "713200JVLXQKY2R7XS50",
          "EmailAddress": "d.user@semiotec.co.jp"
        }
      },
      "Links": {
        "Self": "https://api.alphabank.com/open-banking/v4.0/aisp/party/"
      },
      "Meta": {
        "TotalPages": 1
      }
    }