Change phone for Account Holder

Change Phone for Account Holder

The /changePhone endpoint allows personal customers to update the phone number associated with their account. This ensures contact information remains current for security verifications, notifications, and all account-related communications. The endpoint supports three request variants: a basic phone change, a phone change for an associated person (authorized user), and a secured phone change that requires OTP verification.

Endpoint

POST /changePhone

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 phone number due to switching carriers, getting a new phone, or correcting outdated contact details. For business customers updating a phone number on behalf of an authorized user (associated person), use the changeAssociatedPersonPhone variant by including the associatedPersonId field. When the platform requires step-up verification before allowing the change, use the secured variant by supplying oneTimeCode and secureOperationType.

Request Body

This endpoint accepts one of three request schemas depending on the scenario:

Variant 1 — Basic Phone Change (changephonerequest)

{
  "phone": "15551234567"
}

Variant 2 — Change Phone for Associated Person (changeassociatedpersonphonerequest)

Extends Variant 1. Use when updating the phone number of an authorized user linked to a business account.

{
  "phone": "15559876543",
  "associatedPersonId": "ap_8f3c2d1a4b7e9f06"
}

Variant 3 — Secured Phone Change (changephonesecuredrequest)

Extends Variant 1. Use when the platform requires OTP verification before completing the phone number change.

{
  "phone": "15552223333",
  "oneTimeCode": "847291",
  "secureOperationType": "ShortMessageCode"
}

Response

200 OK

A 200 status indicates the phone number was successfully updated. No response body is returned.

Error Codes

Common Mistakes

• Omitting the phone field — it is required in all three request variants.
• Providing an oneTimeCode that does not match the exactly 6-digit numeric pattern (^\d{6}$) when using the secured variant.
• Using an invalid or unsupported value for secureOperationType — only ShortMessageCode, TimeBasedCode, and LegacyTimeBasedCode are accepted.
• Sending associatedPersonId for a personal customer account — this field is only applicable for authorized users linked to business accounts.
• Using an expired or missing Bearer token; tokens expire after 10 minutes and must be refreshed before making this call.

Related Endpoints

• POST /api/auth/v2 — Obtain a Bearer token for authentication
• POST /api/auth/refresh — Refresh an expiring Bearer token
• POST /changeEmail — Update the email address associated with an account
• POST /changePassword — Update the password for an account holder

Example

Basic phone change:

curl -X POST https://api.banking.netevia.dev/changePhone \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "15551234567"
  }'

Secured phone change with OTP verification:

curl -X POST https://api.banking.netevia.dev/changePhone \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "15552223333",
    "oneTimeCode": "847291",
    "secureOperationType": "ShortMessageCode"
  }'

Change phone for an associated person:

curl -X POST https://api.banking.netevia.dev/changePhone \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "15559876543",
    "associatedPersonId": "ap_8f3c2d1a4b7e9f06"
  }'