--- title: "Create a Work order" method: POST path: "/workorders" tags: ["WorkOrders"] --- # Create a Work order `POST /workorders` ## Request - Base URL: `https://sb2api.servicechannel.com/v3` - URL: `https://sb2api.servicechannel.com/v3/workorders` - Auth: OAuth 2 - Authorization code: `https://sb2login.servicechannel.com/oauth/authorize` - Token URL: `https://sb2login.servicechannel.com/oauth/token` - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates a new Work order. Returns Work order Id for successful request.
Available for provider and subscriber usage.
Additional info:
Updates GL code based on passed Category param according to settings in Admin module {go to Admin => Accounting => GlCodes to see user GL codes}. Similar logic is used when you create Work order through next path: Dashboard => Request Service. ## Request body - ServiceChannelServicesMessagingWorkordersCreateWoRequest: CreateWoRequest - `Number` string: Work Order Number - `PurchaseNumber` string: Purchase Order Number - `HasTruncatedDescription` boolean: Optional - `ContractInfo` ServiceChannelServicesMessagingWorkordersContractInfo, required: ContractInfo (composite object) - describes who, where and what will perform as well as the one who requested work - `SubscriberId` integer, required: Required for provider request (for subscriber request filled authomatically), must belong to existing subscriber - `LocationId` integer, required: Required if 'StoreId' not passed, must belong to existing location for specified subscriber. Can be Optional, if EquipmentId is supplied in the request, system picks LocationId of the location that equipment belongs to - `StoreId` string: Optional, can be used instead of 'LocationId'. If 'LocationId' not passed system will attempt to find location based on 'SubscriberId' and 'StoreId' ('StoreId' is required in this case), it is possible that system won't be able to find location which results in error. Many locations can have similar StoreId but LocationId is always unique - `ProviderId` integer: Optional (for provider request filled authomatically), if provided - must correspond to a valid provider that has contract for specified Subscriber, Location and Trade. If not specified the system will attempt to find default provider based on Location, Trade and Equipment (if specified). It is possible that system won't be able to find provider which results in error - `TradeName` string, required: Required, must be a valid trade for specified subscriber. Can be Optional if EquipmentId is supplied in the request, system picks TradeName of the trade that equipment belongs to. This definition is narrower then Category. For example if Category is "Maintenance" then TradeName will be "FLOOR MAINTENANCE" - `TradeId` integer: Required, must be a valid trade id for specified subscriber. - `IsTradeDeleted` boolean - `Comment` string: Optional, Gets or sets the comment. Describes comments in work order - `SetupId` integer: Optional Dashboard Id, UID of dashboard from which this work order was created must be bigger then zero and belong to existing dashboard - `AssetId` integer: Optional Asset, UID of asset, that will be repaired/reinstalled must be present and correspond to valid asset if system finds that asset exists for specified LocationId, TradeName, IssueRequest.EquipmentType params and asset is required for issue choice specified by IssueRequest, SubscriberId and SetupId params - `ReplaceAsset` boolean: Optional - `CallerName` string: Optional, can be empty Caller Name. Name of the person/organization who created work order - `Category` string, required: Required, not empty Category must be valid category for specified subscriber. Describes what type of work will be performed. This definition is broader then TradeName. For example if TradeName is "FLOOR MAINTENANCE" then Category will be "Maintenance" - `CategoryId` integer - `Priority` string: Required, not empty Priority must be valid priority for specified subscriber. Describes work order priority. For example "Normal", "Emergency" - `PriorityId` integer - `Nte` number, double: Required Nte value; optional only for users that have no access to change NTE. (decimal number (e.g. 1.00)) - describes maximum amount of money to be spent on work order. Must not exceed max amount defined by Subscriber. If you specify ExtendedInfo.Tax, ExtendedInfo.Tax2 and ExtendedInfo.Price then Nte must be equal to sum of those three params - `CallDate` string, required: Required, date when work order was created. - `CallDateDto` string, date-time: Date when work order was created in DateTimeOffset format. - `ScheduledDate` string: Optional, calculated based on CallDate and Priority by default. Date when provider will come to perform work order. Must be an actual date (i.e. not 1/1/1900 or 1/1/3001) + must be bigger then CallDate and smaller then ExpirationDate - `ScheduledDateDto` string, date-time: Date when provider will come to perform work order in DateTimeOffset format. - `CompletedDate` string: Optional, WorkDate when its not completed status. - `ProblemSource` string: Optional, source from which the problem came from - `Description` string, required: Required problem description, Must not be empty. Overall description of a problem (e.g. "Coffee machines are broken all over the place - please help!") - `ProblemCode` string, required: Required, describes problem similar to Description attribute, but its value is predefined in subscriber's [IssueList]. - `RecallWorkOrder` integer: Optional, UID of recalled work order. Work order is set as 'recalled' when subscriber isn't satisfied with work that was done by provider - `ServiceNowId` string: Optional, Service Now Id - `CurrencyId` integer: Optional, UID of currency used to pay for work order. Defaul value is '1' which corresponds to USD. Must be bigger then 0 and correspond to valid currency in dashboard which is found by SetupId param - `FollowupWorkOrder` integer: Optional, UID of work order that is created if problem cannot be fully solved in terms of original work order - `ApprovalCode` string: Optional - `IssueRequestInfo` ServiceChannelServicesMessagingWorkordersCreateWoRequestIssueRequest - `AreaId` integer, required: Required, UID of problem area. Must be bigger then zero and belong and belong to existing area - `ExtendedAreaName` string: Optional, area name. Must be not empty - `ProblemType` string: Optional, Type of problem. Must be not empty - `AssetType` string: Optional, type of asset, has predefined values in [IssueList] Must be not empty - `DispatchSettingsInfo` ServiceChannelServicesMessagingWorkordersCreateWoRequestDispatchSettings: describes email notification settings on work order creation - `NotificationDisabled` boolean: Turns on/off email notification when work order is created - `EmailHeader` string: Email Header - `SendAlertToFM` boolean: Send Alert To FM - `ShowLastServiceCall` boolean: Show Last Service Call - `IsTest` boolean: Is Test - `CcRecipients` string: CC Recipients - `InvalidRecipients` string: Invalid Recipients - `Status` ServiceChannelServicesMessagingWorkordersWorkorderStatus - `Primary` 'NotSet' | 'Open' | 'InProgress' | 'Completed' | 'Incomplete', required: Required, primary work order status value - `Extended` string, required: Required, but can be empty. Extended status value - `PrimaryStatusValue` string - `ExtendedInfo` ServiceChannelServicesMessagingWorkordersCreateWoRequestExtendedRequestInfo: ExtendedRequestInfo - `ExpirationDate` string, date-time: Optional, Expiration Date - `GracePeriod` integer: Optional, Grace Period - `Tax` number, double: Optional, Tax - `Tax2` number, double: Optional, Tax2 - `Tax2Type` string: Optional, Tax2Type - `Price` number, double: Optional, Price - `AutoInvoice` boolean: Optional, Auto Invoice - `CallerIdMatch` boolean: Optional, Caller Id Match - `AutoComplete` boolean: Optional, Auto Complete - `AutoDispatch` boolean: Optional, Auto Dispatch - `IsTransferAsset` boolean: Indicates whether the work order has an asset for transfer - `NewLocationIdForAssetTransfer` integer: Identifier of the new location for asset transfer - `AssetTransferCode` integer: Identifier of the reason for asset transfer - `Attachments` ServiceChannelServicesMessagingAttachmentsAddAttachmentRequest[]: Optional, at least one attachement must be present in list if system finds that attachments are required for issue choice specified by IssueRequest, SubscriberId and SetupId params - `Name` string - `Description` string - `Path` string - `Type` 'File' | 'RemoteStorage' - `MediaType` string: Mime type of the attachment - `Visibility` integer: Note visibility - valid values: null, 1, 2, 3 - `IsInvoiceDigitalCopy` boolean: Mark attachment as Invoice Digital Copy - `IsLocationAttachment` boolean: Indicates if the attachment is copied from location - `IgnoreAttachmentsRequiredFlag` boolean - `ApiRequest` boolean - `Materials` ServiceChannelServicesMessagingWorkordersCreateWoRequestMaterial[]: Optional - `Quantity` number, float - `Description` string - `Price` number, double - `Reason` string - `SupplierPartId` string - `SupplierPartAuxiliaryId` string - `SupplierName` string - `NteMultiplier` number, double - `DefaultNte` number, double - `MaterialsUsed` ServiceChannelServicesMessagingRefrigerantTrackingAddWorkOrderPartRefrigerantItem[]: Optional - `AssetId` integer: Unique numeric identifier of the asset to which the new part use records should be added. Only one asset can be processed in the request. For a non-refrigerant part use, the `AssetId` is not required. - `RecId` integer: Unique numeric identifier of the work order associated with the `AssetId`. Only one work order can be processed in the request. - `Quantity` number, double: Quantity of parts used. - `UnitCost` number, double: Cost of each part. - `IsRefrigerant` boolean: Specifies whether the part you are trying to add is classified as a refrigerant. Possible input values: `true` and `false`. - `IsInventoryPart` boolean: Specifies whether the part you are trying to add is listed in the inventory catalog for the location or the part is supplied by the vendor. Possible input values: • `true`: Indicates an inventory part • `false`: Indicates a vendor-supplied part - `InventorySource` string, byte: Specifies Part inventory source option Possible input values: • `0` = InventoryLocation • `1` = ProviderSupplied • `2` = ClientSupplied • `3` = ManualNonInventory - `UseDate` string, date-time: Date and time when the part was used. The format is `YYYY-MM-DDThh:mm:ss.sssZ`. - `UseDateStr` string: Date and time when the part was used. The format is `YYYY-MM-DDThh:mm:ss.sssZ`. - `ReasonCode` integer: Reason code name for the refrigerant part use — as configured by the subscriber. Possible values: • `Leak` • `Repair` • `Adjustment` • `System Expansion` • `Removal` • `Initial Charge` • `Retrofit` • `Removed Reused`
To get the list of reason codes for the subscriber, use the [GET/refrigeranttracking/{subscriberId}/GetRefrigerantUseReasonCodes](https://developer.servicechannel.com/swagger/index.html#/RefrigerantTracking/GETv3_refrigeranttracking_%7BsubscriberId%7D_GetRefrigerantUseReasonCodes) method. - `ReasonCodeId` integer: Unique numeric identifier of the refrigerant use reason code. To get the list of reason code IDs for the subscriber, use the [GET/refrigeranttracking/{subscriberId}/GetRefrigerantUseReasonCodes](https://developer.servicechannel.com/swagger/index.html#/RefrigerantTracking/GETv3_refrigeranttracking_%7BsubscriberId%7D_GetRefrigerantUseReasonCodes) method. - `PartNumber` string: Part number. Shouldn’t exceed 50 characters. - `PartName` string: Part name. Shouldn’t exceed 100 characters. - `PartGroup` string: Part group. Required only if the `IsRefrigerant` is set to `true`. - `PartGroupId` integer: Unique numeric identifier of the part group. Required only if the `IsRefrigerant` is set to `true`. - `SupplierName` string: Name of a company that supplies the part. - `Description` string: Part description. Any additional information on the part. Shouldn’t exceed 250 characters. - `RefrigerantChargeOptionsId` integer: Unique numeric identifier of the charge method used. Possible values: • `1`: Calculation • `2`: Established • `3`: Manufacturer Tag • `4`: Measurement • `5`: MFG Info (Established Range) • `6`: Onsite Documentation • `7`: Approximate
To get charge options and their IDs, use the [GET/refrigeranttracking/ChargeDescriptions](https://developer.servicechannel.com/swagger/index.html#/RefrigerantTracking/GETv3_refrigeranttracking_ChargeDescriptions) method. - `RefrigerantChargeVendor` string: Provider who identified the initial charge of the system. Only applicable when the `ReasonCode` is set to `Initial Charge`. - `InventoryLocationId` integer: Unique numeric identifier of the inventory location where the inventory part is stored. - `InventoryLocationGuid` string: GUID of the inventory location. - `InventoryPartId` integer: Unique numeric identifier of the inventory part. To get the inventory part ID, use the [GET/Setup/parts](https://inventoryapi.servicechannel.com/swagger/index.html) method. - `RefrigerantUseReason` ServiceChannelServicesMessagingRefrigerantTrackingRefrigerantUseReasonCode: Object containing refrigerant use reasons. - `Id` integer: Unique numeric identifier of the refrigerant use reason code. - `Order` integer: Order of appearance of a reason code. - `Purpose` integer: Unique numeric identifier of the reason code for the refrigerant part use. Possible values: `0` - Leak, `1` - InitialCharge, `2` - SystemExpansion, `3` - Removal, `4` - Other, `5` - RemovedReused, `6` - Retrofit.
Each reason code on the subscriber side is associated with a hardcoded purpose value in the database. Since reason codes can vary across subscribers, the purpose helps identify the valid reason code.
***Note:*** Purpose value `0` is assigned to the `Leak` and `Repair` reason codes, indicating that a leak record gets calculated for these reason codes. - `Name` string: Reason code name for the refrigerant part use as configured by the subscriber. Possible values: • `Leak` • `Repair` • `Adjustment` • `System Expansion` • `Removal` • `Initial Charge` • `Retrofit` • `Removed Reused` - `SubscriberId` integer: Unique numeric identifier of the subscriber. - `IsActive` boolean: Defines whether a user can select a reason code when capturing refrigerant use. Possible response values: • `true`: Reason code is enabled. • `false`: Reason code is disabled. - `RefrigerantRemovalStatus` 'Destroyed' | 'Reused' | 'Reclaimed' | 'Banked' | 'ChargeLost' | 'Sold': Status that describes what was done with the removed refrigerant in the event of the retrofit plan: • `Destroyed` • `Reused` • `Reclaimed` • `Banked` • `ChargeLost` • `Sold`
***Note:*** Applicable for the retrofit plan.
Not recommended for use in this request. - `RefrigerantTypeId` integer: Unique numeric identifier of the refrigerant type. To get the list of refrigerant types and their IDs, run the [GET/refrigeranttracking/RefrigerantTypes](https://developer.servicechannel.com/swagger/index.html#/RefrigerantTracking/GETv3_refrigeranttracking_RefrigerantTypes%3FsubscriberId%3D%7BsubscriberId%7D) method. - `RefrigerantTypeName` string: Refrigerant type name. - `SubmitMoeQtyExceeded` boolean: For Canadian locations. When the part use meets or exceeds the threshold, set the parameter’s value to `true` to be able to proceed with the request. - `MoeNumber` string: Agency number that will be assigned to the work order and the leak record. The number can be up to 20 characters. An agency number needs to be entered when the system threshold has been met or exceeded. For Canadian locations only.
Available with the *SCP_RTCanadaRefrigeration* feature flag. - `IsRetrofit` string, byte: Specifies whether the part use is associated with a retrofit plan. Possible values: • `true`: The part is linked to a retrofit plan. The `RefrigerantRemovalStatus` should be specified. • `false`: The part isn’t associated with a retrofit plan.
Not recommended for use in this request. - `RefrigerantSourceTypeId` integer: Unique numeric identifier of the refrigerant source type. To get the list of refrigerant source types and their IDs, run the [GET/refrigeranttracking/refrigerantSourceTypes](https://developer.servicechannel.com/swagger/index.html#/RefrigerantTracking/GETv3_refrigeranttracking_refrigerantSourceTypes) method.
Is required when *RTRefrigeSourceType* feature flag is enabled for the subscriber. - `AdditionalFields` ServiceChannelServicesMessagingWorkordersCreateWoRequestAdditionalField[]: Interactive troubleshooting additional fileds - `Name` string: Additional Field Name - `Value` string: Additional Field Value - `IssueListHeaderId` integer: Optional. Id in dash_IssueListHeader table - `ProposedNte` number, double: Optional - `NotifyProvider` boolean: Optional - `IsDashboardRequest` boolean: Optional - `FloorPlansImagePath` string: Optional - `AssigneeUserId` integer: Optional - `SessionId` string: SessionId to link work order with feedback session - `ProjectId` integer: Optional. Project Id from Project Tracker - `WeatherTypeId` integer: Optional. Associate with a specific weather type - `LabelId` integer: Optional, Label Id - `Labels` string[]: Optional, Labels names - `AdditionalApprovalCodesList` object: Additional Approval Codes List with id as a key - `LeaseNote` string - `UserName` string - `UserId` integer - `WorkFlowTypeId` integer - `EstimatedCompletionDate` string, date-time - `IsAnomalyProviderOverwritten` boolean: Flag to show that Anomaly Override has happened. - `Anomaly` ServiceChannelApiModelWorkordersOverridePropertiesAnomaly - `TradeAnomalous` boolean - `TradeScore` number, double - `NTEAnomalous` boolean - `NTEScore` number, double - `FirstTimeFixAnomalous` boolean - `FirstTimeFixScore` number, double - `Top1PrimaryTrade` string - `InvoiceTotalWithoutProposal25` number, double - `InvoiceTotalWithoutProposalMedian` number, double - `InvoiceTotalWithProposal75` number, double - `IsAnomaly` boolean - `DecisionAnswers` DecisionAnswer[]: See {ServiceChannel.Services.Messaging.Workorders.GetWorkOrderPropertiesRequest.DecisionAnswers} for details - `Id` string - `Answer` string - `AssetNotListed` boolean - `SpaceId` integer - `LocationPath` string - `ContractServiceRate` ServiceChannelApiModelWorkordersContractRatesSaveWorkOrderContractServiceRateRequest - `ContractedServiceRateId` integer - `Name` string - `BaseAmount` number, double - `VariableAmount` number, double - `CurrencyId` integer - `UpdateSource` string ## Response `201` Created indicates that the request resulted in a new resource created before the response was sent. ## Other responses - `400`: Bad Request - the request could not be understood or was missing required parameters.
Error codes:
100 - No provider was found for specified location and trade;
300 - Missed contract data;
301 - Contract not found for specified subscribers location, provider and trade;
400 - Invalid Subscriber Id specified;
503 - Work order cannot be created, provider could not be determined (missing providerID or IssueRequestInfo);
600 - Invalid Location Id specified;
603 - Subscriber has no specified Location;
700 - Invalid Trade Name specified;
702 - Subscriber has no specified Trade;
800 - Missed required argument 'UserId';
801 - Missed required argument 'CreatedBy';
900 - Missed problem description options;
901 - Missed required argument 'ProblemSource';
902 - Missed required argument 'Description';
903 - Missed required argument 'ProblemCode';
904 - Invalid WorkOrder status;
905 - Invalid 'Nte' value;
906 - Invalid 'CallerName' value;
907 - Invalid 'CallDate' value;
908 - Invalid 'ScheduledDate' value;
909 - Invalid 'ScheduledDate', greater than max allowed by subscriber;
910 - Missed required argument 'Category';
911 - Invalid 'Category';
912 - Missed required argument 'Priority';
913 - Invalid 'Priority';
914 - Invalid 'Currency' value;
915 - Invalid Setup Id;
916 - At least one attachment required to create this WorkOrder;
918 - Assets required to create this WorkOrder; - `401`: Indicates that the requested resource requires authentication.
Error codes:
504 - API call rejected by security permissions; - `500`: Indicates that a generic error has occurred on the server.
Error codes:
501 - Sequence contains no elements --- [API](https://skmtc.dev/servicechannel/apis/servicechannel-api-v-3.md) - [All operations](https://skmtc.dev/servicechannel/apis/servicechannel-api-v-3/llms.txt) - [OpenAPI document](https://skmtc.dev/servicechannel/apis/servicechannel-api-v-3/revisions/d490d6596809?raw)