Create an Employment Run in API Explorer
Ask AI
Creates an employment record
Body
-
The uuid of the account to link Employment to.
-
The name of the accountant company.
Maximum length is
255. -
The email of the accountant.
Maximum length is
255. -
The telephone number of the accountant.
-
The address of the accountant.
Maximum length is
255. -
The name of the business.
Maximum length is
255. -
The value of the business in pennies.
-
The year end of the business.
Maximum length is
255. -
The directors of the business.
Maximum length is
255. -
The name of the employer/business.
Maximum length is
255. -
The email address of the employer. Will be added as a contact detail.
Maximum length is
255. -
An optional end date of the employment.
-
Denotes if the employment owner is the business owner.
-
Job title if no suitable occupation code is found.
Maximum length is
255. -
The date of the last salary increase.
-
The Origo occupation code for the given employment. You can use the /api/v1/static/occupations endpoint to get a list of occupations.
-
The percentage of the business owned.
Minimum value is
0, maximum value is100. -
The phone number of the employer. In E.164 format. Will be added as a contact detail.
-
Make this employment the primary employment. Will make all other employments no longer primary.
-
The profit of the business in pennies.
Minimum value is
0. -
An optional start date of the employment.
-
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, orother. -
An array of turnover history items.
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":"69f755a3-e931-4081-8679-5d6d63753e31","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-08","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-08","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
{
"account_uuid": "69f755a3-e931-4081-8679-5d6d63753e31",
"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-08",
"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-08",
"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 (201)
[
{
"uuid": "8bf40548-ec4e-4994-81a7-9f693c072d6f",
"created_at": "2026-06-08T16:08:04+01:00",
"updated_at": "2026-06-08T16:08:04+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-08T16:08:04+01:00",
"ended_at": "2022-06-08T16:08:04+01:00",
"is_business_owner": true,
"percentage_of_business_shared": 50,
"address": {
"uuid": "679d3ef9-e6ad-4e2c-aac3-8fc08381feda",
"created_at": "2026-06-08T16:08:04+01:00",
"updated_at": "2026-06-08T16:08:04+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": "e25593b0-c406-46fe-8106-2a2fdfa9cf44",
"created_at": "2026-06-08T16:08:04+01:00",
"updated_at": "2026-06-08T16:08:04+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": "a3a96c36-36a5-4b25-af1f-5c133506e37e",
"created_at": "2026-06-08T16:08:04+01:00",
"updated_at": "2026-06-08T16:08:04+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": "fbb68ecf-36d4-4730-9a5f-1ba57ed4e6c9",
"created_at": "2026-06-08T16:08:04+01:00",
"updated_at": "2026-06-08T16:08:04+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:04+01:00",
"next_review_date": "2026-06-08T16:08:04+01:00",
"previous_review_date": "2026-06-08T16:08:04+01:00",
"anniversary_review_date": "2026-06-08T16:08:04+01:00",
"terms_of_business_at": "2026-06-08T16:08:04+01:00",
"client_agreement_at": "2026-06-08T16:08:04+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:04",
"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": "e61dae55-c5bf-49b8-804b-89eea059ad85",
"created_at": "2026-06-08T16:08:04+01:00",
"updated_at": "2026-06-08T16:08:04+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"
},
"account": {
"uuid": "842a47a3-46c6-4d16-9fb7-fb6d7deb82bb",
"created_at": "2026-06-08T16:08:04+01:00",
"updated_at": "2026-06-08T16:08:04+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"
}
}
]