Repository: immersve/immersve-docs
Pull request #624: Add residential addresses endpoints to the API reference and update IC KYC
Author: login: pfellow
Labels: name: spoink
Created: 2025-03-10T00:04:17Z | Merged: 2025-03-12T19:54:41Z

1. Get Residential Addresses
2. Submit Residential Addresses
3. IC KYC Guide Update (more updates are coming with @forktrucka's PR https://github.com/immersve/immersve-docs/pull/622)

Ticket Link: https://www.notion.so/immersve/Update-the-docs-18b1d446ed8a80e4ac4fc967b7589812

<!-- See https://www.notion.so/immersve/Pull-Request-Checklist-72c856d319e24396aa82179e8894face (delete this comment before creating PR) -->



Diff:
diff --git a/imsv-docs-astro/src/content/docs/guides/kyc/immersve-conducted-kyc.mdoc b/imsv-docs-astro/src/content/docs/guides/kyc/immersve-conducted-kyc.mdoc
index 144c6e2e3c..64905c0005 100644
--- a/imsv-docs-astro/src/content/docs/guides/kyc/immersve-conducted-kyc.mdoc
+++ b/imsv-docs-astro/src/content/docs/guides/kyc/immersve-conducted-kyc.mdoc
@@ -110,6 +110,9 @@ If spending prerequisites is called with the `kycHiddenSteps` option but informa
 ---
  * <nobr>expected-spend</nobr>
  * The user's anticipated monthly spend. See "Supply Expected Spend Amount" section below.
+ ---
+ * <nobr>residential-address</nobr>
+ * The user's residential address. See "Supply Residential Address" section below.
 
  {% /table %}
 
@@ -151,7 +154,7 @@ curl -X PATCH "https://${imsv_api_host}/api/accounts/${cardholder_account_id}/co
   }'
 ```
 
-## Supply Expected Spend Amount (Optional)
+### Supply Expected Spend Amount (Optional)
 
 Regulations require that Immersve obtain information on the “nature and purpose”
 of the proposed business relationship between ourselves and the cardholder.
@@ -176,12 +179,80 @@ curl -X POST "https://${imsv_api_host}/api/accounts/${cardholder_account_id}/exp
   }'
 ```
 
+### Supply Residential Address (Optional)
+
+If you would like to supply the user's residential address ahead of time, you can do so by calling the
+{% link endpoint="submit-residential-addresses" /%} endpoint, before starting the KYC process.
+This will then allow the user to check and update the address as part of the Immersve Conducted KYC process
+(if `residential-address` step is not hidden).
+
+You can submit either a structured or an unstructured address. We recommend using a structured address
+whenever possible as correct parsing of an unstructured address is not guaranteed.
+
+{% list %}
+  {% listitem "ArrowRightCircle" %}
+    **Structured Address**
+
+    Organizes address details into predefined fields, making it easier to validate and process the data.
+
+    ```json
+    {
+      "streetNumber": "140",
+      "streetName": "Commonwealth Avenue",
+      "town": "Yarralumla",
+      "state": "ACT",
+      "postalCode": "2600",
+      "country": "AU"
+    }
+    ```
+    Partners are strongly encouraged to use this format whenever possible.
+
+  {% /listitem %}
+  {% listitem "ArrowRightCircle" %}
+    **Unstructured Address**
+
+    This format consolidates the address into a single text string in the `fullAddress` field
+
+    ```json
+    {
+      "fullAddress": "140 Commonwealth Ave, Yarralumla ACT 2600,
+      Australia",
+      "country": "AU"
+    }
+    ```
+
+    Immersve will attempt to structure a submitted unstructured address for addresses
+    in New Zealand and Australia.
+
+  {% /listitem %}
+{% /list %}
+
+{% endpointref name="submit-residential-addresses" /%}
+
+```bash
+curl -X POST "https://${imsv_api_host}/api/accounts/${cardholder_account_id}/residential-addresses" \
+  -H "Content-Type: application/json" \
+  -H "X-Api-Key: ${card_issuer_api_key}" \
+  -H "X-Api-Secret: ${card_issuer_api_secret}" \
+  -H "X-Account-Id: ${cardholder_account_id}" \
+  --data '[
+  {
+    "streetNumber": "140",
+    "streetName": "Commonwealth Avenue",
+    "town": "Yarralumla",
+    "state": "ACT",
+    "postalCode": "2600",
+    "country": "AU"
+  }
+]'
+```
 
 ### User goes through the KYC flow
 
 Upon being redirected to the Immersve KYC page, the user will go through the
-process that involves the collection of the user's address and the verification
-of their identity through document and biometry (facial scan) collection.
+process that involves the collection of the user's contact details, expected spend
+amount, residential address (if not hidden) and the verification of their identity
+through document and biometry (facial scan) collection.
 
 At the end of the process the user is presented with a screen indicating that their
 profile is under review. The user does not have to stay on the page to know
diff --git a/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/get-residential-addresses.yaml b/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/get-residential-addresses.yaml
new file mode 100644
index 0000000000..bcb85fcee5
--- /dev/null
+++ b/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/get-residential-addresses.yaml
@@ -0,0 +1,34 @@
+tags:
+  - kyc
+summary: Get Residential Addresses
+operationId: get-residential-addresses
+description: |
+  Retrieve previously submitted residential addresses of the cardholder.
+  :::note
+  This endpoint is for Immersve-conducted KYC only.
+  :::
+parameters:
+  - name: cardholderAccountId
+    in: path
+    description: ID of the cardholder account.
+    example: 65a7e8ef0d230d0a6bf755e07d39eb02
+    required: true
+    schema:
+      type: string
+responses:
+  "200":
+    content:
+      application/json:
+        schema:
+          $ref: "./models/residential-addresses-response.yaml"
+  "403":
+    description: |
+      Subject is not allowed to perform the action with the reason stated in the `errorCode`
+
+      **FORBIDDEN**
+      Resource does not exist or there are no sufficient permissions to perform the action.
+
+    content:
+      application/json:
+        schema:
+          $ref: "../../models/api-error-403.yaml"
diff --git a/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/residential-addresses-response.yaml b/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/residential-addresses-response.yaml
new file mode 100644
index 0000000000..bf44362694
--- /dev/null
+++ b/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/residential-addresses-response.yaml
@@ -0,0 +1,3 @@
+type: array
+items:
+  $ref: "./structured-address-response.yaml"
diff --git a/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/structured-address-request.yaml b/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/structured-address-request.yaml
new file mode 100644
index 0000000000..b43be1f79a
--- /dev/null
+++ b/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/structured-address-request.yaml
@@ -0,0 +1,40 @@
+type: object
+required:
+  - country
+properties:
+  unitNumber:
+    type: string
+    description: The unit number.
+    example: "1"
+  streetNumber:
+    type: string
+    description: Street number. Generally a number but can also be alphanumeric.
+    example: 3A
+  streetName:
+    type: string
+    description: Street name.
+    example: Victoria
+  town:
+    type: string
+    description: The town/village/suburb/city.
+    example: Auckland
+  suburb:
+    type: string
+    description: The suburb in the town/city. Only use this if you require a suburb AND a town/city, otherwise, just use the "town" parameter.
+    example: Epsom
+  state:
+    type: string
+    description: The state. Use local abbreviations such as VIC (Victoria) or TX (Texas).
+    example: AKL
+  region:
+    type: string
+    description: The county, province, or cantonment.
+    example: Auckland
+  postalCode:
+    type: string
+    description: Postal code.
+    example: "1050"
+  country:
+    type: string
+    description: The ISO 3166-2 Country code of the country the address is in.
+    example: NZ
diff --git a/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/structured-address-response.yaml b/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/structured-address-response.yaml
new file mode 100644
index 0000000000..c1dbc83e87
--- /dev/null
+++ b/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/structured-address-response.yaml
@@ -0,0 +1,42 @@
+type: object
+properties:
+  unitNumber:
+    type: string
+    description: The unit number.
+    example: "1"
+  streetNumber:
+    type: string
+    description: Street number. Generally a number but can also be alphanumeric.
+    example: 3A
+  streetName:
+    type: string
+    description: Street name.
+    example: Victoria Street
+  town:
+    type: string
+    description: The town/village/suburb/city.
+    example: Auckland
+  suburb:
+    type: string
+    description: The suburb in the town/city. Only use this if you require a suburb AND a town/city, otherwise, just use the "town" parameter.
+    example: Epsom
+  state:
+    type: string
+    description: The state. Use local abbreviations such as VIC (Victoria) or TX (Texas).
+    example: AKL
+  region:
+    type: string
+    description: The county, province, or cantonment.
+    example: Auckland
+  postalCode:
+    type: string
+    description: Postal code.
+    example: "1050"
+  country:
+    type: string
+    description: The ISO 3166-2 Country code of the country the address is in.
+    example: NZ
+  fullAddress:
+    type: string
+    description: The submitted unstructured address.
+    example: 1/3A Victoria Street, Epsom, Auckland 1050, New Zealand
diff --git a/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/unstructured-address-request.yaml b/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/unstructured-address-request.yaml
new file mode 100644
index 0000000000..88ea289fe7
--- /dev/null
+++ b/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/unstructured-address-request.yaml
@@ -0,0 +1,13 @@
+type: object
+required:
+  - fullAddress
+  - country
+properties:
+  fullAddress:
+    type: string
+    description: An address written as a single string.
+    example: 2/45 Laddier Road, Centurion, The Reeds, Auckland 0100, New Zealand
+  country:
+    type: string
+    description: The ISO 3166-2 Country code of the country the address is in.
+    example: NZ
diff --git a/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/submit-residential-addresses.yaml b/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/submit-residential-addresses.yaml
new file mode 100644
index 0000000000..153e06695e
--- /dev/null
+++ b/imsv-docs-docusaurus/openapi/endpoints/residential-addresses/submit-residential-addresses.yaml
@@ -0,0 +1,50 @@
+tags:
+  - kyc
+summary: Submit Residential Addresses
+operationId: submit-residential-addresses
+description: |
+  Submit the current residential address of the cardholder in either structured or unstructured format.
+  :::note
+  This endpoint is for Immersve-conducted KYC only.
+  :::
+
+parameters:
+  - name: cardholderAccountId
+    in: path
+    description: ID of the cardholder account.
+    example: 65a7e8ef0d230d0a6bf755e07d39eb02
+    required: true
+    schema:
+      type: string
+requestBody:
+  content:
+    application/json:
+      schema:
+        type: array
+        items:
+          anyOf:
+            - $ref: "./models/structured-address-request.yaml"
+              title: Structured address
+            - $ref: "./models/unstructured-address-request.yaml"
+              title: Unstructured address
+  required: true
+responses:
+  "200":
+    content:
+      application/json:
+        schema:
+          $ref: "./models/residential-addresses-response.yaml"
+  "403":
+    description: |
+      Subject is not allowed to perform the action with the reason stated in the `errorCode`
+
+      **FORBIDDEN**
+      Resource does not exist or there are no sufficient permissions to perform the action.
+
+      **KYC_ALREADY_PASSED**
+      Residential Addresses submission is not allowed after successful KYC checks (KYC profile is passed).
+
+    content:
+      application/json:
+        schema:
+          $ref: "../../models/api-error-403.yaml"
diff --git a/imsv-docs-docusaurus/openapi/immersve.yaml b/imsv-docs-docusaurus/openapi/immersve.yaml
index 681c442e24..5509623e5b 100644
--- a/imsv-docs-docusaurus/openapi/immersve.yaml
+++ b/imsv-docs-docusaurus/openapi/immersve.yaml
@@ -115,6 +115,11 @@ paths:
       $ref: "./endpoints/expected-spend-amount/get-expected-spend-amount.yaml"
     post:
       $ref: "./endpoints/expected-spend-amount/update-expected-spend-amount.yaml"
+  "/api/accounts/{cardholderId}/residential-addresses":
+    get:
+      $ref: "./endpoints/residential-addresses/get-residential-addresses.yaml"
+    post:
+      $ref: "./endpoints/residential-addresses/submit-residential-addresses.yaml"
   "/api/accounts/{partnerAccountId}/supported-regions":
     get:
       $ref: "./endpoints/supported-regions/get-supported-regions.yaml"


Reviews:
user: login: forktrucka
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-10T00:09:20Z
user: login: forktrucka
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-10T02:39:45Z
user: login: forktrucka
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-03-11T04:38:23Z
user: login: NicBathgate
body: Looking good!
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-03-12T19:44:12Z

Review comments:
diff_hunk: @@ -0,0 +1,40 @@
+type: object
+required:
+  - country
+properties:
+  unitNumber:
+    type: string
+    description: The unit number.
+    example: "1"
+  streetNumber:
+    type: string
+    description: Street number. Generally a number but can also be alphanumeric.
+    example: 3A
+  streetName:
+    type: string
+    description: Street name.
+    example: Victoria
+  town:
+    type: string
+    description: The town/village/suburb/city.
+    example: Auckland
+  suburb:
+    type: string
+    description: The suburb in the town/city. Only use this if you require a suburb AND a town/city, otherwise, just use the "town" parameter.
+    example: Epsom
+  state:
+    type: string
+    description: The state. Use local abbreviations such as VIC (Victoria) or TX (Texas).
+    example: AKL
+  region:
path: imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/structured-address-request.yaml
user: login: forktrucka
body: 🤔 hmmm.
created_at: 2025-03-10T00:09:19Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,40 @@
+type: object
+required:
+  - country
+properties:
+  unitNumber:
+    type: string
+    description: The unit number.
+    example: "1"
+  streetNumber:
+    type: string
+    description: Street number. Generally a number but can also be alphanumeric.
+    example: 3A
+  streetName:
+    type: string
+    description: Street name.
+    example: Victoria
+  town:
+    type: string
+    description: The town/village/suburb/city.
+    example: Auckland
+  suburb:
+    type: string
+    description: The suburb in the town/city. Only use this if you require a suburb AND a town/city, otherwise, just use the "town" parameter.
+    example: Epsom
+  state:
+    type: string
+    description: The state. Use local abbreviations such as VIC (Victoria) or TX (Texas).
+    example: AKL
+  region:
path: imsv-docs-docusaurus/openapi/endpoints/residential-addresses/models/structured-address-request.yaml
user: login: forktrucka
body: We are making this align with Partner Conducted. There is another piece of work to address this separately. We're worried about the effort and implication of rushing this out.
created_at: 2025-03-10T02:39:45Z
author_association: CONTRIBUTOR
diff_hunk: @@ -176,12 +179,86 @@ curl -X POST "https://${imsv_api_host}/api/accounts/${cardholder_account_id}/exp
   }'
 ```
 
+### Supply Residential Address (Optional)
+
+If you would like to supply the user's residential address ahead of time, you can do so by calling the
+{% link endpoint="submit-residential-addresses" /%} endpoint, before starting the KYC process.
+This will then allow the user to check and update the address as part of the Immersve Conducted KYC process
+(if `residential-address` step is not hidden).
+
+{% note %}
path: imsv-docs-astro/src/content/docs/guides/kyc/immersve-conducted-kyc.mdoc
user: login: forktrucka
body: This probably doesn't need to be a note, it can just be normal text
created_at: 2025-03-11T04:26:41Z
author_association: CONTRIBUTOR
diff_hunk: @@ -176,12 +179,86 @@ curl -X POST "https://${imsv_api_host}/api/accounts/${cardholder_account_id}/exp
   }'
 ```
 
+### Supply Residential Address (Optional)
+
+If you would like to supply the user's residential address ahead of time, you can do so by calling the
+{% link endpoint="submit-residential-addresses" /%} endpoint, before starting the KYC process.
+This will then allow the user to check and update the address as part of the Immersve Conducted KYC process
+(if `residential-address` step is not hidden).
+
+{% note %}
+You can submit either a structured or an unstructured address. We recommend using a structured address
+whenever possible as correct parsing of an unstructured address is not guaranteed.
+{% /note %}
+
+
+
+{% list %}
+  {% listitem "ArrowRightCircle" %}
+    **Structured Address**
+
+    Organizes address details into predefined fields, making it easier to validate and process the data.
+
+    ```json
+    {
+      "streetNumber": "140",
+      "streetName": "Commonwealth Avenue",
+      "town": "Yarralumla",
+      "state": "ACT",
+      "postalCode": "2600",
+      "country": "AU"
+    }
+    ```
+    Partners are strongly encouraged to use this format whenever possible.
+
+  {% /listitem %}
+  {% listitem "ArrowRightCircle" %}
+    **Unstructured Address**
+
+    This format consolidates the address into a single text string in the `fullAddress` field
+
+    ```json
+    {
+      "fullAddress": "140 Commonwealth Ave, Yarralumla ACT 2600,
+      Australia",
+      "country": "AU"
+    }
+    ```
+
+    {% warning %}
path: imsv-docs-astro/src/content/docs/guides/kyc/immersve-conducted-kyc.mdoc
user: login: forktrucka
body: Can just be content
created_at: 2025-03-11T04:30:21Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,52 @@
+tags:
+  - kyc
+summary: Submit Residential Addresses
+operationId: submit-residential-addresses
+description: |
+  :::note
+  This endpoint is for Immersve-conducted KYC only.
+  :::
+  Submit residential addresses for the cardholder. The request body should contain an array with the cardholder's current residential address either structured or unstructured.
path: imsv-docs-docusaurus/openapi/endpoints/residential-addresses/submit-residential-addresses.yaml
user: login: forktrucka
body: This could probably be simplified to something like

```text
Submit the current residential address of the cardholder in either structured or unstructured format.
```

A lot of the other info about us destructuring is in consequential to the consumer, a lot of the recommendations are already included in the guide.
created_at: 2025-03-11T04:36:00Z
author_association: CONTRIBUTOR

PR comments:
user: login: forktrucka
created_at: 2025-03-11T04:25:43Z
body: https://624-merge--jovial-scone-ec740d.netlify.app/
author_association: CONTRIBUTOR