icon_search Search
Close X

HOW CAN WE HELP?

# Parties - v4.0

# 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

OBParty2

# 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 For a full list of enumeration values refer to OB_Internal_CodeSet here (opens new window). OBInternalPartyType1Code
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. For a full list of enumeration values refer to OB_Internal_CodeSet here (opens new window). OBInternalLegalStructureType1Code
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. For a full list of enumeration values refer to OB_Internal_CodeSet here (opens new window). OBInternalAccountRole1Code
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..* OBParty2/Address Postal address of a party. OBPostalAddress7

# OBPostalAddress7

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

OBReadParty2

# 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

# Data Dictionary

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

# OBPostalAddress7

The OBPostalAddress7 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.OBIE.PrivateLimitedCompany",
                "BeneficialOwnership": true,
                "AccountRole": "UK.OBIE.Principal",
                "EmailAddress": "contact@semiotec.co.jp",
                "LEI": "068700IA8DVYPS77MD05",
                "Relationships": {
                    "Account": {
                        "Related": "https://api.alphabank.com/open-banking/v4.0/aisp/accounts/22289",
                        "Id": "22289"
                    }
                },
                "Phone": "+442079460000", 
                "Mobile": "+447700900000",
                "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,
                "LEI": "068700IA8DVHGY77MD85",
                "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",
                "LEI": "068700IA8DVYPS77MD05",
                "BeneficialOwnership": true,
                "AccountRole": "UK.OBIE.Principal",
                "EmailAddress": "speakup@rosesandthorns.co.uk",
                "Phone": "+44-55565411099",
                "Mobile": "+44-55565411098",
                "Relationships": [{
                    "Account": {
                        "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,
                "LEI": "068700IA8DVHGY77MD85",
                "AccountRole": "UK.OBIE.SeniorManagingOfficial",
                "EmailAddress": "neil@rosesandthorns.co.uk",
                "Phone": "+44-55565411097",
                "Mobile": "+44-55565411096",
                "Relationships": [{
                  "Account": {
                        "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",
      "PartyNumber": "20202002",
      "Name": "Semiotec",
      "EmailAddress": "contact@semiotec.co.jp",
      "FullLegalName": "Mr Neil Paul Example",
      "LegalStructure": "UK.OBIE.Individual",
      "BeneficialOwnership": false,
      "AccountRole": "UK.OBIE.SeniorManagingOfficial",
      "LEI": "068700IA8DVYPS77MD05",
      "Phone": "+442079460000", 
      "Mobile": "+447700900000",
      "Address": {
        "AddressType": "Business",
        "StreetName": "Street",
        "BuildingNumber": "15",
        "PostCode": "NW1 1AB",
        "TownName": "London",
        "Country": "GB"
        },
       "Relationships": [{
          "Account": {
            "Related": "https://api.alphabank.com/open-banking/v4.0/aisp/accounts/89019",
            "Id": "89019"
          }
     }],
  },
  "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",
      "PartyNumber": "20202002",
      "PartyType": "Delegate",
      "Name": "Mr D User",
      "FullLegalName": "Mr Neil Paul Example",
      "LegalStructure": "UK.OBIE.Individual",
      "BeneficialOwnership": false,
      "AccountRole": "UK.OBIE.SeniorManagingOfficial",
      "LEI": "713200JVLXQKY2R7XS50",
      "EmailAddress": "d.user@semiotec.co.jp",
      "Phone": "+442079460000", 
      "Mobile": "+447700900000",
      "Address": {
        "AddressType": "Business",
        "StreetName": "Street",
        "BuildingNumber": "15",
        "PostCode": "NW1 1AB",
        "TownName": "London",
        "Country": "GB"
        },
      "Relationships": [{
          "Account": {
            "Related": "https://api.alphabank.com/open-banking/v4.0/aisp/accounts/89019",
            "Id": "89019"
          }
     }],
    }
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking/v4.0/aisp/party/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

← Scheduled Payments→