Change Address

Change Address

The /changeAddress endpoint allows personal customers to update their residential or mailing address in the Netevia system. It supports three request variants: a basic address update, a security-code-verified update, and an update targeting an associated person (such as a primary authorized person or beneficial owner). Keeping address details accurate ensures that account communications and mailings are delivered correctly.

Endpoint

POST /changeAddress

Authentication

Bearer token required. Obtain via:

POST https://api.banking.netevia.dev/api/auth/v2

Include in header: Authorization: Bearer {token}
Token lifetime: 10 minutes. Refresh via POST /api/auth/refresh.

When to use

Use this endpoint when a personal customer needs to update their address due to relocation, a change in mailing preferences, or correction of outdated information. For updates that require additional verification (e.g., high-security contexts), supply the oneTimeCode and secureOperationType fields. To update the address of an associated person such as a beneficial owner, include the associatedPersonId field instead.

Request Body

This endpoint accepts one of three request variants (oneOf). All variants share the base address fields. Choose the variant that matches your use case.

Variant 1 — Basic Address Update (changeaddressrequest)

{
  "streetAddress": "742 Evergreen Terrace",
  "extendedAddress": "Apt 1",
  "postalCode": "62701",
  "city": "Springfield",
  "state": 14
}

Variant 2 — Secured Address Update (changeaddresssecuredrequest)

Extends Variant 1 with OTP verification fields. Include all base fields plus:

{
  "streetAddress": "742 Evergreen Terrace",
  "extendedAddress": "Apt 1",
  "postalCode": "62701",
  "city": "Springfield",
  "state": 14,
  "oneTimeCode": "483921",
  "secureOperationType": "ShortMessageCode"
}

Variant 3 — Associated Person Address Update (changeassociatedpersonaddressrequest)

Extends Variant 1 to update the address of a linked person (e.g., a primary authorized person or beneficial owner). Include all base fields plus:

{
  "streetAddress": "742 Evergreen Terrace",
  "postalCode": "62701",
  "city": "Springfield",
  "state": 14,
  "associatedPersonId": "ap-7f3c1e2a-84b0-4d29-a5f6-102938475610"
}

State Enum Values

The state field is an integer from 1 to 53 representing US states and territories. Values map sequentially (e.g., 1 = Alabama, 2 = Alaska, ... 51 = Wyoming, 52 = District of Columbia, 53 = Puerto Rico or other territory). Verify the exact mapping with your integration team or platform documentation.

Response

200 OK

A 200 response indicates the address was successfully updated. No response body fields are returned beyond the success status.

{}

Error Codes

Common Mistakes

• Sending postalCode with fewer or more than 5 digits — the pattern requires exactly ^\d{5}$.
• Sending streetAddress that does not begin with a number — the format must follow 123 Avenue Street style (digit-first).
• Using Variant 2 without having triggered an OTP flow first — oneTimeCode will be invalid or expired.
• Confusing associatedPersonId (Variant 3) with a customer or account ID — this field accepts only the ID of a linked person (authorized person or beneficial owner).
• Omitting secureOperationType when providing oneTimeCode — both fields are required together in Variant 2.

Related Endpoints

• POST /api/auth/v2 — Obtain a Bearer token for authentication
• POST /api/auth/refresh — Refresh an existing Bearer token

Example

Variant 1 — Basic address update:

curl -X POST https://api.banking.netevia.dev/changeAddress \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "streetAddress": "742 Evergreen Terrace",
    "extendedAddress": "Apt 1",
    "postalCode": "62701",
    "city": "Springfield",
    "state": 14
  }'

Variant 2 — Secured address update with OTP:

curl -X POST https://api.banking.netevia.dev/changeAddress \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "streetAddress": "742 Evergreen Terrace",
    "postalCode": "62701",
    "city": "Springfield",
    "state": 14,
    "oneTimeCode": "483921",
    "secureOperationType": "ShortMessageCode"
  }'

Variant 3 — Update address for an associated person:

curl -X POST https://api.banking.netevia.dev/changeAddress \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "streetAddress": "742 Evergreen Terrace",
    "postalCode": "62701",
    "city": "Springfield",
    "state": 14,
    "associatedPersonId": "ap-7f3c1e2a-84b0-4d29-a5f6-102938475610"
  }'