# Create a New Appointment

Creates a standard Appointment or an Appointment in a Group Event.
For a standard Appointment, `staff_id`, `services`, `client`, `datetime`, and
`seance_length` are required.
For a Group Event Appointment, `activity_id` and `client` are required. The API
obtains `staff_id`, `services`, `datetime`, and `seance_length` from the Group Event.
To set custom Appointment Fields, pass an object in `custom_fields`, with each key
matching a field code configured for the Location. The Business User must have both
`custom_fields_record_values_read_access` and
`custom_fields_record_values_edit_access`.

Endpoint: POST /locations/{location_id}/appointments
Version: 1.0.0
Security: BearerPartnerUser

## Security:

  - `BearerPartnerUser` (unknown)
    http bearer Bearer {PartnerToken}, User {UserToken}

## Path parameters:

  - `location_id` (number, required)
    location ID

## Header parameters:

  - `Accept` (string, required)
    e.g. application/vnd.api.v2+json

  - `Content-Type` (string, required)
    application/json

  - `Authorization` (string, required)
    Bearer partner_token, User user_token

## Request fields (application/json):

  - `activity_id` (integer)
    Group Event ID. Required for a Group Event Appointment; omit it or use 0 for a standard Appointment. When updating, the value must match the current Appointment.

  - `team_member_id` (number)
    Team Member ID

  - `services` (array)
    Service parameters (id, cost, discount)

  - `services.id` (number)
    Service ID

  - `services.first_cost` (number)
    Initial cost of the service

  - `services.discount` (number)
    Service discount

  - `services.cost` (number)
    The total cost of the service

  - `client` (object)
    Client parameters (phone, name, email)

  - `client.id` (number)
    Existing Client ID. When set, the phone, name and email are taken from the client card.

  - `client.phone` (string)
    Customer phone number

  - `client.name` (string)
    Client name

  - `client.email` (string)
    Client Email

  - `save_if_busy` (boolean)
    Whether to keep the appointment if the time is busy or non-working, or give an error

  - `datetime` (string)
    Date and time of appointment

  - `seance_length` (number)
    Appointment duration in seconds. Includes technical_break_duration. To add a technical break without reducing the service time, increase seance_length by the break delta.

  - `send_sms` (boolean)
    Whether to send SMS with the details of the appointment to the client

  - `comment` (string)
    Appointment Comment

  - `sms_remain_hours` (number)
    Specifies how many hours before the visit an SMS reminder should be sent to the client. Set to 0 if no reminder is needed.

  - `email_remain_hours` (number)
    Specifies how many hours before the visit an email reminder should be sent to the client. Set to 0 if no reminder is needed.

  - `attendance` (number)
    Appointment status (2 - User confirmed the appointment, 1 - User came, services provided, 0 - user waiting, -1 - user did not show)

  - `api_id` (string)
    External system ID

  - `custom_color` (string)
    Appointment color

  - `record_labels` (array)
    Array of post category IDs

  - `resource_instance_ids` (array)
    Resource Instance IDs (for example, a specific room or chair) the Appointment occupies. On update, the list replaces the current one. Unless `save_if_busy` is true, a busy instance returns an error.

  - `master_request` (number)
    Whether the client explicitly requested this Team Member: 1 - requested, 0 - not requested
    Enum: "0", "1"

  - `clients_count` (number)
    Group Event Appointment only: number of seats the Appointment takes. Must fit the Event's remaining capacity and the Location's per-appointment participant limit.

  - `client_agreements` (object)
    Consent flags to save on the client card. Applied only when client agreements are enabled for the Location.

  - `client_agreements.is_newsletter_allowed` (boolean)
    Newsletter consent

  - `client_agreements.is_personal_data_processing_allowed` (boolean)
    Personal data processing consent

  - `technical_break_duration` (any)
    Technical break duration in seconds.
- Must be in multiples of 300 (5-minute intervals)
- Maximum value is 3600 (1 hour)
- If null or not provided, uses location default from Settings → Appointment Log → Technical Breaks

  - `custom_fields` (object)
    Custom Appointment Field values keyed by field code.
The Business User must have both `custom_fields_record_values_read_access` and
`custom_fields_record_values_edit_access`. When updating an Appointment, supplying
`custom_fields` does not make the request partial: resend the required main fields
for the applicable Appointment type.

  - `custom_fields.my_custom_field` (integer)

  - `custom_fields.some_another_field` (array)

  - `activity_id` (integer)
    Enum: "0"

  - `activity_id` (integer, required)

## Response 201:

  - `201` (unknown)
    Created

## Response 201 fields (application/json):

  - `success` (boolean)
    Execution success status (true)

  - `data` (array)
    Array of objects with data

  - `data.id` (number)
    Appointment ID

  - `data.company_id` (number)
    location ID

  - `data.staff_id` (number)
    team member ID

  - `data.services` (array)
    Array of objects with services in the appointment

  - `data.services.id` (number)
    Service ID

  - `data.services.title` (string)
    Service name

  - `data.services.cost` (number)
    The total cost of the service

  - `data.services.cost_to_pay` (number)
    Amount to pay (cost minus discounts/deposits)

  - `data.services.manual_cost` (number)
    Manual price

  - `data.services.cost_per_unit` (number)
    Unit cost

  - `data.services.discount` (number)
    Discount

  - `data.services.first_cost` (number)
    Initial cost of the service (excluding discounts)

  - `data.services.amount` (number)
    Quantity

  - `data.services.assistants` (array | null)
    Array of assistant team members for this service

  - `data.goods_transactions` (array)
    Array of commodity transactions

  - `data.staff` (object)
    team member data object

  - `data.staff.id` (number)
    team member ID

  - `data.staff.api_id` (string | null)
    team member External ID

  - `data.staff.name` (string)
    team member name

  - `data.staff.specialization` (string)
    team member specialization

  - `data.staff.position` (object | array)
    team member's position

  - `data.staff.position.id` (number)
    Job ID

  - `data.staff.position.title` (string)
    Job title

  - `data.staff.position.services_binding_type` (number)
    Services binding type

  - `data.staff.avatar` (string)
    The path to the file with the team member's avatar

  - `data.staff.avatar_big` (string)
    Let to the file with the team member's profile picture in high resolution

  - `data.staff.rating` (number)
    team member Rating

  - `data.staff.votes_count` (number)
    Number of votes that rated the team member

  - `data.client` (object | null)
    Customer data (may be empty)

  - `data.client.id` (number)
    Client ID

  - `data.client.name` (string)
    Client first name

  - `data.client.surname` (string)
    Client surname

  - `data.client.middle_name` (string)
    Client middle name

  - `data.client.patronymic` (string)
    Client middle name (legacy field name; same value as middle_name)

  - `data.client.display_name` (string)
    Client display name

  - `data.client.comment` (string)
    Client comment

  - `data.client.phone` (string)
    Client phone number

  - `data.client.card` (string)
    Client card number

  - `data.client.email` (string)
    Client email

  - `data.client.success_visits_count` (number)
    Number of successful visits

  - `data.client.fail_visits_count` (number)
    Number of failed visits

  - `data.client.discount` (number)
    Client discount

  - `data.client.is_new` (boolean)
    Is new client flag

  - `data.client.custom_fields` (object | array)
    Client custom fields (object keyed by field code, or empty array when none)

  - `data.client.gender` (number)
    Client gender (0 - not specified, 1 - male, 2 - female)

  - `data.client.sex` (number)
    Client sex (alias for gender: 0 - not specified, 1 - male, 2 - female)

  - `data.client.birthday` (string)
    Client birthday

  - `data.client.client_tags` (array)
    Client tags

  - `data.client.phone_country_id` (number)
    Phone country ID

  - `data.date` (string)
    Session date

  - `data.datetime` (string)
    Session date in ISO

  - `data.create_date` (string)
    Session creation date

  - `data.comment` (string)
    Appointment Comment

  - `data.online` (boolean)
    (Read only) Whether the appointment is online or not (false if the appointment was made by an administrator)

  - `data.visit_attendance` (number)
    Visit status, 2 - The user confirmed the appointment, 1 - The user came, the services were provided, 0 - the user is waiting, -1 - the user did not come to the visit

  - `data.attendance` (number)
    Appointment status, 2 - User confirmed the appointment, 1 - The user has arrived, services have been rendered, 0 - the user is waiting, -1 - the user has not come to visit

  - `data.confirmed` (number)
    Appointment confirmation status, 0 - not confirmed, 1 - confirmed

  - `data.seance_length` (number)
    Appointment duration in seconds. Includes technical_break_duration. Equal to the sum of services plus the technical break.

  - `data.length` (number)
    Appointment duration in seconds. Alias of seance_length. Includes technical_break_duration.

  - `data.sms_before` (number)
    Whether to send an SMS reminder to the client (if the client is specified)

  - `data.sms_now` (number)
    Did you send SMS when adding an appointment

  - `data.sms_now_text` (string)
    SMS text

  - `data.email_now` (number)
    Has an email notification been sent?

  - `data.notified` (number)
    Flag for confirmation of the appointment by the location administrator, if the client asked to confirm the appointment

  - `data.master_request` (number)
    Indicates whether a specific team member was selected for the appointment. Set to false if the "any team member" option was chosen

  - `data.api_id` (string)
    External appointment ID

  - `data.from_url` (string)
    From which page the transition was made to complete the appointment (website, VK application, etc.)

  - `data.review_requested` (number)
    Flag for requesting visit feedback from the client

  - `data.is_remind_sms_sent` (boolean)
    Has reminder SMS been sent

  - `data.visit_id` (number)
    Visit ID

  - `data.created_user_id` (number)
    ID of the user who created the appointment

  - `data.deleted` (boolean)
    (Read only) Whether the appointment was deleted (true if deleted)

  - `data.paid_full` (number)
    Flag, whether the appointment is paid in full (1 - if paid in full)

  - `data.prepaid` (boolean)
    Is online payment available

  - `data.prepaid_confirmed` (boolean)
    Online payment status

  - `data.last_change_date` (string)
    The date and time when the appointment was last modified

  - `data.custom_color` (string)
    Log appointment color

  - `data.custom_font_color` (string)
    (Only when reading) Write font color

  - `data.record_labels` (array)
    Post categories

  - `data.activity_id` (integer)
    Group event ID

  - `data.custom_fields` (object | array)
    Custom fields (object or empty array)

  - `data.documents` (array)
    Array of documents

  - `data.documents.id` (number)
    Document ID

  - `data.documents.type_id` (number)
    Document Type

  - `data.documents.storage_id` (number)
    Inventory ID

  - `data.documents.user_id` (number)
    ID of the user who created the document

  - `data.documents.company_id` (number)
    location ID

  - `data.documents.number` (number)
    Document Number

  - `data.documents.comment` (string)
    Document comment

  - `data.documents.date_created` (string)
    Document creation date

  - `data.documents.category_id` (integer)
    Product category ID

  - `data.documents.visit_id` (integer)
    Visit ID

  - `data.documents.record_id` (integer)
    Appointment ID

  - `data.documents.type_title` (string)
    The name of the entity to which the document belongs

  - `data.documents.is_sale_bill_printed` (boolean)
    Is the sales receipt printed?

  - `data.sms_remain_hours` (number | null)
    How many hours before the start of the visit to send an SMS with a reminder

  - `data.email_remain_hours` (number | null)
    How many hours before the start of the visit to send a reminder email

  - `data.bookform_id` (number)
    Online Appointment Form ID

  - `data.record_from` (string)
    Name of online registration form

  - `data.is_mobile` (number)
    Type of device used to register (0 - appointment created by administrator, via web version or mobile app for administrators, 1 - Mobile browser, online appointment widget, 2 - Desktop browser, online appointment widget)

  - `data.is_sale_bill_printed` (boolean)
    Is the sales receipt printed?

  - `data.consumables` (array)
    Consumable Array

  - `data.finance_transactions` (array)
    Array of financial transactions

  - `data.acceptance_free` (boolean | null)
    Acceptance free flag

  - `data.clients_count` (number)
    Number of clients in appointment

  - `data.comer` (boolean | null)
    Comer flag

  - `data.is_update_blocked` (boolean)
    Update blocked flag

  - `data.payment_status` (string | number)
    Payment status

  - `data.resource_instance_ids` (array)
    Resource instance IDs

  - `data.short_link` (string)
    Short link to appointment

  - `data.short_link_token` (string)
    Token of the Booking User's Appointment page. Returned only when `short_link_token=1` is requested.

  - `data.technical_break_duration` (number)
    Technical break duration in seconds

  - `meta` (object)
    Metadata (contains the page number and the number of appointments per page)

  - `meta.page` (integer)

  - `meta.total_count` (integer)

## Response 401:

  - `401` (unknown)
    Unauthorized

## Response 401 fields (application/json):

  - `success` (boolean)
    Response status.
    Example: false

  - `data` (object | null)
    Response data.
    Example: null

  - `meta` (object)
    Additional response data.

  - `meta.message` (string)
    Error message.
    Example: Authentication needed.

## Response 403:

  - `403` (unknown)
    Forbidden

## Response 403 fields (application/json):

  - `success` (boolean)
    Response status.
    Example: false

  - `data` (object | null)
    Response data.
    Example: null

  - `meta` (object)
    Additional response data.

  - `meta.message` (string)
    Error message.
    Example: Access denied.

## Response 404:

  - `404` (unknown)
    Not Found

## Response 404 fields (application/json):

  - `success` (boolean)
    Response status.
    Example: false

  - `data` (object | null)
    Response data.
    Example: null

  - `meta` (object | array)
    Additional response data (empty object or empty array)
    Example: {}

## Response 422:

  - `422` (unknown)
    Required request data is missing or invalid

## Response 422 fields (application/json):

  - `success` (boolean)
    Response status.
    Example: false

  - `data` (object | null)
    Response data.
    Example: null

  - `meta` (object)
    Additional response data.

  - `meta.message` (string)
    Error message.
    Example: An error has occurred.

  - `meta.errors` (array)
    Set of a validation error messages.