Create an employment | PlannrCRM API documentation

Create 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"
}

POST /api/v1/client/{client_uuid}/employment

Personal access token & O auth2

Headers

X-PLANNR-ACCOUNT-UUID string

Path parameters

client_uuid string Required

application/json

Body

status string Required

The employment status for the given employment. Available values: employed, self_employed, student, unemployed, house_person, retired and other

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.
primary boolean

Make this employment the primary employment. Will make all other employments no longer primary.
occupation_code string

The Origo occupation code for the given employment. You can use the /api/v1/static/occupations endpoint to get a list of occupations.
job_title string

Job title if no suitable occupation code is found.
employer string

The name of the employer/business.
started_at string(date)

An optional start date of the employment.
ended_at string(date)

An optional end date of the employment.
is_business_owner boolean

Denotes if the employment owner is the business owner.
percentage_of_business_owned integer

The percentage of the business owned.
address object
Hide address attributes Show address attributes object
- address_1 string
  
  Name 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
email_address string

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

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

Optional UUID of an owner account. The client must be a shared type.
last_salary_increase string(date)

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 integer

The value of the business in pennies.
directors string

The directors of the business.
shareholding_in_business number(float)

The shareholding in the business in percentage.
profit integer

The profit of the business in pennies.
turnover_history array[object]

The turnover history of the business for each year. All values must be in pennies as integers.
Hide turnover_history attributes Show turnover_history attributes object
- year string
  
  Year for this history item
- value integer
  
  The Value for the year specified
accountant_company_name string

The name of the accountant company.
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.

Value	Description
employed	Employed
self_employed	Self Employed
student	Student
unemployed	Unemployed
house_person	House Person
retired	Retired
other	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.
- status string
  
  The employment status. Available values: employed, self_employed, student, unemployed, house_person, retired and other
- occupation string
  
  The occupation name found from the occupation code provided.
- occupation_code string
  
  @deprecated 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.
- primary boolean
  
  Denotes if the employment is the primary employment for the account associated.
- 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 the 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

POST /api/v1/client/{client_uuid}/employment

curl \
 --request POST 'https://api.plannrcrm.com/api/v1/client/6ff8f7f6-1eb3-3525-be4a-3932c805afed/employment' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}" \
 --data '{"status":"employed","primary":true,"occupation_code":"FAC02774","job_title":"Senior Developer","employer":"Plannr Technologies Ltd","started_at":"2021-06-08","ended_at":"2022-06-08","is_business_owner":true,"percentage_of_business_owned":50,"address":{"address_1":"Work Address","address_2":"Suite E, 5 The Briars","address_3":"Waterberry Drive","address_4":"The Innovative Centre","town_city":"Waterlooville","county":"Hampshire","postcode":"PO7 7YH","country":"United Kingdom"},"email_address":"gareth@plannrcrm.com","phone_number":"+443330509960","shared_owner_uuid":"431e0ed5-c768-446f-afc8-fbc80380861b","last_salary_increase":"2019-01-01","business_name":"My Business","business_year_end":"2019-01-01","business_value":5000000,"directors":"John Doe","shareholding_in_business":50.5,"profit":5000000,"turnover_history":[{"year":2022,"value":5000000},{"year":2021,"value":4500000}],"accountant_company_name":"My Company","accountant_email":"accountant@email.com","accountant_telephone_number":"0123456789","accountant_address":"1 My Street, My Town, My Country"}'

Request examples

# Headers
X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}

# Payload
{
  "status": "employed",
  "primary": true,
  "occupation_code": "FAC02774",
  "job_title": "Senior Developer",
  "employer": "Plannr Technologies Ltd",
  "started_at": "2021-06-08",
  "ended_at": "2022-06-08",
  "is_business_owner": true,
  "percentage_of_business_owned": 50,
  "address": {
    "address_1": "Work Address",
    "address_2": "Suite E, 5 The Briars",
    "address_3": "Waterberry Drive",
    "address_4": "The Innovative Centre",
    "town_city": "Waterlooville",
    "county": "Hampshire",
    "postcode": "PO7 7YH",
    "country": "United Kingdom"
  },
  "email_address": "gareth@plannrcrm.com",
  "phone_number": "+443330509960",
  "shared_owner_uuid": "431e0ed5-c768-446f-afc8-fbc80380861b",
  "last_salary_increase": "2019-01-01",
  "business_name": "My Business",
  "business_year_end": "2019-01-01",
  "business_value": 5000000,
  "directors": "John Doe",
  "shareholding_in_business": 50.5,
  "profit": 5000000,
  "turnover_history": [
    {
      "year": 2022,
      "value": 5000000
    },
    {
      "year": 2021,
      "value": 4500000
    }
  ],
  "accountant_company_name": "My Company",
  "accountant_email": "accountant@email.com",
  "accountant_telephone_number": "0123456789",
  "accountant_address": "1 My Street, My Town, My Country"
}

Response examples (201)

{
  "uuid": "04b82ec7-2b38-424a-873a-6dc03a034611",
  "created_at": "2026-06-08T16:08:02+01:00",
  "updated_at": "2026-06-08T16:08:02+01:00",
  "status": "employed",
  "occupation": "Financial Adviser",
  "occupation_code": "FAC02774",
  "job_title": "Senior financial adviser",
  "employer": "Plannr Technologies Ltd",
  "started_at": "2021-06-08T16:08:02+01:00",
  "ended_at": "2022-06-08T16:08:02+01:00",
  "is_business_owner": true,
  "percentage_of_business_shared": 50,
  "address": {
    "uuid": "9f4158b6-5b8e-47bd-a94c-f36b27803e54",
    "created_at": "2026-06-08T16:08:02+01:00",
    "updated_at": "2026-06-08T16:08:02+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-08",
    "accounts": "App\\Http\\Resources\\AccountResource"
  },
  "phone_number": {
    "uuid": "a6a7a139-8eb1-49ae-978a-dbcc0e147633",
    "created_at": "2026-06-08T16:08:02+01:00",
    "updated_at": "2026-06-08T16:08:02+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": "8fc19f66-a8fe-4106-b355-ed4e1c0a5759",
    "created_at": "2026-06-08T16:08:02+01:00",
    "updated_at": "2026-06-08T16:08:02+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": "819dd0a5-3e28-4085-a919-be5cde8aa3d8",
    "created_at": "2026-06-08T16:08:02+01:00",
    "updated_at": "2026-06-08T16:08:02+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-08T16:08:02+01:00",
    "next_review_date": "2026-06-08T16:08:02+01:00",
    "previous_review_date": "2026-06-08T16:08:02+01:00",
    "anniversary_review_date": "2026-06-08T16:08:02+01:00",
    "terms_of_business_at": "2026-06-08T16:08:02+01:00",
    "client_agreement_at": "2026-06-08T16:08:02+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-08",
    "last_interaction_at": "2026-06-08 16:08:02",
    "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",
  "primary": true,
  "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": "9a9a5a5d-2df8-4a24-bdd3-ad05ee46898f",
    "created_at": "2026-06-08T16:08:02+01:00",
    "updated_at": "2026-06-08T16:08:02+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-08",
    "end_date": "2026-06-08",
    "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"
  }
}