get
https://api.marketcircle.net/v1/appointments/
List the details of an appointment
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Appointment Attributes
| Attribute Name | Type | Description | Attributes |
|---|---|---|---|
self | reference | URL of the Appointment | Read-only Non-null |
subject | string | Subject (max 2048 characters) | Read-Write Non-null Required Searchable |
timezone | string | IANA time zone name, e.g. America/Toronto, or floating. See Times and time zones | Read-Write Nullable |
all_day | boolean | Whether this is an all-day appointment | Read-Write Non-null |
local_start | datetime | Start time in the appointment's time zone, without an offset, e.g. 2025-04-10T09:15:00 | Read-Write Non-null |
local_end | datetime | End time in the appointment's time zone, without an offset | Read-Write Non-null |
utc_start | datetime | Start time in UTC, e.g. 2025-04-10T13:15:00Z | Read-Write Non-null Searchable |
utc_end | datetime | End time in UTC. Must be after the start | Read-Write Non-null Searchable |
show_as | string | Show the time as "busy" or "free" | Read-Write Non-null Default value is "free" |
category | string | Category name | Read-Write Nullable Searchable |
resources | array of reference | URLs of the booked Resources. At most 10, and all must be active | Read-Write Nullable Searchable |
keywords | array of string | List of Keywords (max 64) | Read-Write Nullable Searchable |
invitations | array of invitation | Invited users and contacts. See Invitations | Read-Write Nullable Searchable |
contacts | array of link | Linked Contacts | Read-Write Nullable Searchable |
companies | array of link | Linked Companies | Read-Write Nullable Searchable |
groups | array of link | Linked Groups | Read-Write Nullable Searchable |
notes | array of link | Linked Notes | Read-Write Nullable Searchable |
forms | array of link | Linked Forms | Read-Write Nullable Searchable |
opportunities | array of link | Linked Opportunities | Read-Write Nullable Searchable |
projects | array of link | Linked Projects | Read-Write Nullable Searchable |
tasks | array of link | Linked Tasks | Read-Write Nullable Searchable |
type | string | The type of appointment. See Appointment types | Read-Write Non-null Default value is "appointment"Searchable |
status | string | The status of the appointment. See Appointment statuses | Read-Write Non-null Default value is "other"Searchable |
location | string | Location (max 2048 characters) | Read-Write Nullable Searchable |
details | string | Details (max 8192 characters) | Read-Write Nullable |
owner | reference | URL of the User responsible for the appointment | Read-Write Non-null Default value is the user making the request Searchable |
creator | reference | URL of the User that created the appointment | Read-only Non-null Searchable |
trashed | boolean | Whether the appointment is in the trash. Set to false to restore it | Read-only Non-null |
create_date | datetime | When the appointment was created | Read-only Non-null Searchable |
modify_date | datetime | When the appointment was last updated | Read-only Non-null Searchable |
Appointment types
"appointment" | Normal Appointment |
"event" | An event |
"outbound_call" | An outbound call |
"inbound_call" | An inbound call |
"chat" | A chat |
"vacation" | A vacation |
"meeting" | A meeting |
"video" | A video call appointment |
Appointment statuses
"other" | Other type of status |
"tentative" | The Appointment is tentative |
"confirmed" | The Appointment has been confirmed |
"postponed" | The Appointment has been postponed |
"completed" | The Appointment has been completed |
"cancelled" | The Appointment has been cancelled |
Times and time zones
Every appointment has both UTC times (utc_start, utc_end) and local times (local_start, local_end) in its timezone. You can set either pair; if you send both, the UTC times are used. Local times have no offset, e.g. 2025-04-10T09:15:00; UTC times end in Z, e.g. 2025-04-10T13:15:00Z.
A floating appointment has no time zone: it happens at the same clock time wherever you are, and its local and UTC times are the same.
Invitations
Each entry in invitations looks like this:
{ "invitee": "/v1/users/1000", "status": "accepted", "note": "Running late", "type": "internal" }Invited users are notified.
Users who can see an appointment but not edit it can still send an update containing only invitations, to add invitees or to change their own invitation's status.