Appointment

post

https://api.marketcircle.net/v1/appointments

create an appointment

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

📘
Note
If utc_start and utc_end are provided, local_start and local_end values will be ignored. See Times and time zones.

subject and a start and end time are required. Repeating appointments can't be created through the API.

{
  "subject": "Project kickoff",
  "timezone": "America/Toronto",
  "local_start": "2025-04-10T09:15:00",
  "local_end": "2025-04-10T10:15:00",
  "type": "meeting",
  "resources": ["/v1/resources/1000"],
  "invitations": [{ "invitee": "/v1/contacts/2000" }],
  "contacts": [{ "contact": "/v1/contacts/2000" }]
}

A successful request returns 201 Created with the new appointment's reference, e.g. {"location": "/v1/appointments/5000"}. If validation fails, the response is 400 with the errors for each attribute, e.g. {"base": [{"error": "invalid_start_end_date"}]} when the end is not after the start.

Body Params

subject

string

Subject (max 2048 characters). Required.

location

string

Location (max 2048 characters).

details

string

Details (max 8192 characters).

category

string

Category name. Created if it does not exist. Send null or "" to clear.

keywords

array of strings

List of keyword names (max 64). Keywords that do not exist are created. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

keywords

type

string

enum

Appointment type. Defaults to appointment.

status

string

enum

Appointment status. Defaults to other.

Allowed:

all_day

boolean

Whether this is an all-day appointment.

show_as

string

enum

Show the time as busy or free. Defaults to free.

Allowed:

timezone

string

IANA time zone name, e.g. America/Toronto, or floating for an appointment at the same clock time in every time zone.

utc_start

date-time

Start time in UTC, e.g. 2025-04-10T13:15:00Z. Required unless local_start is given.

utc_end

date-time

End time in UTC, e.g. 2025-04-10T14:15:00Z. Must be after the start. Required unless local_end is given.

local_start

string

Start time in the appointment's timezone, without an offset, e.g. 2025-04-10T09:15:00. Ignored if utc_start is also sent.

local_end

string

End time in the appointment's timezone, without an offset, e.g. 2025-04-10T10:15:00. Ignored if utc_end is also sent.

resources

array of strings

References of the resources booked for the appointment, e.g. ["/v1/resources/1000"]. At most 10, and all must be active. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

resources

invitations

array of objects

People invited to the appointment. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

invitations

contacts

array of objects

Contacts linked to the appointment. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

contacts

companies

array of objects

Companies linked to the appointment. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

companies

opportunities

array of objects

Opportunities linked to the appointment. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

opportunities

projects

array of objects

Projects linked to the appointment. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

projects

tasks

array of objects

Tasks linked to the appointment. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

tasks

groups

array of objects

Groups linked to the appointment. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

groups

notes

array of objects

Notes linked to the appointment. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

notes

forms

array of objects

Forms linked to the appointment. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

forms

email_messages

array of objects

Emails to link to the appointment. Write-only: use GET /v1/appointments/{id}/emails to list them. On update, an array replaces the whole list. Send {"add": [...], "remove": [...]} instead to change only some entries.

email_messages

owner

string

Reference to the user responsible for the appointment, e.g. /v1/users/1000. Defaults to the user making the request.

Responses

Note

201201 Created

400400 Bad Request