--- title: "Create job" method: POST path: "/v1/jobs" tags: ["Jobs"] --- # Create job `POST /v1/jobs` ## Request - Base URL: `https://api.spruce.eco` - URL: `https://api.spruce.eco/v1/jobs` - Auth: HTTP bearer Create a new job with property and customer details. ## Request body - object - `altitude_m` number: Property altitude in meters. Will be derived from the coordinates if not provided. - `built_form` 'detached' | 'semi_detached' | 'mid_terrace' | 'end_terrace', required: Built form of the property - `floor_area_m2` number, required: Total floor area in square meters - `fuel_type` 'mains_gas' | 'oil' | 'lpg' | 'electric' | 'coal' | 'wood', required: Current heating fuel type - `loft_insulation` 'none' | '50mm' | '100mm' | '150mm' | '200mm' | '250+mm', required: Loft insulation thickness - `num_bathrooms` integer: Number of bathrooms - `num_bedrooms` integer, required: Number of bedrooms - `num_storeys` integer: Number of storeys - `postcode` string, required: UK postcode or Irish Eircode - `property_type` 'house' | 'flat' | 'bungalow', required: Property type - `room_height_m` number: Room height in metres - `wall_type` 'cavity_wall_filled' | 'cavity_wall_unfilled' | 'solid_brick_uninsulated' | 'solid_brick_internal_insulation' | 'solid_brick_external_insulation' | 'solid_brick_unknown' | 'solid_stone_uninsulated' | 'solid_stone_internal_insulation' | 'solid_stone_external_insulation' | 'solid_stone_unknown' | 'solid_concrete_uninsulated' | 'solid_concrete_internal_insulation' | 'solid_concrete_external_insulation' | 'solid_concrete_unknown' | 'timber_uninsulated' | 'timber_internal_insulation' | 'timber_external_insulation' | 'timber_unknown', required: Wall construction and insulation type - `window_type` 'single_glazing' | 'double_glazing' | 'high_performance' | 'triple_glazing', required: Window glazing type - `floor_u_value` number: Floor U-value in W/m²K (optional, if directly measured or from EPC). If provided, overrides the floor U-value used in the heat loss calculation. - `roof_u_value` number: Roof U-value in W/m²K (optional, if directly measured or from EPC). If provided, overrides the roof U-value used in the heat loss calculation (otherwise derived from loft_insulation). - `wall_u_value` number: External wall U-value in W/m²K (optional, if directly measured or from EPC). If provided, overrides both the external wall and party wall U-values used in the heat loss calculation (party wall capped at 0.5 W/m²K; otherwise derived from wall_type). - `window_u_value` number: Window U-value in W/m²K (optional, if directly measured or from EPC). If provided, overrides the window U-value used in the heat loss calculation (otherwise derived from window_type). - `address` string, required: Full property address (consisting of optional apartment number, street and post town) without postcode - `cibse_design_temperature_version` number: Optional CIBSE weather dataset version to use for this job (2 = 2015 dataset, 3 = 2026 dataset). If omitted, the job inherits the company's configured default at read time. - `country` 'England' | 'Scotland' | 'Wales' | 'Northern Ireland' | 'Channel Islands' | 'Isle of Man' | 'Ireland': The country the property is in. Used to determine grant scheme and paperwork. If omitted, it's derived from the postcode / any linked EPC. - `customer_email` string, email, required: Customer's email address - `customer_first_name` string, required: Customer's first name - `customer_last_name` string, required: Customer's last name - `customer_phone` string, required: Customer's phone number - `epc_certificate_number` string: EPC Certificate number for an English/Welsh EPC. If this is present, we will make a best-effort attempt to retrieve the EPC data and link it to the job. - `job_name` string: Optional custom name for the job - `job_reference` string: Optional job reference, which must be unique within the company. If not provided, will be generated from the customer surname. Must be at least 3 characters long and not contain the # character. The API will return an error if the reference is invalid or already exists. - `lat_lng` number[], required: Latitude and longitude coordinates of the address [lat, lng] - `outdoor_space` 'ground_floor' | 'upper_floor' | 'none': Outdoor space availability. Only relevant for flats - indicates where the heat pump could be installed. - `payaca_project_id` string: The ID of an associated Payaca project. If included and the authed company has a Payaca integration set up, the job in Spruce will be linked to this Payaca project. This ID cannot be changed after the job is created. - `source` string: Source of the lead (e.g., 'API', 'Social media', 'Search engine', 'Word of mouth', 'Trade show') - `tags` string[]: Tags to apply to this job. If a tag name does not exist for your company, it will be created automatically. - `udprn` string: Unique Delivery Point Reference Number - `uprn` string: Unique Property Reference Number. If this is included but the EPC certificate number key is omitted, we will attempt to retrieve the EPC from this. Passing the EPC certificate number is a more reliable method to retrieve an EPC. - `year_built` number: Year the property was built. ## Response `201` Job created successfully - object - `job_reference` string, required: The unique job reference, which can be used to search for the job in the Spruce admin panel. It is never used by the API. - `url` string, uri, required: The full admin URL of the job. This URL requires a logged in Spruce account to view. - `uuid` string, uuid, required: The UUID of the new job, which must be used for interacting with the job via the API in future. We strongly recommend that you store this UUID in your internal systems. ## Other responses - `400`: Validation error - `401`: Unauthorized - missing or invalid token - `403`: Forbidden - insufficient permissions - `409`: Conflict - resource already exists --- [API](https://skmtc.dev/spruce/apis/spruce-external-api.md) - [All operations](https://skmtc.dev/spruce/apis/spruce-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/spruce/apis/spruce-external-api/revisions/ffdfaf1a73d9?raw)