Create an Employment

POST /api/v2/employments

Personal access token & O auth2

Creates an employment record

Headers

X-PLANNR-ACCOUNT-UUID string

application/json

Body Required

account_uuid string Required

The uuid of the account to link Employment to.
accountant_address string

The address of the accountant.
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.
address array[string]

The address of the employer.
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.
email_address string

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

The name of the employer/business.
ended_at date

An optional end date of the employment.
is_business_owner boolean

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

Job title if no suitable occupation code is found.
last_salary_increase date

The date of the last salary increase.
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.
percentage_of_business_owned integer

The percentage of the business owned.
phone_number string

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

The profit of the business in pennies.
shareholding_in_business number

The shareholding in the business in percentage.
status string Required

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

An optional start date of the employment.

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
- 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
  
  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
  
  groups string
  
  tags string
  
  owners string
  
  first_contact_date string
  
  next_review_date string
  
  previous_review_date string
  
  anniversary_review_date string
  
  with_login boolean
  
  has_joint_account boolean
  
  can_be_deleted string
  
  joint_account_circle string
  
  ownership_percentage integer
  
  inactive_at string
  
  custom_fields string
  
  external_references string
- last_salary_increase object
  
  The last salary increase.
  
  Hide last_salary_increase attributes Show last_salary_increase 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
- 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
  
  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

POST /api/v2/employments

curl \
 --request POST 'https://api.plannrcrm.com/api/v2/employments' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}" \
 --data '{"account_uuid":"c1683590-2c6c-4b06-84d9-afc5b5b87cc0","accountant_address":"1 My Street, My Town, My Country","accountant_company_name":"My Company","accountant_email":"accountant@email.com","accountant_telephone_number":"0123456789","address":[{"name":{"type":"string","example":"Work Address","required":false,"description":"Name of the address"},"county":{"type":"string","example":"Hampshire","required":false,"description":"County"},"country":{"type":"string","example":"United Kingdom","required":false,"description":"Country"},"postcode":{"type":"string","example":"PO7 7YH","required":false,"description":"Postcode"},"address_1":{"type":"string","example":"Suite E","required":false,"description":"First line of the address"},"address_2":{"type":"string","example":"5 The Briars","required":false,"description":"Second line of the address"},"address_3":{"type":"string","example":"Waterberry Drive","required":false,"description":"Third line of the address"},"address_4":{"type":"string","example":"The Innovative Centre","required":false,"description":"Fourth line of the address"},"town_city":{"type":"string","example":"Waterlooville","required":false,"description":"Town/City"},"move_in_date":{"type":"string","example":"2024-06-20","required":false,"description":"Move in date"},"moved_in_year":{"type":"integer","example":2022,"required":false,"description":"The year the client moved into this address."},"moved_in_month":{"type":"integer","example":6,"required":false,"description":"The month the client moved into this address."},"moved_out_year":{"type":"integer","example":2024,"required":false,"description":"The year the client moved out of this address."},"moved_out_month":{"type":"integer","example":1,"required":false,"description":"The month the client moved out of this address."},"residential_status":{"type":"string","example":"homeowner","required":false,"description":"The client's residential status when living at the address."},"residential_status_other":{"type":"string","example":"Non-tenant occupier","required":false,"description":"The client's residential status if it is not provided in the residential_status options. Must only be provided if residential_status is other."}}],"business_name":"My Business","business_year_end":"2019-01-01","business_value":5000000,"directors":"John Doe","email_address":"gareth@plannrcrm.com","employer":"Plannr Technologies Ltd","ended_at":"2021-06-26T11:37:11+01:00","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,"status":"employed","started_at":"2020-06-26T11:37:11+01:00"}'

Request examples

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

# Payload
{
  "account_uuid": "c1683590-2c6c-4b06-84d9-afc5b5b87cc0",
  "accountant_address": "1 My Street, My Town, My Country",
  "accountant_company_name": "My Company",
  "accountant_email": "accountant@email.com",
  "accountant_telephone_number": "0123456789",
  "address": [
    {
      "name": {
        "type": "string",
        "example": "Work Address",
        "required": false,
        "description": "Name of the address"
      },
      "county": {
        "type": "string",
        "example": "Hampshire",
        "required": false,
        "description": "County"
      },
      "country": {
        "type": "string",
        "example": "United Kingdom",
        "required": false,
        "description": "Country"
      },
      "postcode": {
        "type": "string",
        "example": "PO7 7YH",
        "required": false,
        "description": "Postcode"
      },
      "address_1": {
        "type": "string",
        "example": "Suite E",
        "required": false,
        "description": "First line of the address"
      },
      "address_2": {
        "type": "string",
        "example": "5 The Briars",
        "required": false,
        "description": "Second line of the address"
      },
      "address_3": {
        "type": "string",
        "example": "Waterberry Drive",
        "required": false,
        "description": "Third line of the address"
      },
      "address_4": {
        "type": "string",
        "example": "The Innovative Centre",
        "required": false,
        "description": "Fourth line of the address"
      },
      "town_city": {
        "type": "string",
        "example": "Waterlooville",
        "required": false,
        "description": "Town/City"
      },
      "move_in_date": {
        "type": "string",
        "example": "2024-06-20",
        "required": false,
        "description": "Move in date"
      },
      "moved_in_year": {
        "type": "integer",
        "example": 2022,
        "required": false,
        "description": "The year the client moved into this address."
      },
      "moved_in_month": {
        "type": "integer",
        "example": 6,
        "required": false,
        "description": "The month the client moved into this address."
      },
      "moved_out_year": {
        "type": "integer",
        "example": 2024,
        "required": false,
        "description": "The year the client moved out of this address."
      },
      "moved_out_month": {
        "type": "integer",
        "example": 1,
        "required": false,
        "description": "The month the client moved out of this address."
      },
      "residential_status": {
        "type": "string",
        "example": "homeowner",
        "required": false,
        "description": "The client's residential status when living at the address."
      },
      "residential_status_other": {
        "type": "string",
        "example": "Non-tenant occupier",
        "required": false,
        "description": "The client's residential status if it is not provided in the residential_status options. Must only be provided if residential_status is other."
      }
    }
  ],
  "business_name": "My Business",
  "business_year_end": "2019-01-01",
  "business_value": 5000000,
  "directors": "John Doe",
  "email_address": "gareth@plannrcrm.com",
  "employer": "Plannr Technologies Ltd",
  "ended_at": "2021-06-26T11:37:11+01:00",
  "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,
  "status": "employed",
  "started_at": "2020-06-26T11:37:11+01:00"
}

Response examples (201)

{
  "uuid": "1bb58976-7428-4431-b983-3360b12e8bb2",
  "income": {
    "name": "My Salary",
    "type": "salary",
    "uuid": "4103aeaa-0ea8-4a88-8c12-7d0a2d5ce283",
    "amount": {
      "amount": {
        "example": "4000",
        "description": "Money amount at their lowest denominator (for example: pennies)"
      },
      "currency": {
        "example": "GBP",
        "description": "Currency of the money"
      },
      "formatted": {
        "example": "£40.00",
        "description": "Money amount formatted with currency"
      }
    },
    "account": "App\\Http\\Resources\\MinimalAccountResource",
    "end_date": "2025-06-26",
    "frequency": "annually",
    "created_at": "2025-06-26T11:37:11+01:00",
    "employment": "App\\Http\\Resources\\EmploymentResource",
    "is_taxable": true,
    "start_date": "2024-06-26",
    "updated_at": "2025-06-26T11:37:11+01:00",
    "amount_type": "net",
    "shared_owner": "App\\Http\\Resources\\AccountResource",
    "shared_owner_type": "individual"
  },
  "profit": {
    "amount": {
      "example": "4000",
      "description": "Money amount at their lowest denominator (for example: pennies)"
    },
    "currency": {
      "example": "GBP",
      "description": "Currency of the money"
    },
    "formatted": {
      "example": "£40.00",
      "description": "Money amount formatted with currency"
    }
  },
  "status": "employed",
  "account": {
    "name": "Gareth Thompson",
    "role": "client",
    "type": "client",
    "uuid": "4c6d74a6-c0be-409d-9d0f-683dfd22b3fe",
    "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"
  },
  "address": {
    "name": "Work Address",
    "uuid": "e6251acd-33b9-492a-942b-d97189da8334",
    "county": "Hampshire",
    "country": "United Kingdom",
    "accounts": "App\\Http\\Resources\\AccountResource",
    "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",
    "move_in_date": "2024-06-26"
  },
  "primary": true,
  "employer": "Plannr Technologies Ltd",
  "ended_at": "2021-06-26T11:37:11+01:00",
  "directors": "Susan F. Lancaster",
  "job_title": "Senior financial adviser",
  "created_at": "2025-06-26T11:37:11+01:00",
  "occupation": "Financial Adviser",
  "started_at": "2020-06-26T11:37:11+01:00",
  "updated_at": "2025-06-26T11:37:11+01:00",
  "phone_number": {
    "name": "Work number",
    "type": "phone_number",
    "uuid": "adb0a50c-400b-4f14-96d8-67b95a0e8215",
    "value": "+443330903630",
    "accounts": "App\\Http\\Resources\\AccountResource",
    "created_at": "2025-06-26T11:37:11+01:00",
    "updated_at": "2025-06-26T11:37:11+01:00",
    "phone_number_meta": {
      "country": "GB",
      "formatted": "0333 090 3630"
    }
  },
  "shared_owner": {
    "firm": "App\\Http\\Resources\\FirmResource",
    "name": "Gareth Thompson",
    "role": "client",
    "tags": "App\\Http\\Resources\\TagResource",
    "type": "client",
    "uuid": "16c76190-f990-451c-a759-99b4b903b6aa",
    "email": "gareth@codepotato.co.uk",
    "groups": "App\\Http\\Resources\\GroupResource",
    "owners": "App\\Http\\Resources\\AccountResource",
    "last_name": "Thompson",
    "created_at": "2025-06-26T11:37:11+01:00",
    "first_name": "Gareth",
    "updated_at": "2025-06-26T11:37:11+01:00",
    "with_login": true,
    "inactive_at": "2025-06-26",
    "custom_fields": "App\\Http\\Resources\\CustomFieldValueResource",
    "introduced_by": "App\\Http\\Resources\\AccountResource",
    "primary_email": "App\\Http\\Resources\\ContactDetailResource",
    "can_be_deleted": "false",
    "assigned_adviser": "App\\Http\\Resources\\AccountResource",
    "next_review_date": "2025-06-26T11:37:11+01:00",
    "has_joint_account": true,
    "current_time_entry": "App\\Http\\Resources\\TimeEntryResource",
    "first_contact_date": "2025-06-26T11:37:11+01:00",
    "external_references": "App\\Http\\Resources\\ExternalReferenceResource",
    "assigned_paraplanner": "App\\Http\\Resources\\AccountResource",
    "joint_account_circle": "App\\Http\\Resources\\CircleResource",
    "ownership_percentage": 100,
    "previous_review_date": "2025-06-26T11:37:11+01:00",
    "primary_phone_number": "App\\Http\\Resources\\ContactDetailResource",
    "assigned_administrator": "App\\Http\\Resources\\AccountResource",
    "anniversary_review_date": "2025-06-26T11:37:11+01:00"
  },
  "business_name": "My Business",
  "email_address": {
    "name": "Work number",
    "type": "phone_number",
    "uuid": "e5f0e5cd-da35-43aa-a35b-3d297a956add",
    "value": "+443330903630",
    "accounts": "App\\Http\\Resources\\AccountResource",
    "created_at": "2025-06-26T11:37:11+01:00",
    "updated_at": "2025-06-26T11:37:11+01:00",
    "phone_number_meta": {
      "country": "GB",
      "formatted": "0333 090 3630"
    }
  },
  "business_value": {
    "amount": {
      "example": "4000",
      "description": "Money amount at their lowest denominator (for example: pennies)"
    },
    "currency": {
      "example": "GBP",
      "description": "Currency of the money"
    },
    "formatted": {
      "example": "£40.00",
      "description": "Money amount formatted with currency"
    }
  },
  "occupation_code": "FAC02774",
  "accountant_email": "accountant@email.com",
  "turnover_history": {
    "year": 2020,
    "value": {
      "amount": {
        "example": "4000",
        "description": "Money amount at their lowest denominator (for example: pennies)"
      },
      "currency": {
        "example": "GBP",
        "description": "Currency of the money"
      },
      "formatted": {
        "example": "£40.00",
        "description": "Money amount formatted with currency"
      }
    }
  },
  "business_year_end": "2020-12-31",
  "is_business_owner": true,
  "shared_owner_type": "individual",
  "accountant_address": "23 Chollerton, Hexham, Northumberland, NE46 4TF",
  "last_salary_increase": {
    "amount": {
      "example": "4000",
      "description": "Money amount at their lowest denominator (for example: pennies)"
    },
    "currency": {
      "example": "GBP",
      "description": "Currency of the money"
    },
    "formatted": {
      "example": "£40.00",
      "description": "Money amount formatted with currency"
    }
  },
  "accountant_company_name": "My Accountant",
  "shareholding_in_business": {
    "amount": {
      "example": "4000",
      "description": "Money amount at their lowest denominator (for example: pennies)"
    },
    "currency": {
      "example": "GBP",
      "description": "Currency of the money"
    },
    "formatted": {
      "example": "£40.00",
      "description": "Money amount formatted with currency"
    }
  },
  "accountant_telephone_number": "+441234567890",
  "percentage_of_business_shared": 50
}