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":["ec2a3be1-35a6-46e9-92cc-583388be5320","bc2c741a-d82a-4c05-9da9-5f9384c4b4aa"],"primary_account_uuids":["e5be056a-4ddc-41cb-ae02-af62a7fc412f","c9ae7dad-fd40-4230-bcf6-e06e8a68bb4c"],"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": [
    "ec2a3be1-35a6-46e9-92cc-583388be5320",
    "bc2c741a-d82a-4c05-9da9-5f9384c4b4aa"
  ],
  "primary_account_uuids": [
    "e5be056a-4ddc-41cb-ae02-af62a7fc412f",
    "c9ae7dad-fd40-4230-bcf6-e06e8a68bb4c"
  ],
  "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": "feb55e66-5cb9-4b9d-a698-4c1bba5d4dc5",
  "county": "Hampshire",
  "country": "United Kingdom",
  "accounts": {
    "name": "Gareth Thompson",
    "role": "client",
    "type": "client",
    "uuid": "c029bb4b-fe46-4578-974c-fb5300abff02",
    "email": "gareth@codepotato.co.uk",
    "last_name": "Thompson",
    "photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
    "created_at": "2025-06-26T11:37:11+01:00",
    "first_name": "Gareth",
    "updated_at": "2025-06-26T11:37:11+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-06-26T11:37:11+01:00",
  "updated_at": "2025-06-26T11:37:11+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": "c7e1aa42-4b3c-4747-9440-30ac73d9f59a",
    "email": "gareth@codepotato.co.uk",
    "last_name": "Thompson",
    "photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
    "created_at": "2025-06-26T11:37:11+01:00",
    "first_name": "Gareth",
    "updated_at": "2025-06-26T11:37:11+01:00",
    "external_references": "App\\Http\\Resources\\ExternalReferenceResource"
  },
  "residential_status": "homeowner",
  "residential_status_other": "homeowner"
}