Update an Employment | PlannrCRM API documentation

Update an Employment Run in API Explorer

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL


        
          
            https://apidocs.plannrcrm.com/mcp

Standard setup for AI tools providing an mcp.json file

      
          mcp.json

"PlannrCRM MCP server": {
  "url": "https://apidocs.plannrcrm.com/mcp"
}

PUT /api/v2/employments/{uuid}

Personal access token & O auth2

Update an existing Employment record

Headers

X-PLANNR-ACCOUNT-UUID string

Path parameters

uuid string Required

application/json

Body

accountant_company_name string | null

The name of the accountant company.

Maximum length is 255.
accountant_email string | null

The email of the accountant.

Maximum length is 255.
accountant_telephone_number string | null

The telephone number of the accountant.
accountant_address string | null

The address of the accountant.

Maximum length is 255.
business_name string | null

The name of the business.

Maximum length is 255.
business_value integer | null

The value of the business in pennies.
business_year_end string | null

The year end of the business.

Maximum length is 255.
directors string | null

The directors of the business.

Maximum length is 255.
employer string | null

The name of the employer/business.

Maximum length is 255.
email_address string | null

The email address of the employer. Will be added as a contact detail.

Maximum length is 255.
ended_at string(date)

An optional end date of the employment.
is_business_owner boolean

Denotes if the employment owner is the business owner.
job_title string | null

Job title if no suitable occupation code is found.

Maximum length is 255.
last_salary_increase string(date) | null

The date of the last salary increase.
occupation_code string | null

The Origo occupation code for the given employment. You can use the /api/v1/static/occupations endpoint to get a list of occupations.
percentage_of_business_owned integer | null

The percentage of the business owned.

Minimum value is 0, maximum value is 100.
phone_number string | null

The phone number of the employer. In E.164 format. Will be added as a contact detail.
primary boolean

Make this employment the primary employment. Will make all other employments no longer primary.
profit integer | null

The profit of the business in pennies.

Minimum value is 0.
shareholding_in_business number(float) | null

The shareholding in the business in percentage.

Minimum value is 0.0, maximum value is 100.0.
started_at string(date)

An optional start date of the employment.
status string Required

The employment status for the given employment.

Value Description

employed Employed

self_employed Self Employed

student Student

unemployed Unemployed

house_person House Person

retired Retired

other Other

Values are employed, self_employed, student, unemployed, house_person, retired, or other.
turnover_history array[object] | null

An array of turnover history items.
Hide turnover_history attributes Show turnover_history attributes object
- year string(date) Required
  
  The year of the turnover entry.
- value integer Required
  
  The turnover value in pennies for the given year.
  
  Minimum value is 0.
address object
Hide address attributes Show address attributes object
- name string
  
  Name of the address
- address_1 string
  
  First line of the address
- address_2 string
  
  Second line of the address
- address_3 string
  
  Third line of the address
- address_4 string
  
  Fourth line of the address
- town_city string
  
  Town/City
- county string
  
  County
- postcode string
  
  Postcode
- country string
  
  Country
- move_in_date string
  
  Move in date
- 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.
  
  Value Description
  
  homeowner Homeowner
  
  renting Renting
  
  living_with_parents Living With Parents
  
  other Other
  
  Values are homeowner, renting, living_with_parents, or other.
- 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.

Value	Description
employed	Employed
self_employed	Self Employed
student	Student
unemployed	Unemployed
house_person	House Person
retired	Retired
other	Other

Value	Description
homeowner	Homeowner
renting	Renting
living_with_parents	Living With Parents
other	Other

Responses

200 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.
- status string
  
  The employment status. Available values: employed, self_employed, student, unemployed, house_person, retired and other
- primary boolean
  
  Denotes if the employment is the primary employment for the account associated.
- occupation string
  
  The occupation name found from the occupation code provided.
- occupation_code string
  
  The Origo occupation code.
- job_title string
  
  Job title if not suitable occupation code is found.
- employer string
  
  The name of the employer.
- started_at string
  
  The employment start date.
- ended_at string
  
  The employment end date if provided.
- is_business_owner boolean
  
  Denotes if the account is the business owner.
- percentage_of_business_shared integer
  
  The percentage of business shared.
- address object
  
  The address of the employer.
  
  Hide address attributes Show address attributes object
  
  uuid string
  
  created_at string
  
  updated_at string
  
  name string
  
  address_1 string
  
  address_2 string
  
  address_3 string
  
  address_4 string
  
  town_city string
  
  county string
  
  postcode string
  
  country string
  
  move_in_date string
  
  accounts string
- phone_number object
  
  The phone number of the employer.
  
  Hide phone_number attributes Show phone_number attributes object
  
  uuid string
  
  created_at string
  
  updated_at string
  
  type string
  
  name string
  
  value string
  
  phone_number_meta object
  
  Hide phone_number_meta attributes Show phone_number_meta attributes object
  
  country string
  
  formatted string
  
  accounts string
- email_address object
  
  The email address of the employer.
  
  Hide email_address attributes Show email_address attributes object
  
  uuid string
  
  created_at string
  
  updated_at string
  
  type string
  
  name string
  
  value string
  
  phone_number_meta object
  
  Hide phone_number_meta attributes Show phone_number_meta attributes object
  
  country string
  
  formatted string
  
  accounts string
- shared_owner_type string
  
  Denotes if the employment is shared across the client or belongs to one of the owners of the client. (Only applicable for joint/business/trust clients)
- shared_owner object
  
  The owner of the employment. Only provided if the shared_owner_type is "individual".
  
  Hide shared_owner attributes Show shared_owner 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
  
  firm string
  
  primary_phone_number string
  
  primary_email string
  
  current_time_entry string
  
  assigned_adviser string
  
  assigned_administrator string
  
  assigned_paraplanner string
  
  introduced_by string
  
  business_unit string
  
  groups string
  
  tags string
  
  owners string
  
  first_contact_date string
  
  next_review_date string
  
  previous_review_date string
  
  anniversary_review_date string
  
  terms_of_business_at string
  
  client_agreement_at string
  
  with_login boolean
  
  has_joint_account boolean
  
  can_be_deleted string
  
  joint_account_circle string
  
  circles string
  
  ownership_percentage integer
  
  inactive_at string
  
  last_interaction_at string
  
  referral_code string
  
  permissions object
  
  Hide permissions attributes Show permissions attributes object
  
  firm:read array[string]
  
  network:read array[string]
  
  custom_fields string
  
  external_references string
- last_salary_increase string
  
  The date of the last salary increase.
- business_name string
  
  The name of the business.
- business_year_end string
  
  The year end of the business.
- business_value object
  
  The value of the business.
  
  Hide business_value attributes Show business_value attributes object
  
  amount object
  
  Hide amount attributes Show amount attributes object
  
  example string
  
  description string
  
  formatted object
  
  Hide formatted attributes Show formatted attributes object
  
  example string
  
  description string
  
  currency object
  
  Hide currency attributes Show currency attributes object
  
  example string
  
  description string
- directors string
  
  The directors of the business.
- shareholding_in_business object
  
  The shareholding in the business.
  
  Hide shareholding_in_business attributes Show shareholding_in_business attributes object
  
  amount object
  
  Hide amount attributes Show amount attributes object
  
  example string
  
  description string
  
  formatted object
  
  Hide formatted attributes Show formatted attributes object
  
  example string
  
  description string
  
  currency object
  
  Hide currency attributes Show currency attributes object
  
  example string
  
  description string
- profit object
  
  The profit of the business.
  
  Hide profit attributes Show profit attributes object
  
  amount object
  
  Hide amount attributes Show amount attributes object
  
  example string
  
  description string
  
  formatted object
  
  Hide formatted attributes Show formatted attributes object
  
  example string
  
  description string
  
  currency object
  
  Hide currency attributes Show currency attributes object
  
  example string
  
  description string
- accountant_company_name string
  
  The name of the accountant.
- accountant_email string
  
  The email of the accountant.
- accountant_telephone_number string
  
  The telephone number of the accountant.
- accountant_address string
  
  The address of the accountant.
- turnover_history object
  
  The turnover history of the income.
  
  Hide turnover_history attributes Show turnover_history attributes object
  
  year integer
  
  value object
  
  Hide value attributes Show value attributes object
  
  amount object
  
  Hide amount attributes Show amount attributes object
  
  example string
  
  description string
  
  formatted object
  
  Hide formatted attributes Show formatted attributes object
  
  example string
  
  description string
  
  currency object
  
  Hide currency attributes Show currency attributes object
  
  example string
  
  description string
- income object
  
  Incomes that have been linked to thi employment.
  
  Hide income attributes Show income attributes object
  
  uuid string
  
  created_at string
  
  updated_at string
  
  name string
  
  type string
  
  type_other string
  
  amount object
  
  Hide amount attributes Show amount attributes object
  
  amount object
  
  Hide amount attributes Show amount attributes object
  
  example string
  
  description string
  
  formatted object
  
  Hide formatted attributes Show formatted attributes object
  
  example string
  
  description string
  
  currency object
  
  Hide currency attributes Show currency attributes object
  
  example string
  
  description string
  
  amount_type string
  
  start_date string
  
  end_date string
  
  frequency string
  
  is_taxable boolean
  
  shared_owner_type string
  
  shared_owner string
  
  employment string
  
  account string
- account object
  
  The account for this employment.
  
  Hide account attributes Show account 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

PUT /api/v2/employments/{uuid}

curl \
 --request PUT 'https://api.plannrcrm.com/api/v2/employments/6ff8f7f6-1eb3-3525-be4a-3932c805afed' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}" \
 --data '{"accountant_company_name":"My Company","accountant_email":"accountant@email.com","accountant_telephone_number":"0123456789","accountant_address":"1 My Street, My Town, My Country","business_name":"My Business","business_value":5000000,"business_year_end":"2019-01-01","directors":"John Doe","employer":"Plannr Technologies Ltd","email_address":"gareth@plannrcrm.com","ended_at":"2022-06-09","is_business_owner":true,"job_title":"Senior Developer","last_salary_increase":"2019-01-01","occupation_code":"FAC02774","percentage_of_business_owned":50,"phone_number":"+443330509960","primary":true,"profit":5000000,"shareholding_in_business":50.5,"started_at":"2021-06-09","status":"employed","turnover_history":[{"year":"2020","value":1000000}],"address":{"name":"Work Address","address_1":"Suite E","address_2":"5 The Briars","address_3":"Waterberry Drive","address_4":"The Innovative Centre","town_city":"Waterlooville","county":"Hampshire","postcode":"PO7 7YH","country":"United Kingdom","move_in_date":"2024-06-20","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
{
  "accountant_company_name": "My Company",
  "accountant_email": "accountant@email.com",
  "accountant_telephone_number": "0123456789",
  "accountant_address": "1 My Street, My Town, My Country",
  "business_name": "My Business",
  "business_value": 5000000,
  "business_year_end": "2019-01-01",
  "directors": "John Doe",
  "employer": "Plannr Technologies Ltd",
  "email_address": "gareth@plannrcrm.com",
  "ended_at": "2022-06-09",
  "is_business_owner": true,
  "job_title": "Senior Developer",
  "last_salary_increase": "2019-01-01",
  "occupation_code": "FAC02774",
  "percentage_of_business_owned": 50,
  "phone_number": "+443330509960",
  "primary": true,
  "profit": 5000000,
  "shareholding_in_business": 50.5,
  "started_at": "2021-06-09",
  "status": "employed",
  "turnover_history": [
    {
      "year": "2020",
      "value": 1000000
    }
  ],
  "address": {
    "name": "Work Address",
    "address_1": "Suite E",
    "address_2": "5 The Briars",
    "address_3": "Waterberry Drive",
    "address_4": "The Innovative Centre",
    "town_city": "Waterlooville",
    "county": "Hampshire",
    "postcode": "PO7 7YH",
    "country": "United Kingdom",
    "move_in_date": "2024-06-20",
    "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 (200)

{
  "uuid": "f0500cd3-484b-401e-9868-4fd360111f4a",
  "created_at": "2026-06-09T14:10:15+01:00",
  "updated_at": "2026-06-09T14:10:15+01:00",
  "status": "employed",
  "primary": true,
  "occupation": "Financial Adviser",
  "occupation_code": "FAC02774",
  "job_title": "Senior financial adviser",
  "employer": "Plannr Technologies Ltd",
  "started_at": "2021-06-09T14:10:15+01:00",
  "ended_at": "2022-06-09T14:10:15+01:00",
  "is_business_owner": true,
  "percentage_of_business_shared": 50,
  "address": {
    "uuid": "4dc908b2-9c6a-43a1-9c29-b9ba7665d83a",
    "created_at": "2026-06-09T14:10:15+01:00",
    "updated_at": "2026-06-09T14:10:15+01:00",
    "name": "Work Address",
    "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",
    "move_in_date": "2025-06-09",
    "accounts": "App\\Http\\Resources\\AccountResource"
  },
  "phone_number": {
    "uuid": "3433c8df-5f4b-470a-8cd2-547c5bf74369",
    "created_at": "2026-06-09T14:10:15+01:00",
    "updated_at": "2026-06-09T14:10:15+01:00",
    "type": "phone_number",
    "name": "Work number",
    "value": "+443330903630",
    "phone_number_meta": {
      "country": "GB",
      "formatted": "0333 090 3630"
    },
    "accounts": "App\\Http\\Resources\\AccountResource"
  },
  "email_address": {
    "uuid": "07690906-c73e-45d0-b364-1f7cc5cdd5b3",
    "created_at": "2026-06-09T14:10:15+01:00",
    "updated_at": "2026-06-09T14:10:15+01:00",
    "type": "phone_number",
    "name": "Work number",
    "value": "+443330903630",
    "phone_number_meta": {
      "country": "GB",
      "formatted": "0333 090 3630"
    },
    "accounts": "App\\Http\\Resources\\AccountResource"
  },
  "shared_owner_type": "individual",
  "shared_owner": {
    "uuid": "7dd7c422-f803-4f82-b7d6-9b88a3a7c55f",
    "created_at": "2026-06-09T14:10:15+01:00",
    "updated_at": "2026-06-09T14:10:15+01:00",
    "type": "client",
    "role": "client",
    "first_name": "Gareth",
    "last_name": "Thompson",
    "name": "Gareth Thompson",
    "email": "gareth@codepotato.co.uk",
    "photo_url": "https://eu.ui-avatars.com/api/?name=gareth+thompson",
    "firm": "App\\Http\\Resources\\FirmResource",
    "primary_phone_number": "App\\Http\\Resources\\ContactDetailResource",
    "primary_email": "App\\Http\\Resources\\ContactDetailResource",
    "current_time_entry": "App\\Http\\Resources\\TimeEntryResource",
    "assigned_adviser": "App\\Http\\Resources\\AccountResource",
    "assigned_administrator": "App\\Http\\Resources\\AccountResource",
    "assigned_paraplanner": "App\\Http\\Resources\\AccountResource",
    "introduced_by": "App\\Http\\Resources\\AccountResource",
    "business_unit": "App\\Http\\Resources\\BusinessUnitResource",
    "groups": "App\\Http\\Resources\\GroupResource",
    "tags": "App\\Http\\Resources\\TagResource",
    "owners": "App\\Http\\Resources\\AccountResource",
    "first_contact_date": "2026-06-09T14:10:15+01:00",
    "next_review_date": "2026-06-09T14:10:15+01:00",
    "previous_review_date": "2026-06-09T14:10:15+01:00",
    "anniversary_review_date": "2026-06-09T14:10:15+01:00",
    "terms_of_business_at": "2026-06-09T14:10:15+01:00",
    "client_agreement_at": "2026-06-09T14:10:15+01:00",
    "with_login": true,
    "has_joint_account": true,
    "can_be_deleted": "false",
    "joint_account_circle": "App\\Http\\Resources\\CircleResource",
    "circles": "App\\Http\\Resources\\CircleResource",
    "ownership_percentage": 100,
    "inactive_at": "2026-06-09",
    "last_interaction_at": "2026-06-09 14:10:15",
    "referral_code": "ABC12345",
    "permissions": {
      "firm:read": [
        "firm"
      ],
      "network:read": [
        "network:uuid"
      ]
    },
    "custom_fields": "App\\Http\\Resources\\CustomFieldValueResource",
    "external_references": "App\\Http\\Resources\\ExternalReferenceResource"
  },
  "last_salary_increase": "2019-01-01",
  "business_name": "My Business",
  "business_year_end": "2020-12-31",
  "business_value": {
    "amount": {
      "example": "4000",
      "description": "Money amount at their lowest denominator (for example: pennies)"
    },
    "formatted": {
      "example": "£40.00",
      "description": "Money amount formatted with currency"
    },
    "currency": {
      "example": "GBP",
      "description": "Currency of the money"
    }
  },
  "directors": "Susan F. Lancaster",
  "shareholding_in_business": {
    "amount": {
      "example": "4000",
      "description": "Money amount at their lowest denominator (for example: pennies)"
    },
    "formatted": {
      "example": "£40.00",
      "description": "Money amount formatted with currency"
    },
    "currency": {
      "example": "GBP",
      "description": "Currency of the money"
    }
  },
  "profit": {
    "amount": {
      "example": "4000",
      "description": "Money amount at their lowest denominator (for example: pennies)"
    },
    "formatted": {
      "example": "£40.00",
      "description": "Money amount formatted with currency"
    },
    "currency": {
      "example": "GBP",
      "description": "Currency of the money"
    }
  },
  "accountant_company_name": "My Accountant",
  "accountant_email": "accountant@email.com",
  "accountant_telephone_number": "+441234567890",
  "accountant_address": "23 Chollerton, Hexham, Northumberland, NE46 4TF",
  "turnover_history": {
    "year": 2020,
    "value": {
      "amount": {
        "example": "4000",
        "description": "Money amount at their lowest denominator (for example: pennies)"
      },
      "formatted": {
        "example": "£40.00",
        "description": "Money amount formatted with currency"
      },
      "currency": {
        "example": "GBP",
        "description": "Currency of the money"
      }
    }
  },
  "income": {
    "uuid": "4c9a48e5-2afb-43fb-a383-017d96481ffc",
    "created_at": "2026-06-09T14:10:15+01:00",
    "updated_at": "2026-06-09T14:10:15+01:00",
    "name": "My Salary",
    "type": "salary",
    "type_other": "Other income type",
    "amount": {
      "amount": {
        "example": "4000",
        "description": "Money amount at their lowest denominator (for example: pennies)"
      },
      "formatted": {
        "example": "£40.00",
        "description": "Money amount formatted with currency"
      },
      "currency": {
        "example": "GBP",
        "description": "Currency of the money"
      }
    },
    "amount_type": "net",
    "start_date": "2025-06-09",
    "end_date": "2026-06-09",
    "frequency": "annually",
    "is_taxable": true,
    "shared_owner_type": "individual",
    "shared_owner": "App\\Http\\Resources\\AccountResource",
    "employment": "App\\Http\\Resources\\EmploymentResource",
    "account": "App\\Http\\Resources\\MinimalAccountResource"
  },
  "account": {
    "uuid": "2ce067b1-be2c-47ae-966e-09d96f801f62",
    "created_at": "2026-06-09T14:10:15+01:00",
    "updated_at": "2026-06-09T14:10:15+01:00",
    "type": "client",
    "role": "client",
    "first_name": "Gareth",
    "last_name": "Thompson",
    "name": "Gareth Thompson",
    "email": "gareth@codepotato.co.uk",
    "photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
    "external_references": "App\\Http\\Resources\\ExternalReferenceResource"
  }
}