Party v3.0

Version Control

VersionDateAuthorComments
3.0-draft118-Apr-2018OB R/W API TeamInitial draft for Version 3.0
3.0-draft3 OB R/W API Team

Draft3 changes:

  • Switched headings under Usage Examples for Account Owner and Authorised User - as these were documented incorrectly.
3.0-draft4 OB R/W API TeamClarified use of Idempotency Key in endpoint table.
3.0-draft5 OB R/W API TeamUpdated examples to change UTC to GMT to be in line with https://tools.ietf.org/html/rfc7231#page-66
3.0-draft6/rc1 OB R/W API Team

Draft6 Changes:

  • For consistency - added a Permission Codes section to clarify expected behaviour.
3.0-draft7 OB R/W API Team

Draft 7 Changes:

  • Changed Examples to Usage Examples for consistency
3.0-RC2 OB R/W API Team

Errata:

  • Updated Usage Example to include "Country" as this is a mandatory field
3.0-RC3 OB R/W API TeamNo Change
3.0 OB R/W API TeamThis is the baseline version. No change from RC3.

Endpoints

Endpoints for the resource - and available methods.


Resource
HTTP Operation
Endpoint
Mandatory?
Scope
Grant Type
Idempotency Key
Parameters
Request Object
Response Object
1partyGETGET /accounts/{AccountId}/partyConditionalaccountsAuthorization CodeNo

OBReadParty1
2partyGETGET /partyConditionalaccountsAuthorization CodeNo

OBReadParty1

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:

  • 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. If the AISP wishes to access details of other parties linked to the AccountId, the AISP must go through an authorisation flow with the other parties.

GET /party

If the ASPSP has chosen to implement the the /party endpoint - the ASPSP must return details on the user that has authorised the account-request 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 OBReadParty1 object will be used for the call to: 

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

Resource Definition

A resource that contains a set of elements that describes the party linked to a specific account (AccountId).

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

UML Diagram

Permission Codes

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

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBReadParty1
OBReadParty1
OBReadParty1

Data1..1OBReadParty1/Data
OBReadDataParty1

Party0..1OBReadParty1/Data/Party
OBParty1

PartyId1..1OBReadParty1/Data/Party/PartyIdA unique and immutable identifier used to identify the customer resource. This identifier has no meaning to the account owner.Max40Text

PartyNumber0..1OBReadParty1/Data/Party/PartyNumberNumber assigned by an agent to identify its customer.Max35Text

PartyType0..1OBReadParty1/Data/Party/PartyTypeParty type, in a coded form.OBExternalPartyType1CodeDelegate
Joint
Sole

Name0..1OBReadParty1/Data/Party/NameName by which a party is known and which is usually used to identify that party.Max70Text

EmailAddress0..1OBReadParty1/Data/Party/EmailAddressAddress for electronic mail (e-mail).Max256Text

Phone0..1OBReadParty1/Data/Party/PhoneCollection of information that identifies a phone number, as defined by telecom services.PhoneNumber
\+[0-9]{1,3}-[0-9()+\-]{1,30}
Mobile0..1OBReadParty1/Data/Party/MobileCollection of information that identifies a mobile phone number, as defined by telecom services.PhoneNumber
\+[0-9]{1,3}-[0-9()+\-]{1,30}
Address0..nOBReadParty1/Data/Party/AddressPostal address of a party.OBPostalAddress8

AddressType0..1OBReadParty1/Data/Party/Address/AddressTypeIdentifies the nature of the postal address.OBAddressTypeCodeBusiness
Correspondence
DeliveryTo
MailTo
POBox
Postal
Residential
Statement

AddressLine0..5OBReadParty1/Data/Party/Address/AddressLineInformation that locates and identifies a specific address, as defined by postal services, that is presented in free format text.Max70Text

StreetName0..1OBReadParty1/Data/Party/Address/StreetNameName of a street or thoroughfare.Max70Text

BuildingNumber0..1OBReadParty1/Data/Party/Address/BuildingNumberNumber that identifies the position of a building on a street.Max16Text

PostCode0..1OBReadParty1/Data/Party/Address/PostCodeIdentifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail.Max16Text

TownName0..1OBReadParty1/Data/Party/Address/TownNameName of a built-up area, with defined boundaries, and a local government.Max35Text

CountrySubDivision0..1OBReadParty1/Data/Party/Address/CountrySubDivisionIdentifies a subdivision of a country eg, state, region, county.Max35Text

Country1..1OBReadParty1/Data/Party/Address/CountryNation with its own government, occupying a particular territory.CountryCode
^[A-Z]{2,2}$

Usage Examples

Account Owner

Request

Get Party Request
GET /accounts/22289/party HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  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 Party 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",
      "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/v2.0/accounts/22289/party/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Authorised User

Request

Get Party Request
GET /party HTTP/1.1
Authorization: Bearer Az90SAOJklae
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  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 Party Response
HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

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