icon_search Search
Close X

HOW CAN WE HELP?

# Parties - v4.0.1

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

TPPs should refer to ASPSP developer portals to understand the approach they have taken for the conditional Parties endpoints and what conditional fields are supported.

ASPSPs should ensure they support the provision of any data available through their direct channel, such as full legal name.

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 implemented the /accounts/{AccountId}/parties endpoint, the ASPSP must return details on the account owner(s)/holder(s) and operator(s).

# GET /accounts/{AccountId}/party

If the ASPSP has implemented 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 implemented 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": "+44-2079460000",
        "Mobile": "+44-7700900000",
        "Address": [
          {
            "AddressType": "BIZZ",
            "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": "BIZZ",
            "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": "HOME",
            "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": "+44-2079460000",
      "Mobile": "+44-7700900000",
      "Address": {
        "AddressType": "BIZZ",
        "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": "+44-2079460000",
      "Mobile": "+44-7700900000",
      "Address": {
        "AddressType": "BIZZ",
        "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→