Create an address

POST /api/v2/addresses
Personal access token & O auth2

Headers

  • X-PLANNR-ACCOUNT-UUID string
application/json

Body Required

  • account_uuids array[string] Required

    The UUIDs of the accounts who should own the address. These must only be client accounts.

  • primary_account_uuids array[string]

    The UUIDs of the accounts who should have the address as their primary address.

  • name string Required

    The friendly name for the address.

  • is_primary boolean

    When provided and set to true, it will make the created address the primary address for all of the account UUIDs provided.

  • address_1 string Required

    The first line of the address.

  • address_2 string

    The second line of the address.

  • address_3 string

    The third line of the address.

  • address_4 string

    The fourth line of the address.

  • town_city string

    The town or city.

  • county string

    The county.

  • postcode string

    The postcode.

  • country string

    The country.

  • moved_in_month integer

    The month the client moved into this address.

  • moved_in_year integer

    The year the client moved into this address.

  • moved_out_month integer

    The month the client moved out of this address.

  • moved_out_year integer

    The year the client moved out of this address.

  • residential_status string

    The client's residential status when living at the address.

  • residential_status_other string

    The client's residential status if it is not provided in the residential_status options. Must only be provided if residential_status is other.

Responses

  • 201 application/json
    Hide response attributes Show response attributes object
    • uuid string

      The UUID of the resource.

    • created_at string

      The timestamp of when the resource was created.

    • updated_at string

      The timestamp of when the resource was updated.

    • name string

      The friendly name for the address.

    • address_1 string

      The first line of the address.

    • address_2 string

      The second line of the address.

    • address_3 string

      The third line of the address.

    • address_4 string

      The fourth line of the address.

    • town_city string

      The town or city.

    • county string

      The county.

    • postcode string

      The postcode.

    • country string

      The country.

    • accounts object

      The accounts who own the address. This may not be included when viewing all addresses. Refer to the documentation to include this field.

      Hide accounts attributes Show accounts attributes object
      • uuid string
      • created_at string
      • updated_at string
      • type string
      • role string
      • first_name string
      • last_name string
      • name string
      • email string
      • photo_url string
      • external_references string
    • primary_accounts object

      The accounts who own the address and have it as their primary address. This may not be included when viewing all addresses. Refer to the documentation to include this field.

      Hide primary_accounts attributes Show primary_accounts attributes object
      • uuid string
      • created_at string
      • updated_at string
      • type string
      • role string
      • first_name string
      • last_name string
      • name string
      • email string
      • photo_url string
      • external_references string
    • moved_in_month integer

      The month the client moved into this address.

    • moved_in_year integer

      The year the client moved into this address.

    • moved_out_month integer

      The month the client moved out of this address.

    • moved_out_year integer

      The year the client moved out of this address.

    • residential_status string

      The client's residential status when living at the address.

    • residential_status_other string

      The client's residential status if it is not provided in the residential_status options. Must only be provided if residential_status is other.

    • lived_in_months integer

      The number of months the client lived in the address.
POST /api/v2/addresses 
curl \
 --request POST 'https://api.plannrcrm.com/api/v2/addresses' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}" \
 --data '{"account_uuids":["de08bdf0-079a-4b0f-a659-ec10768c09d9","cdd4d90b-1371-4856-906d-0ebb6c397c41"],"primary_account_uuids":["e074c702-a455-4ebe-a85c-47808292b462","2aa7c3ab-a083-4aff-8a85-e32ef817d682"],"name":"Work Address","is_primary":true,"address_1":"Suite E, 5 The Briars","address_2":"Waterberry Drive","address_3":"The Innovative Centre","address_4":"Waterlooville","town_city":"Waterlooville","county":"Hampshire","postcode":"PO7 7YH","country":"United Kingdom","moved_in_month":6,"moved_in_year":2022,"moved_out_month":1,"moved_out_year":2024,"residential_status":"homeowner","residential_status_other":"Non-tenant occupier"}'
Request examples 
# Headers
X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}

# Payload
{
  "account_uuids": [
    "de08bdf0-079a-4b0f-a659-ec10768c09d9",
    "cdd4d90b-1371-4856-906d-0ebb6c397c41"
  ],
  "primary_account_uuids": [
    "e074c702-a455-4ebe-a85c-47808292b462",
    "2aa7c3ab-a083-4aff-8a85-e32ef817d682"
  ],
  "name": "Work Address",
  "is_primary": true,
  "address_1": "Suite E, 5 The Briars",
  "address_2": "Waterberry Drive",
  "address_3": "The Innovative Centre",
  "address_4": "Waterlooville",
  "town_city": "Waterlooville",
  "county": "Hampshire",
  "postcode": "PO7 7YH",
  "country": "United Kingdom",
  "moved_in_month": 6,
  "moved_in_year": 2022,
  "moved_out_month": 1,
  "moved_out_year": 2024,
  "residential_status": "homeowner",
  "residential_status_other": "Non-tenant occupier"
}
Response examples (201) 
{
  "name": "Work Address",
  "uuid": "725695c6-bf4d-46c6-8e8a-95ce61c69606",
  "county": "Hampshire",
  "country": "United Kingdom",
  "accounts": {
    "name": "Gareth Thompson",
    "role": "client",
    "type": "client",
    "uuid": "994baa9c-43b6-4595-9339-a164489c3bfc",
    "email": "gareth@codepotato.co.uk",
    "last_name": "Thompson",
    "photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
    "created_at": "2025-08-07T13:41:47+01:00",
    "first_name": "Gareth",
    "updated_at": "2025-08-07T13:41:47+01:00",
    "external_references": "App\\Http\\Resources\\ExternalReferenceResource"
  },
  "postcode": "PO7 7YH",
  "address_1": "Suite E, 5 The Briars",
  "address_2": "Waterberry Drive",
  "address_3": "The Innovative Centre",
  "address_4": "Waterlooville",
  "town_city": "Waterlooville",
  "created_at": "2025-08-07T13:41:47+01:00",
  "updated_at": "2025-08-07T13:41:47+01:00",
  "moved_in_year": 2022,
  "moved_in_month": 6,
  "moved_out_year": 2024,
  "lived_in_months": 19,
  "moved_out_month": 1,
  "primary_accounts": {
    "name": "Gareth Thompson",
    "role": "client",
    "type": "client",
    "uuid": "ba2160fb-3731-4653-aea0-faaadaccfed3",
    "email": "gareth@codepotato.co.uk",
    "last_name": "Thompson",
    "photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
    "created_at": "2025-08-07T13:41:47+01:00",
    "first_name": "Gareth",
    "updated_at": "2025-08-07T13:41:47+01:00",
    "external_references": "App\\Http\\Resources\\ExternalReferenceResource"
  },
  "residential_status": "homeowner",
  "residential_status_other": "homeowner"
}