Version Control

Version	Date	Author	Comments
1.0.0	01 March 2019	Payments NZ API Working Group	Transactions specifications

Endpoints

Endpoints for the resource - and available methods.

	Resource	HTTP Operation	Endpoint	Mandatory?	Scope	Grant Type	Idempotent	Parameters	Request Object	Response Object
1	party	GET	GET /accounts/{AccountId}/party	Optional	accounts	Authorization Code				OBReadParty1
2	party	GET	GET /party	Optional	accounts	Authorization Code				OBReadParty1

GET /accounts/{AccountId}/party

If the API Provider has chosen to implement the /accounts/{AccountId}/party endpoint - the API Provider 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 Third Party to view the account. If the Third Party wishes to access details of other parties linked to the AccountId, the Third Party must go through an authorisation flow with the other parties.

GET /party

If the API Provider has chosen to implement the /party endpoint - the API Provider must return details on the user that has authorised the account-request with the API Provider:

In the case of a business account - this will be the details of the party that has given authorisation to the Third Party to view the account
In the case of a joint account - this will be the party that has given authorisation to the Third Party 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

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes	Pattern
OBReadParty1		OBReadParty1		OBReadParty1
Data	1..1	OBReadParty1/Data		OBReadDataParty1
Party	0..1	OBReadParty1/Data/Party		OBParty1
PartyId	1..1	OBReadParty1/Data/Party/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	OBReadParty1/Data/Party/PartyNumber	Number assigned by an agent to identify its customer.	Max35Text
PartyType	0..1	OBReadParty1/Data/Party/PartyType	Party type, in a coded form.	OBExternalPartyType1Code	Delegate Joint Sole
Name	0..1	OBReadParty1/Data/Party/Name	Name by which a party is known and which is usually used to identify that party.	Max70Text
EmailAddress	0..1	OBReadParty1/Data/Party/EmailAddress	Address for electronic mail (e-mail).	Max256Text
Phone	0..1	OBReadParty1/Data/Party/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	OBReadParty1/Data/Party/Mobile	Collection of information that identifies a mobile phone number, as defined by telecom services.	PhoneNumber		\+[0-9]{1,3}-[0-9()+\-]{1,30}
Address	0..n	OBReadParty1/Data/Party/Address	Postal address of a party.	OBPostalAddress8
AddressType	0..1	OBReadParty1/Data/Party/Address/AddressType	Identifies the nature of the postal address.	OBAddressTypeCode	Business Correspondence DeliveryTo MailTo POBox Postal Residential Statement
AddressLine	0..5	OBReadParty1/Data/Party/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	OBReadParty1/Data/Party/Address/StreetName	Name of a street or thoroughfare.	Max70Text
BuildingNumber	0..1	OBReadParty1/Data/Party/Address/BuildingNumber	Number that identifies the position of a building on a street.	Max16Text
PostCode	0..1	OBReadParty1/Data/Party/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	OBReadParty1/Data/Party/Address/TownName	Name of a built-up area, with defined boundaries, and a local government.	Max35Text
CountrySubDivision	0..1	OBReadParty1/Data/Party/Address/CountrySubDivision	Identifies a subdivision of a country eg, state, region, county.	Max35Text
Country	1..1	OBReadParty1/Data/Party/Address/Country	Nation with its own government, occupying a particular territory.	CountryCode		^[A-Z]{2,2}$

Enumerations

This section gives the definitions for enumerations used.

Code Class	Name	Definition
OBAddressTypeCode	Business	Address is the business address.
OBAddressTypeCode	Correspondence	Address is the address where correspondence is sent.
OBAddressTypeCode	DeliveryTo	Address is the address to which delivery is to take place.
OBAddressTypeCode	MailTo	Address is the address to which mail is sent.
OBAddressTypeCode	POBox	Address is a postal office (PO) box.
OBAddressTypeCode	Postal	Address is the complete postal address.
OBAddressTypeCode	Residential	Address is the home address.
OBAddressTypeCode	Statement	Address is the address where statements are sent.
OBExternalPartyType1Code	Delegate	Party that has delegated access.
OBExternalPartyType1Code	Joint	Party is a joint owner of the account.
OBExternalPartyType1Code	Sole	Party is a sole owner of the account.

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 UTC
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.uk",
	  "Address": {
		"AddressType": "Business",
		"StreetName": "Street",
		"BuildingNumber": "15",
		"PostCode": "NW1 1AB",
		"TownName": "London"		
      }
    }
  },
  "Links": {
    "Self": "https://api.examplebank.co.nz/open-banking-nz/v1.0/accounts/22289/party/"
  },
  "Meta": {
    "TotalPages": 1
  }
}

Authorised User