Skip to content
BC Government LogoAddress Change

Submit an address-change request

POST
/api/v1/address-change
curl --request POST \
  --url https://address-change-test.apps.gold.devops.gov.bc.ca/api/v1/address-change \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "idempotencyKey": "submit-7f3a", "effectiveDate": "2026-02-01", "isBillingAddressSame": true, "person": { "firstName": "Alex", "lastName": "Example", "dateOfBirth": "1990-04-12" }, "oldAddress": { "country": "Canada", "addressLineOne": "1234 Example Street", "locality": "Victoria", "region": "BC", "postalCode": "V8W 1A1" }, "newAddress": { "country": "Canada", "addressLineOne": "5678 Sample Avenue", "locality": "Victoria", "region": "BC", "postalCode": "V8W 1A1" }, "notificationIntent": { "notifyIcbc": true, "notifyMsp": true } }'

Accepts an address-change request for asynchronous delivery to the selected partners and returns a request identifier. Repeating a submission with the same idempotency key returns the original result.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

The address-change payload.

Media typeapplication/json
object
idempotencyKey
required
string
>= 1 characters <= 255 characters
effectiveDate
required
string
isBillingAddressSame
required
boolean
person
required
object
firstName
required
string
firstMiddleInitial
string
nullable
secondMiddleInitial
string
nullable
lastName
required
string
dateOfBirth
required
string
emailAddress
string
nullable
daytimePhone
string
nullable
driversLicenseNumber
string
nullable
heightCm
integer
nullable
weightKg
integer
nullable
securityKeyword
string
nullable
phn
string
nullable
oldAddress
required
object
country
required
string
addressLineOne
required
string
addressLineTwo
string
nullable
locality
required
string
region
required
string
postalCode
required
string
newAddress
required
object
country
required
string
addressLineOne
required
string
addressLineTwo
string
nullable
locality
required
string
region
required
string
postalCode
required
string
mailingAddress
object
country
required
string
addressLineOne
required
string
addressLineTwo
string
nullable
locality
required
string
region
required
string
postalCode
required
string
notificationIntent
required
object
notifyIcbc
required
boolean
notifyMsp
required
boolean
notifyBcsc
boolean

Example 

{
  "idempotencyKey": "submit-7f3a",
  "effectiveDate": "2026-02-01",
  "isBillingAddressSame": true,
  "person": {
    "firstName": "Alex",
    "lastName": "Example",
    "dateOfBirth": "1990-04-12"
  },
  "oldAddress": {
    "country": "Canada",
    "addressLineOne": "1234 Example Street",
    "locality": "Victoria",
    "region": "BC",
    "postalCode": "V8W 1A1"
  },
  "newAddress": {
    "country": "Canada",
    "addressLineOne": "5678 Sample Avenue",
    "locality": "Victoria",
    "region": "BC",
    "postalCode": "V8W 1A1"
  },
  "notificationIntent": {
    "notifyIcbc": true,
    "notifyMsp": true
  }
}

Responses

Section titled “Responses”

202

Section titled “202”

The request was accepted for processing.

Media typeapplication/json
object
requestId
required
string format: uuid

Example 

{
  "requestId": "7c825573-3df5-4e63-b376-ef7a4057369d"
}

400

Section titled “400”

The request is malformed or fails validation. The body is an RFC 9457 problem details object; errors lists the invalid fields without echoing their values.

Media typeapplication/json
object
type
required
string
title
required
string
status
required
integer
detail
required
string
errors
required
Array<object>
>= 1 items
object
type
required
string
code
required
string
message
required
string
location
required
string
Allowed values: body query header path cookie

Example 

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request body",
  "errors": [
    {
      "type": "validation",
      "code": "invalid_string",
      "message": "Invalid value at /person/dateOfBirth",
      "location": "body"
    }
  ]
}

401

Section titled “401”

A valid bearer access token is required.

Media typeapplication/json
object
statusCode
required
number
message
required
string
error
required
string

Example 

{
  "statusCode": 401,
  "message": "A bearer access token is required",
  "error": "Unauthorized"
}

403

Section titled “403”

The access token does not include the required scope.

Media typeapplication/json
object
statusCode
required
number
message
required
string
error
required
string

Example 

{
  "statusCode": 403,
  "message": "Missing address-change submission permission",
  "error": "Forbidden"
}

409

Section titled “409”

The request conflicts with the current state of a resource.

Media typeapplication/json
object
statusCode
required
number
message
required
string
error
required
string

Example 

{
  "statusCode": 409,
  "message": "An address-change request is already active",
  "error": "Conflict"
}

503

Section titled “503”

The service or a downstream partner is temporarily unavailable.

Media typeapplication/json
object
statusCode
required
number
message
required
string
error
required
string

Example 

{
  "statusCode": 503,
  "message": "Request could not be saved",
  "error": "Service Unavailable"
}