Party v3.0.1

Version Control

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.

Endpoints

Resource

Endpoint

Mandatory?

Scope

Grant Type

Idempotency Key

Parameters

Request Object

Response Object

Resource

Endpoint

Mandatory?

Scope

Grant Type

Idempotency Key

Parameters

Request Object

Response Object

party

GET /accounts/{AccountId}/party

Mandatory

accounts

Redirect Flow; or

Decoupled Flow

No





OBReadParty1

party

GET /party

Mandatory

accounts

Redirect Flow; or

Decoupled Flow

No





OBReadParty1

GET /accounts/{AccountId}/party

The API endpoint allows a Third Party to retrieve details on the account owner 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 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.

  • The Third Party must have an access token issued by the API Provider using an authorization flow (either redirect flow or decoupled flow). 

GET /party

The API endpoint allows a Third Party to retrieve details on the user that has authorised the account-access-consent 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

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 ReadPartyAuthUser permission is required to access GET /party. The resource response payload does not differ depending on the permissions granted.

Data Dictionary

Name

Occurrence

XPath

EnhancedDefinition

Class

Codes

Pattern

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.

Max128Text





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}\s?[0-9]{1,14}(\s[0-9]{1,13})?$

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}\s?[0-9]{1,14}(\s[0-9]{1,13})?$

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 

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

Retrieving the account owner for a specific account.

Request

Get Party Request

GET /accounts/22289/party HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-auth-date: 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": "1024", "TownName": "Auckland", "Country": "NZ" } } }, "Links": { "Self": "https://api.examplebank.co.nz/open-banking-nz/v2.1/accounts/22289/party" }, "Meta": { "TotalPages": 1 } }

Authorised User

Retrieving the authorised user.

Request

Get Party Request

GET /party HTTP/1.1 Authorization: Bearer Az90SAOJklae x-fapi-auth-date: 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