Create an Employment

POST /api/v2/employments

Personal access token & O auth2

Creates an employment record

Headers

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.
- phone_number object
  
  The phone number of the employer.
- email_address object
  
  The email address of the employer.
- 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".
- last_salary_increase object
  
  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.
- directors string
  
  The directors of the business.
- shareholding_in_business object
  
  The shareholding in the business.
- profit object
  
  The profit of the business.
- 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.
- income object
  
  Incomes that have been linked to thi employment.
- account object
  
  The account for this employment.

POST /api/v2/employments

curl \
 --request POST 'https://api.plannrcrm.com/api/v2/employments' \
 --header "Authorization: Bearer {OAUTH_ACCESS_TOKEN or PERSONAL_ACCESS_TOKEN}" \
 --header "Content-Type: application/json" \
 --header "Accept: application/json" \
 --header "X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}" \
 --data '{"account_uuid":"6c733f78-dc0f-4d9d-a21e-a1e6594e6eca","accountant_address":"1 My Street, My Town, My Country","accountant_company_name":"My Company","accountant_email":"accountant@email.com","accountant_telephone_number":"0123456789","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":"Work Address","required":false,"description":"Name of the address"},"address_2":{"type":"string","example":"Suite E, 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"}}],"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-04-02T13:27:59+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-04-02T13:27:59+01:00"}'

Request examples

# Headers
Authorization: Bearer {OAUTH_ACCESS_TOKEN or PERSONAL_ACCESS_TOKEN}
Content-Type: application/json
Accept: application/json
X-PLANNR-ACCOUNT-UUID: {YOUR_PLANNR_ACCOUNT_UUID}

# Payload
{
  "account_uuid": "6c733f78-dc0f-4d9d-a21e-a1e6594e6eca",
  "accountant_address": "1 My Street, My Town, My Country",
  "accountant_company_name": "My Company",
  "accountant_email": "accountant@email.com",
  "accountant_telephone_number": "0123456789",
  "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": "Work Address",
        "required": false,
        "description": "Name of the address"
      },
      "address_2": {
        "type": "string",
        "example": "Suite E, 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"
      }
    }
  ],
  "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-04-02T13:27:59+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-04-02T13:27:59+01:00"
}

Response examples (201)

{
  "uuid": "440791bc-d92e-4841-9f79-378f030f5099",
  "income": {
    "name": "My Salary",
    "type": "salary",
    "uuid": "09f07288-ca1f-4e4e-b954-351d34ffd405",
    "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-04-02",
    "frequency": "annually",
    "created_at": "2025-04-02T13:27:59+01:00",
    "employment": "App\\Http\\Resources\\EmploymentResource",
    "is_taxable": true,
    "start_date": "2024-04-02",
    "updated_at": "2025-04-02T13:27:59+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": "82c5d359-ebb8-4ddb-98d7-6e176711f3d0",
    "email": "gareth@codepotato.co.uk",
    "last_name": "Thompson",
    "photo_url": "https://eu.ui-avatars.com/api/?name=Gareth+Thompson",
    "created_at": "2025-04-02T13:27:59+01:00",
    "first_name": "Gareth",
    "updated_at": "2025-04-02T13:27:59+01:00",
    "external_references": "App\\Http\\Resources\\ExternalReferenceResource"
  },
  "address": {
    "name": "Work Address",
    "uuid": "02fc5381-9a2a-4c38-acd9-977b737103f7",
    "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-04-02T13:27:59+01:00",
    "updated_at": "2025-04-02T13:27:59+01:00",
    "move_in_date": "2024-04-02"
  },
  "primary": true,
  "employer": "Plannr Technologies Ltd",
  "ended_at": "2021-04-02T13:27:59+01:00",
  "directors": "Susan F. Lancaster",
  "job_title": "Senior financial adviser",
  "created_at": "2025-04-02T13:27:59+01:00",
  "occupation": "Financial Adviser",
  "started_at": "2020-04-02T13:27:59+01:00",
  "updated_at": "2025-04-02T13:27:59+01:00",
  "phone_number": {
    "name": "Work number",
    "type": "phone_number",
    "uuid": "057e169a-222c-48a4-abcb-0b704cb33ab6",
    "value": "+443330903630",
    "accounts": "App\\Http\\Resources\\AccountResource",
    "created_at": "2025-04-02T13:27:59+01:00",
    "updated_at": "2025-04-02T13:27:59+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": "f6485bce-1756-4d9e-9dc2-0411009e699a",
    "email": "gareth@codepotato.co.uk",
    "groups": "App\\Http\\Resources\\GroupResource",
    "owners": "App\\Http\\Resources\\AccountResource",
    "last_name": "Thompson",
    "created_at": "2025-04-02T13:27:59+01:00",
    "first_name": "Gareth",
    "updated_at": "2025-04-02T13:27:59+01:00",
    "with_login": true,
    "inactive_at": "2025-04-02",
    "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-04-02T13:27:59+01:00",
    "has_joint_account": true,
    "current_time_entry": "App\\Http\\Resources\\TimeEntryResource",
    "first_contact_date": "2025-04-02T13:27:59+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-04-02T13:27:59+01:00",
    "primary_phone_number": "App\\Http\\Resources\\ContactDetailResource",
    "assigned_administrator": "App\\Http\\Resources\\AccountResource",
    "anniversary_review_date": "2025-04-02T13:27:59+01:00"
  },
  "business_name": "My Business",
  "email_address": {
    "name": "Work number",
    "type": "phone_number",
    "uuid": "65c9ec58-c9ec-416e-95b2-afbdf55ad08d",
    "value": "+443330903630",
    "accounts": "App\\Http\\Resources\\AccountResource",
    "created_at": "2025-04-02T13:27:59+01:00",
    "updated_at": "2025-04-02T13:27:59+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
}