# Partner API

###### tags: `HBL`

The documentation looks great and we really are looking forward to implementing its integration with DOAPI.

Our understanding is that with this Partner API, we can create Partner, associate relationships between Partners and supply addresses.

We understand that there will be other endpoints for (non exhaustive) working with:
- portfolios/accounts
- ebanking contracts
- more addresses/contacts (e.g., phone numbers, email addresses)
- documents (e.g., identification documents)

Note from the meeting:
> We will agree on how to send files to the API: we discussed (i) multipart or (ii) post data with metadata in the header or (iii) JSON with files encoded in Base64 or similar

---
The answer from HBL has been reformatted in quote for easier identification:
>SWE (HBL): yes there will be several endpoints:
>* DefaultPortfolio (as part of the Partner_API)
>* MoneyAccount (in specification)
>* MortgageAccount / Tranche / Pricing / Amortisation(in specification)
>* Mortgage (=FinancingPortfolio) (currently being specified)
>* InvestmentPortfolio (not yet planned)
>* EBankingContract (to be specified)
>* Identification / Recognition (to be specified)
>* ContactInformation (e.g. Phone / Mail ) (to be specified)
>* Documents (forArchive, like OpeningContract, FinancingDocuments...) (to be specified)

We agreed to setup meetings/workshop for:
- EbankingContract <- we have a challenge for the password
- Identification / Recognition <- we already have quite a few data that need to fit into this API
- Documents <- we have quite a few files with different formats (images, PDFs, videos, audio recordings)

## Jobs

There seem to be a job management API, which is not documented here.
Do you intend that we do some busy polling to get refreshed status, or will there be a kind of callback/push/webhook mechanism?

Note from meeting:
> The APIs that we are going to use should be synchronous, no need for the JobAPI that will be, as Futures/callbacks, for dealing with asynchronous calls

## Partners

- **consultantTeamName**: what is your expectation here? Should it be the person that validated manually the onboarding in doapi?

>SWE: ConsultantTeamName should be the relationship manager, not the person who did the manual onboarding. I think we should define a default consultant team for each Originator. We'll provide a configuration table where we can set a clientspecific default value for missing data (e.g. ServiceDesk as ConsultantTeamName for Neon).

Note from the meeting:
> This has to be decided by the Business, probably ARF/Service Desk

### Persons

Nationalities is placed at top level of partners rather than at person level. This way, if the couple is formed, let's say, by a Swiss and a binational US/Swiss, we will never know which one has the American nationality. Isn't it an issue?

Note from meeting:
> This should not really be an issue, it seemed from the discussion we had that the nationality at the partner level (when it's a joint account) is the aggregation of nationalities of the different partners

#### NaturalPerson
Here are a couple of general questions:
- **title**: shouldn't this be an enumerated field? If so, which values would be acceptable
>SWE: It's not an enumerated Field in Finstar, it's not title like "Herr" oder "Frau", in Finstar academic titles are meant e.g. Dr. Prof.; Magister (in AUT), Dr., Professor... ..since there are thousands of possibilities an enum would be very hard to maintain.
- **firstName, lastName**: max length are shorter than on DOAPI (255 vs 25 chars), where should we cut (spaces, hyphens, last char)?
>SWE: The length of the names in the API is exactly the same as in Finstar, we have length restrictions coming from the data model / data base which have to be taken into account.

Note from the meeting:
>There are four fields:
>1. firstname
>2. middlename (second name)
>3. lastname
>4. name continuation
> each field is 40 characters which should be good enough. We might need to magically split, but it should be doable to fit any "firstname lastname" into the four fields (we will anyway propose a split to the service center and a human will double check/confirm)

- **gender**: always a little bit awkward to ask for such an information, moreover if title is provided - we get this information during the identification, in CH, it's only male/female, in Germany (and probably other countries) it could also be "neutral" and probably also "X"

Note from the meeting:
> We joked on the fact that this should be an updatable field... ;-)
> This is the field on which the "salutation" (i.e., Herr, Frau) is computed.
- **countryOfBirth**: isn't nationalities preferable? (we currently don't get that information) - we get the nationality but not the countryOfBirth
>SWE: it's an optional field, so you don't have to send us any information regarding countryOfBirth
## Partner relations
- Is there a list of relation types?

- If a married couple registers, should we create 2 partners and then link them through partner relations or add both in the partner/persons field as both strategies seem doable?
>SWE: If they would like to have a joint account you have to register 3 partners:
>* Partner A
>* Partner B
>* Joint Account with relations to Partner A and B.
>The identification records are stored on Partner A and Partner B, the joint account does not need any...

# Details
There are some minor details/typos, please take these only as proposals:
- that allow -> that allows
- Partner and Partner Address Entities (instead of Entity)
- can upserted -> can upsert (meaing "update or insert")
- The called -> the caller (let's use caller and callee if needed)
- acceptet -> accepted
- Whether to include -> Whether or not to include
- Either no token or an invalid (e.g., token expired) token was received. -> Either no token or an invalid token was received (e.g., expired token).
- A valid OAuth Token was received, but access was denied. -> token instead of Token?
- consultantTeamName: wouldn't is sound better with "Advisor" instead of consultant?

# Use case: doapi "export file"
Taking as basis the JSON export of doapi - which is for single private person as of right now, here is a quick analysis of what's used and/or missing.

## Fields that doapi delivers and that fit into the current API
Partner (person):
- salutation (title) -> not needed in the API (title is Dr, Prof, etc)
- gender
- first_name
- last_name
- date_of_birth
- nationalities
- marital_status
- matrimonial_regime
- correspondence_language

Address:
- street
- house_number
- zip_code
- city
- country

## Fields that are needed by Partner API and are missing from doapi
- It seemed that for a private person, a nogaCode2008 was also required in the past (hard coded "95.00A Private Haushalte mit Hauspersonal"), is that still the case (it looks like it's only needed for legal person, which makes sense)?
>SWE: the value should be 970000 for a private household following the codes from 2008, 95.00A was the old logic...
- countryOfBirth - we get the nationalities during the data collection and at least one of them is confirmed during identification
>SWE: as mentioned above not mandatory

## Fields that doapi delivers and are not (yet) handled

### Related to the person
- place_of_birth (could contain information about country) -> identification
- place_of_origin (makes sense for Swiss people) -> identification
- email_address -> PtEmail
- mobile_phone_number -> PtPhone

Optional in DOAPI:
- private_phone_number -> PtPhone (optional)
- business_phone_number -> PtPhone (optional)
- profession -> PtProfile? (optional)
- income -> PtProfile? (optional)
- wealth -> PtProfile? (optional)
- employer_name -> PtProfile? (optional)
- other_banks -> PtProfile? (optional)
- emergency_contact -> PtProfile? (optional)

### Related to compliance
The following fields are True/False and depend on the product:
- beneficial_owner -> PtBase (Partner)
- swiss_fiscal_residency
- not_us_person
- fintech_agreement
- reporting_duty
- terms_and_conditions_confirmed
- no_relationship_country
- no_business_country
- execution_only
- risk_agreement
- risk_information_securities_trading
- no_paper_confirmation (probably deprecated)
- ebanking_confirmation (probably deprecated)
- non_dormant_intention (probably deprecated)
- ebanking_request (deprecated)
- card_request (deprecated)
- signature_confirmation (deprecated)

Note:
>In case beneficial_owner is False, we will provide a `Person` that is the beneficial owner, this is work-in-progress.

Additional note from the meeting:
> We could generate a PDF of the JSON to have all checkboxes information somewhere stored in Finstar

### Related to identification
- id_type
- id_number
- country
- issuing_date
- expiry_date
- first_name (could be sligthly different than during the data collection)
- last_name (could be sligthly different than during the data collection)
- date_of_birth
- place_of_birth - depends on the technology provider
- place_of_origin - depends on the technology provider
- scan_recto
- scan_verso
- signature_from_id_document
- photo
- protocol
- identification_employee_id
- residence_permit (work in progress)
- audio-transcript
- video-transcript
- utility-bill

### Other fields
- contract + signed contract (when applicable) -> signed contract only
- encrypted password (bcrypt) -> to be discussed when defining the ebanking contract API