Navigation :

Create Work Order

Creates a new work order.

URLs

Environment	Method	URL
Sandbox		https://api-sandbox.fndev.net/api/rest/v2/workorders
Production		https://api.fieldnation.com/api/rest/v2/workorders

Path Parameters

Not applicable.

Query Parameters

Parameter	Type	Example	Notes
access_token	string	abc123defg459hijk786lmn45	Required.

Body Parameters

Body parameters can vary depending on your work order options. If you use a work order template, some of these parameters will be automatically set.

Create Work Order Examples

Here are some JSON examples to help you get started.

Tip: Refer to Work Order Locations, Schedules, and Pay Rates for additional options and examples.

Work Order with Primary and Additional Types of Work to complete a job

This example uses a Primary Type of Work of Point of Sale with Additional Types of Work of Low Voltage Runs and Low Voltage Testing.It does not include a work order template.

Warning: The support of type_of_work will be deprecated in the future and we encourage you to use types_of_work instead.


{
   "title":"Install Point of Sale and run cable at a new store",
   "type_of_work":{
      "id" : 62
   },
   "types_of_work":[
      {
         "id" : 91,
         "isPrimary" : true,
      },
      {
         "id" : 93,
         "isPrimary" : false,
      },
      {
         "id" : 94,
         "isPrimary" : false,
      },
   ],
   "description":{
      "html":"<p>This example uses a Primary Type of Work of Point of Sale with Additional Types of Work of Low Voltage Runs and Low Voltage Testing</p>"
   },
   "require_gps": true,
   "manager": {
       "id": 776
   },
   "confidential":{
      "html":""
   },
   "location":{
      "mode":"custom",
      "display_name":"ABC Corp",
      "address1":"123 Main Street",
      "address2":"Building 4C",
      "city":"Phoenix",
      "state":"AZ",
      "zip":"85001",
      "country":"US",
      "type":{
         "id":1
      }
   },
   "schedule":{
      "service_window":{
         "mode":"exact",
         "start":{
            "utc":"2018-11-07 13:00:00"
         }
      }
   },
   "pay":{
      "type":"fixed",
      "base":{
         "amount":400,
         "units":1
      }
   },
   "template":null
}

Work Order with Manager, Require GPS, Location, Arrive at a specific date and time, Fixed Pay

This example uses a Custom Location, where the provider should Arrive at a specific date and time and should turn the GPS on the device during check-in & check-out. The pay rate is Fixed Pay. It does not include a work order template. The work order has a Primary types of work of ID 146 and an Additional types of work of ID 127.

Warning: The support of type_of_work will be deprecated in the future and we encourage you to use types_of_work instead.


{
   "title":"Fix Copier on 2nd Floor",
   "type_of_work":{
      "id" : 76
   },
   "types_of_work":[
      {
         "id" : 146,
         "isPrimary" : true,
      },
      {
         "id" : 127,
         "isPrimary" : false,
      },
   ],
   "require_gps": true,
   "manager": {
       "id": 776
   },
   "description":{
      "html":"<p>copier is displaying error code <b>206</b>.</p>"
   },
   "confidential":{
      "html":""
   },
   "location":{
      "mode":"custom",
      "display_name":"ABC Corp",
      "address1":"123 Main Street",
      "address2":"Building 4C",
      "city":"Phoenix",
      "state":"AZ",
      "zip":"85001",
      "country":"US",
      "type":{
         "id":1
      }
   },
   "schedule":{
      "service_window":{
         "mode":"exact",
         "start":{
            "utc":"2018-11-07 13:00:00"
         }
      }
   },
   "pay":{
      "type":"fixed",
      "base":{
         "amount":400,
         "units":1
      }
   },
   "template":null
}

Use a Client and/or Project ID, Complete work between specific hours, Per Hour Pay

This example includes a client id and a project id, where the provider should Complete work between specific hours. The pay rate is Per Hour Pay.The work order has a Primary types of work of ID 146 and an Additional types of work of ID 127.

Warning: The support of type_of_work will be deprecated in the future and we encourage you to use types_of_work instead.


{
   "title":"Fix Copier on 2nd Floor",
   "type_of_work":{
      "id" : 76
   },
   "types_of_work":[
      {
         "id" : 146,
         "isPrimary" : true,
      },
      {
         "id" : 127,
         "isPrimary" : false,
      },
   ],
   "client":{
      "id": 188
   },
   "project":{
      "id":239
   },
   "description":{
      "html":"<p>copier is displaying error code <b>206</b>.</p>"
   },
   "confidential":{
      "html":""
   },
   "location":{
      "mode":"custom",
      "display_name":"ABC Corp",
      "address1":"123 Main Street",
      "address2":"Building 4C",
      "city":"Phoenix",
      "state":"AZ",
      "zip":"85001",
      "country":"US",
      "type":{
         "id":1
      }
   },
"schedule":{  
      "service_window":{  
         "mode":"hours",
         "start":{  
            "utc":"2018-11-07 13:00:00"
         },
         "end":{  
            "utc":"2018-11-08 15:00:00"
         }
      }
   },
   "pay":{  
      "type":"hourly",
      "base":{  
         "amount":25,
         "units":4
      }
   },
   "template":null
}

Use a Work Order Template, Complete work anytime over a date range

This example uses a work order template with a prefilled client, project, type of work, and pay rate. The provider should Complete work anytime over a date range. Refer to Get Templates to return a list of your work order template ids.


{
   "title":"Fix Copier on 2nd Floor",
   "template":{
      "id":68
   },
   "location":{
      "mode":"custom",
      "display_name":"ABC Corp",
      "address1":"123 Main Street",
      "address2":"Building 4C",
      "city":"Phoenix",
      "state":"AZ",
      "zip":"85001",
      "country":"US",
      "type":{
         "id":1
      }
   },
   "schedule":{  
      "service_window":{  
         "mode":"between",
         "start":{  
            "utc":"2018-11-06 13:00:00"
         },
         "end":{  
            "utc":"2018-11-06 22:00:00"
         }
      }
   }
}

Include a Bonus and/or Penalty

This example adds a bonus and penalty to the pay object. Refer to Bonuses and Penalties for more information.The work order has a Primary types of work of ID 146 and an Additional types of work of ID 127.

Warning: The support of type_of_work will be deprecated in the future, and we encourage you to use types_of_work instead.

{
   "title":"ATM Repair Bonus/Penalty",
   "type_of_work":{
      "id":76
   },
    "types_of_work":[
      {
         "id" : 146,
         "isPrimary" : true,
      },
      {
         "id" : 127,
         "isPrimary" : false,
      },
   ],
   "description":{
      "html":"monthly ATM maintenance."
   },
   "location":{
      "mode":"custom",
      "display_name":"ABC Corp",
      "address1":"123 Main Street",
      "address2":"Building 4C",
      "city":"Phoenix",
      "state":"AZ",
      "zip":"85001",
      "country":"US",
      "type":{
         "id":1
      }
   },
   "schedule":{
      "service_window":{
         "mode":"exact",
         "start":{
            "utc":"2019-1-07 13:00:00"
         }
      }
   },
   "pay":{
      "type":"fixed",
      "base":{
         "amount":400,
         "units":1
      },
      "bonuses":{
         "results":[
            {
               "id":3
            }
         ]
      },
      "penalties":{
         "results":[
            {
               "id":6
            }
         ]
      }
   }
}

Include a Custom Field Value

You can send custom field values in a custom_fields > results > results array. All other custom field parameters are read-only. Refer to Custom Fields for more information.


"custom_fields":{
   "results":[
      {
         "results":[
            {
               "id":129,
               "value":"1001258"
            }
         ]
      }
   ]
}

Include Contacts

You can send contacts in the results array. Refer to Contacts for additional role types and contact parameters.


"contacts":{
   "results":[
      {
         "role":"Location Contact",
         "name":"Site Contact",
         "email":"sitecontact@email.com",
         "phone":"4805551234"
      },
      {
         "role":"Project manager",
         "name":"Project Manager",
         "email":"projectmgr@email.com",
         "phone":"4805551234"
      }
   ]
}

Include Tasks

A new work order includes Set ETA, “Enter closeout notes,” “Check in,” and “Check out” tasks in the On Site group by default. You can send additional tasks in the results array. Refer to Tasks for more information.

Note: The tasks object returns a paginated list of results. When you create a new work order, this object returns only four tasks by default. For a complete list of tasks, you can Get Work Order by ID or Get Tasks by Work Order.

This example creates a task to Upload/take photo in the Post Work group.


"tasks":{
   "results":[
      {
         "group":{
            "id":"post"
         },
         "type":{
            "id":6
         },
         "label":"finished work."
      }
 ]

Include Auto-Dispatch

In order to use auto-dispatch through the integration, you must add “auto_dispatch”: true. This is required even if you have a selection rule set on the template or project.


"auto_dispatch": true

Incident/Site ID

Creates a new Incident/Site ID to associate a new work order or site with a unique identifier. This is useful when creating a new work order and associating it with a new site identifier.


"incident_id": "54321"

Response

Returns the Work Order Response. Refer to Work Orders for parameter details and examples.

Errors

Standard HTTP and OAuth error codes.

Examples

400 Bad Request

Missing required parameter.


{
    "message": "Parameter \"title\" is required and was not passed in request payload",
    "trace": [],
    "extra": []
}