Create a service

This endpoint enables the creation of a new service within the business.

POST /api/v2/businesses/{businessId}/services

Below is a detailed explanation of each field that can be included in the request body. Some of them are required for the request to be processed successfully.

Required fields are marked with an asterisk (*).

Request body

JSON Analysis 
{
  "newServiceOuterId": "string",
  "newServiceName": "string",
  "copyFromServiceOuterId": "string",
  "timeZone": "string",
  "firstDayOfWeek": 1,
  "parentOuterId": "string"
}
Details

  • newServiceOuterId: external identifier of the new service. Although not mandatory, it is recommended to define it so it can be used in future integration operations. It must be unique within the business.

  • newServiceName*: name of the new service.

  • copyFromServiceOuterId: external identifier of the service to be used as a reference if a copy is to be made.

  • timeZone*: time zone in which the service will be created. It is mandatory to provide a TZ identifier from this list.

  • firstDayOfWeek*: first day of the week. It is mandatory to include a value from 1 (Monday) to 7 (Sunday).

  • parentOuterId*: external identifier of the node to which the service will be linked.

Request example

After analyzing the different fields, here is an example of the request body:

{
    "newServiceOuterId": "1327",
    "newServiceName": "STORE 1327",
    "timeZone": "Africa/Freetown",
    "firstDayOfWeek": 1,
    "copyFromServiceOuterId": "0001",
    "parentOuterId": "PN"
}

Considerations

If the external identifier specified for the new service already exists within the business, the request will return a 409 Conflict error with the message ID already exists.

If the name of the new service is not provided, the request will return a 400 Bad Request error with the message newServiceName must not be empty.

If no time zone is provided, or if the one included is not valid, the request will return a 400 Bad Request error with the message Invalid TimeZone.

If the firstDayOfWeek field is not provided or its value is not one of the allowed ones, the request will return a 400 Bad Request error with the message Invalid firstDayOfWeek. Must be an integer between 1 (Monday) and 7 (Sunday).

If the external identifier of the service (copyFromServiceOuterId) or of the node (parentOuterId) does not match any of those configured at the business level, the request will return a 404 Not Found error with the message Node not found.

If parentOuterId is not provided, the request will return a 400 Bad Request error with the message parentOuterId must not be empty.

If the copyFromServiceOuterId field is provided, all dependent entities of the referenced service will be copied: products, locations, zones, employee limits, needs templates, employee distribution, service times, service parameters, regulations, employee roles, etc.

Useful links

What is a service?

What is a node?