Change PIN

POST/subscribers/{id}/change-pinOpen in the API playground →

Warning

Changing PIN requires verification of the current PIN first.

Request

Authorizationstringheaderrequired

Bearer olive_live_xxx or Bearer eyJ... (JWT)

Path Parameters

idstringpathrequired

Subscriber UUID (e.g., sub_abc123)

Body Parameters

current_pinstringbodyrequired

Current 4-digit PIN

new_pinstringbodyrequired

New 4-digit PIN

---

Response

successboolean

Whether change succeeded

messagestring

Result message

---

Examples

Request

cURL

curl -X POST "https://demo.api.vultlocal.com/api/v1/subscribers/sub_abc123/change-pin" \
  -H "Authorization: Bearer olive_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "current_pin": "1234",
    "new_pin": "5678"
  }'

Response

200 Success

{
  "success": true,
  "message": "PIN changed successfully"
}

401 Wrong PIN

{
  "success": false,
  "message": "Current PIN is incorrect",
  "attempts_remaining": 2
}

400 Invalid New PIN

{
  "success": false,
  "message": "New PIN must be 4 digits",
  "code": "INVALID_PIN_FORMAT"
}

---

PIN Rules

Format

• Exactly 4 digits
• Numbers only (0-9)
• No spaces or special characters

Security

• Cannot be same as current PIN
• Sequential patterns discouraged
• Simple patterns (1111) warned

---

Validation

Rule	Invalid Example	Reason
Length	123	Must be 4 digits
Numeric	12ab	Numbers only
Same as current	1234 → 1234	Must be different

---

Notifications

Info

A WhatsApp notification is sent to the subscriber when their PIN is changed.

---

Errors

Status	Code	Description
400	INVALID_PIN_FORMAT	PIN must be 4 digits
400	SAME_PIN	New PIN same as current
401	UNAUTHORIZED	Invalid or missing API key
401	WRONG_CURRENT_PIN	Current PIN incorrect
403	ACCOUNT_LOCKED	Too many failed attempts
404	NOT_FOUND	Subscriber not found
500	INTERNAL_ERROR	Server error

---

Related

Verify PIN

Verify a PIN without changing it