Create jobs
Creating jobs in Connecteam involves defining core job attributes and optionally assigning nested sub-jobs for more complex hierarchical structures. This method allows you to customize job configurations according to your organization's operational needs.
Good to know
Testing the creation of jobs with nested sub-jobs is not supported in the sandbox environment.
In order test these API calls, you can use tools like Postman, Insomnia, or cURL.
These tools allow you to simulate API requests and review responses to ensure everything functions as expected before deploying to production.
When creating a regular job, you need to specify basic job details and assignment settings:
- instanceIds: List of Scheduler IDs to assign the job to.
- title: The title of the job.
- code: The code of the job.
- description: The description of the job.
- gps: The GPS data of the job, used if the job requires location tracking.
- assign:Assignment-related settings, allowing for detailed control over how and to whom the job is assigned. You can whether specify userIds, groupIds or both.
- color: Optional. Defaults to #4B7AC5. The color representing the job. Must be one of the specified colors for uniformity across the platform.
Payload example for creating regular job request (without nested sub-jobs)
[
{
"instanceIds": [
6833518
],
"title": "Regular job test title",
"code": "3357YU",
"gps": {
"address": "this is an example address in New York",
"longitude": 40.71,
"latitude": -73.93
},
"assign": {
"type": "users", //In this example we specified only user IDs
"userIds": [
7031021
]
},
"color": "#3968BB",
"description": "This is the description for the new job"
}
]
Payload example for creating regular job response:
{
"requestId": "6c5f7f64-df27-4430-b41e-fe0f86ec20dd",
"data": {
"jobs": [
{
"jobId": "9fdebf1f-0c69-4914-89d2-8f86c3e5f47d",
"title": "Regular job test title",
"code": "3357YU",
"color": "#3968BB",
"description": "This is the description for the new job",
"gps": {
"address": "this is an example address in New York",
"longitude": 40.71,
"latitude": -73.93
},
"isDeleted": false,
"assign": {
"type": "both",
"userIds": [
7031021
],
"groupIds": []
},
"useParentData": false,
"parentId": "",
"subJobs": []
}
]
}
}
Important Note
Currently, the system supports assigning only one instance ID per request. In 2025, it will be possible to specify more than one instance (Scheduler, Time Clock, or both).
Creating Jobs with Nested Sub-Jobs
To create a job with nested sub-jobs, specify additional sub-job details within the subJobs array. This allows for detailed task breakdowns beneath the main job:
When creating a job with nested sub-jobs, pay attention to the following fields:
- subJobs: List of sub-jobs to create under the main job. Each sub-job can have its own set of attributes similar to main jobs, such as title and description.
- useParentData: This field is very important to understand.
By default, it is set to true, meaning the following fields will be inherited from the parent job: assign, location data, description. If any of these fields need to be different from those in the parent job, you must specify all the fields along withuseParentDataset to false.
Good to know
If useParentData is set to true, the inherited fields in the sub-jobs will remain empty. To retrieve the details of these fields, please refer to the parent job details (example is provided).
Payload example for creating job with nested sub-jobs request (when use parent data is set to true - by default):
[
{
"instanceIds": [6833518
],
"title": "Parent job title example",
"code": "12322ds",
"assign": {
"type": "groups",
"groupIds": [
5321397
]
},
"color": "#225A8C",
"subJobs": [ //The nested sub-jobs, useParentData defaults to true, no need to specify it
{
"title": "sub-job 1 title example"
},
{
"title": "sub-job 2 title example"
},
{
"title": "sub-job 3 title example"
}
]
}
]
Payload example for creating job with nested sub-jobs response:
{
"requestId": "24aa0cd5-a990-476a-ba8f-15ac2557ebfd",
"data": {
"jobs": [
{
"jobId": "19cc77e2-0aab-4578-a79c-0d8160671a34",
"title": "Parent job title example",
"code": "12322ds",
"color": "#225A8C",
"description": "",
"gps": {
"address": "",
"longitude": 0.0,
"latitude": 0.0
},
"isDeleted": false,
"assign": {
"type": "both",
"userIds": [],
"groupIds": [
"5321397"
]
},
"useParentData": false,
"parentId": "",
"subJobs": [
{
"jobId": "7c86a7c2-6736-4c91-aeec-b1beb64fb7b5",
"title": "sub-job 1 title example",
"code": "",
"color": "#4B7AC5",
"description": "",
"gps": {
"address": "",
"longitude": 0.0,
"latitude": 0.0
},
"isDeleted": false,
"assign": { //The assign details are the same as the parent job
"type": "both",
"userIds": [],
"groupIds": []
},
"useParentData": true, //This field indicates the sub-job inherited the fields of the parent job
"parentId": "19cc77e2-0aab-4578-a79c-0d8160671a34"
},
{
"jobId": "4ffd4ccc-7a07-48cc-ada2-127b6edbd54b",
"title": "sub-job 2 title example",
"code": "",
"color": "#4B7AC5",
"description": "",
"gps": {
"address": "",
"longitude": 0.0,
"latitude": 0.0
},
"isDeleted": false,
"assign": {
"type": "both",
"userIds": [],
"groupIds": []
},
"useParentData": true,
"parentId": "19cc77e2-0aab-4578-a79c-0d8160671a34"
},
{
"jobId": "a75f9c56-378a-41ea-8a8e-b74eb5e61ad3",
"title": "sub-job 3 title example",
"code": "",
"color": "#4B7AC5",
"description": "",
"gps": {
"address": "",
"longitude": 0.0,
"latitude": 0.0
},
"isDeleted": false,
"assign": {
"type": "both",
"userIds": [],
"groupIds": []
},
"useParentData": true,
"parentId": "19cc77e2-0aab-4578-a79c-0d8160671a34"
}
]
}
]
}
}
Payload example for creating job with nested sub-jobs request (when one of the sub-jobs useParentData is set to false):
[
{
"instanceIds": [6833518
],
"title": "Parent job title example",
"code": "12322ds",
"assign": {
"type": "groups",
"groupIds": [
5321397
]
},
"color": "#225A8C",
"subJobs": [
{
"title": "sub-job 1 title example with different assigned user",
"useParentData": false, //All fields inherited from the parent job must be specified otherwise will remain empty
"assign": {
"type": "users",
"userIds": [
7031021
]
}
},
{
"title": "sub-job 2 title example"
},
{
"title": "sub-job 3 title example"
}
]
}
]
Payload example for creating job with nested sub-jobs (with useParentData set to false) response:
{
"requestId": "ae829c4c-43b9-4a4b-b6c0-95ac93702d85",
"data": {
"jobs": [
{
"jobId": "3753d207-fab8-4b74-8520-99ec5b64aa92",
"title": "Parent job title example",
"code": "12322ds",
"color": "#225A8C",
"description": "",
"gps": {
"address": "",
"longitude": 0.0,
"latitude": 0.0
},
"isDeleted": false,
"assign": {
"type": "both",
"userIds": [],
"groupIds": [
"5321397"
]
},
"useParentData": false,
"parentId": "",
"subJobs": [
{
"jobId": "7a54ff39-c239-4705-a3e6-1efada80d547",
"title": "sub-job 1 title example with different assigned user",
"code": "",
"color": "#4B7AC5",
"description": "",
"gps": {
"address": "",
"longitude": 0.0,
"latitude": 0.0
},
"isDeleted": false,
"assign": { //This is the sub-job with the new assigned user, it will be specified in the response
"type": "both",
"userIds": [
7031021
],
"groupIds": []
},
"useParentData": true,
"parentId": "3753d207-fab8-4b74-8520-99ec5b64aa92"
},
{
"jobId": "8aa580c8-9b6f-49ab-938f-d60873461dc6",
"title": "sub-job 2 title example",
"code": "",
"color": "#4B7AC5",
"description": "",
"gps": {
"address": "",
"longitude": 0.0,
"latitude": 0.0
},
"isDeleted": false,
"assign": { //for this sub-job, the details are inherited from the parent job (same assigned data) as the useParentData set to true
"type": "both",
"userIds": [],
"groupIds": []
},
"useParentData": true,
"parentId": "3753d207-fab8-4b74-8520-99ec5b64aa92"
},
{
"jobId": "ef8b2bf8-901d-4c77-84c3-eb7b845d5904",
"title": "sub-job 3 title example",
"code": "",
"color": "#4B7AC5",
"description": "",
"gps": {
"address": "",
"longitude": 0.0,
"latitude": 0.0
},
"isDeleted": false,
"assign": {
"type": "both",
"userIds": [],
"groupIds": []
},
"useParentData": true,
"parentId": "3753d207-fab8-4b74-8520-99ec5b64aa92"
}
]
}
]
}
}
Important Notes
Nested Sub-Jobs: While creating sub-jobs is supported during the job creation process, updating and deleting sub-jobs individually is currently not supported.
Future API releases aim to provide comprehensive sub-job management methods.
This method provides flexibility in structuring tasks and scheduling, making it adaptable to various organizational needs. For further assistance or advanced configurations, please refer to the Connecteam API documentation or support resources.
Updated 3 months ago