Submit Residential Addresses

post/api/accounts/{cardholderAccountId}/residential-addresses

Submit the current residential address of the cardholder in either structured or unstructured format. In some regions, unstructured addresses are not allowed. Refer to the Get Supported Regions endpoint to check whether unstructured addresses are allowed for a region.

This endpoint is for Immersve-conducted KYC only.

Request

Path Parameters

cardholderAccountIdstringrequired
ID of the cardholder account.

Body application/json

Items

Any of

unitNumberstring
The unit number.
streetNumberstring
Street number. Generally a number but can also be alphanumeric.
streetNamestring
Street name.
townstring
The town/village/suburb/city.
suburbstring
The suburb in the town/city. Only use this if you require a suburb AND a town/city, otherwise, just use the "town" parameter.
statestring
The state. Use local abbreviations such as VIC (Victoria) or TX (Texas).
regionstring
The county, province, or cantonment.
postalCodestring
Postal code.
countrystringrequired
The ISO 3166-2 Country code of the country the address is in.

fullAddressstringrequired
An address written as a single string.
countrystringrequired
The ISO 3166-2 Country code of the country the address is in.

Response

Successful operation.

Body application/json

Items

unitNumberstring
The unit number.
streetNumberstring
Street number. Generally a number but can also be alphanumeric.
streetNamestring
Street name.
townstring
The town/village/suburb/city.
suburbstring
The suburb in the town/city. Only use this if you require a suburb AND a town/city, otherwise, just use the "town" parameter.
statestring
The state. Use local abbreviations such as VIC (Victoria) or TX (Texas).
regionstring
The county, province, or cantonment.
postalCodestring
Postal code.
countrystring
The ISO 3166-2 Country code of the country the address is in.
fullAddressstring
The submitted unstructured address.

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).

Body application/json

statusCodeintegerrequired
statusNamestringrequired
errorCodestringrequired
reasonstring

Example

Example Request

ServerAuthentication

curl 'https://api.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "unitNumber": "1",
    "streetNumber": "3A",
    "streetName": "Victoria",
    "town": "Auckland",
    "suburb": "Epsom",
    "state": "AKL",
    "region": "Auckland",
    "postalCode": "1050",
    "country": "NZ"
  }
]'

curl 'https://api.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "fullAddress": "2/45 Laddier Road, Centurion, The Reeds, Auckland 0100, New Zealand",
    "country": "NZ"
  }
]'

curl 'https://api.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "unitNumber": "1",
    "streetNumber": "3A",
    "streetName": "Victoria",
    "town": "Auckland",
    "suburb": "Epsom",
    "state": "AKL",
    "region": "Auckland",
    "postalCode": "1050",
    "country": "NZ"
  }
]'

curl 'https://api.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "fullAddress": "2/45 Laddier Road, Centurion, The Reeds, Auckland 0100, New Zealand",
    "country": "NZ"
  }
]'

curl 'https://api.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "unitNumber": "1",
    "streetNumber": "3A",
    "streetName": "Victoria",
    "town": "Auckland",
    "suburb": "Epsom",
    "state": "AKL",
    "region": "Auckland",
    "postalCode": "1050",
    "country": "NZ"
  }
]'

curl 'https://api.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "fullAddress": "2/45 Laddier Road, Centurion, The Reeds, Auckland 0100, New Zealand",
    "country": "NZ"
  }
]'

curl 'https://api.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "unitNumber": "1",
    "streetNumber": "3A",
    "streetName": "Victoria",
    "town": "Auckland",
    "suburb": "Epsom",
    "state": "AKL",
    "region": "Auckland",
    "postalCode": "1050",
    "country": "NZ"
  }
]'

curl 'https://api.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "fullAddress": "2/45 Laddier Road, Centurion, The Reeds, Auckland 0100, New Zealand",
    "country": "NZ"
  }
]'

curl 'https://test.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "unitNumber": "1",
    "streetNumber": "3A",
    "streetName": "Victoria",
    "town": "Auckland",
    "suburb": "Epsom",
    "state": "AKL",
    "region": "Auckland",
    "postalCode": "1050",
    "country": "NZ"
  }
]'

curl 'https://test.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "fullAddress": "2/45 Laddier Road, Centurion, The Reeds, Auckland 0100, New Zealand",
    "country": "NZ"
  }
]'

curl 'https://test.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "unitNumber": "1",
    "streetNumber": "3A",
    "streetName": "Victoria",
    "town": "Auckland",
    "suburb": "Epsom",
    "state": "AKL",
    "region": "Auckland",
    "postalCode": "1050",
    "country": "NZ"
  }
]'

curl 'https://test.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'Authorization: Bearer <access-token>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "fullAddress": "2/45 Laddier Road, Centurion, The Reeds, Auckland 0100, New Zealand",
    "country": "NZ"
  }
]'

curl 'https://test.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "unitNumber": "1",
    "streetNumber": "3A",
    "streetName": "Victoria",
    "town": "Auckland",
    "suburb": "Epsom",
    "state": "AKL",
    "region": "Auckland",
    "postalCode": "1050",
    "country": "NZ"
  }
]'

curl 'https://test.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "fullAddress": "2/45 Laddier Road, Centurion, The Reeds, Auckland 0100, New Zealand",
    "country": "NZ"
  }
]'

curl 'https://test.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "unitNumber": "1",
    "streetNumber": "3A",
    "streetName": "Victoria",
    "town": "Auckland",
    "suburb": "Epsom",
    "state": "AKL",
    "region": "Auckland",
    "postalCode": "1050",
    "country": "NZ"
  }
]'

curl 'https://test.immersve.com/api/accounts/{cardholderAccountId}/residential-addresses' \
  --request POST \
  --header 'X-Api-Key: <api-key>' \
  --header 'X-Api-Secret: <api-secret>' \
  --header 'X-Account-Id: <target-account>' \
  --header 'Content-Type: application/json' \
  --data '[
  {
    "fullAddress": "2/45 Laddier Road, Centurion, The Reeds, Auckland 0100, New Zealand",
    "country": "NZ"
  }
]'

Example Response

[
  {
    "unitNumber": "1",
    "streetNumber": "3A",
    "streetName": "Victoria Street",
    "town": "Auckland",
    "suburb": "Epsom",
    "state": "AKL",
    "region": "Auckland",
    "postalCode": "1050",
    "country": "NZ",
    "fullAddress": "1/3A Victoria Street, Epsom, Auckland 1050, New Zealand"
  }
]

{
  "statusCode": 403,
  "statusName": "Forbidden",
  "errorCode": "FORBIDDEN",
  "reason": "Unauthorized"
}