Appointments API | Genaya API Reference

Core

Appointments

Schedule entries - appointments, projects, service calls, visits.

GET/appointments

List appointments

Returns a cursor-paginated list of appointments for the authenticated organization. Soft-deleted appointments are excluded. Results are ordered by document id for stable, complete cursor coverage; each object carries its own createdAt for client-side sorting. Requires scope: appointments:read.

Response 200

No fields.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/appointments \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "9Kd2pXq7Lm4",
      "object": "appointment",
      "appointmentId": 1042,
      "uuid": "K7QF3M",
      "clientId": "4Bf1nWq2Jp9",
      "clientFullName": "Dana Whitfield",
      "firstName": "Dana",
      "lastName": "Whitfield",
      "company": "Whitfield HVAC",
      "phone": "+15125550101",
      "email": "dana@example.com",
      "appointmentType": "Diagnostic Visit",
      "appointmentTypeId": "at_diag_01",
      "description": "AC not cooling on the second floor.",
      "address": {
        "line1": "123 Market St",
        "city": "Austin",
        "state": "TX",
        "zip": "78701",
        "country": "US"
      },
      "fullAddress": "123 Market St, Austin, TX, 78701, US",
      "serviceArea": "North Austin",
      "serviceAreaId": "sa_north",
      "companyId": "co_main",
      "companyName": "Whitfield HVAC LLC",
      "team": [
        {
          "id": "tm_8c1f0a",
          "name": "Jordan Rivera"
        }
      ],
      "status": "Scheduled",
      "tags": [
        "VIP",
        "Follow-up"
      ],
      "customFields": {
        "cf_priority": "High"
      },
      "startAt": "2026-06-20T15:00:00.000Z",
      "endAt": "2026-06-20T16:00:00.000Z",
      "createdAt": "2026-06-17T12:00:00.000Z",
      "updatedAt": "2026-06-17T12:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": ""
}

POST/appointments

Create an appointment

Creates a new appointment for the authenticated organization. The organizationId and the creating actor are derived from the API key context and can never be set from the request body. Per-organization required-field configuration is enforced and returns 422 when a configured required field is missing. Supports the Idempotency-Key header for safe retries. Requires scope: appointments:write.

Request body

FieldTypeDescription

clientId

string

Link the appointment to an existing client by id (GET /v1/clients). The client's name, phone, email and address fill any of those fields you leave blank. An id that is not one of your clients is rejected with 422. When omitted, a client is upserted from the supplied contact fields.

clientFullName

string

Full client name. When omitted, it is computed from firstName + lastName.

firstName

string

lastName

string

company

string

phone

string

secondaryPhone

string

email

string

appointmentType

string

appointmentTypeId

string

Appointment type id (GET /v1/appointment-types). Fills `appointmentType` from the record; an unknown id is rejected with 422.

leadSource

string

leadSourceId

string

Lead source id (GET /v1/lead-sources). Fills `leadSource` from the record; an unknown id is rejected with 422.

description

string

address

object

Canonical address sub-object. Emitted only when at least one address field is present; individual keys are omitted when empty.

line1

string

Street address line.

unit

string

Unit, apartment, or suite.

city

string

state

string

zip

string

country

string

fullAddress

string

Full address string. When omitted, it is recomputed from the address sub-object.

serviceArea

string

serviceAreaId

string

Service area id (GET /v1/service-areas). Fills `serviceArea` from the record; an unknown id is rejected with 422.

companyId

string

Id of the organization company to bill the appointment from (GET /v1/companies). The company's name and logo are filled in; an unknown id is rejected with 422. Empty string clears it.

companyName

string

Display name of the billed-from organization company.

team

array of object

Team members to assign. Give each member's `id` from GET /v1/team (the name is filled in from the roster); an id that is not a member of your organization is rejected with 422. A name-only item is kept as a label. Send an empty array to unassign everyone.

id

string

Team member id (teamId).nullable

name

string

nullable

role

string

The member's role as stored on the assignment (read-only; absent when unknown).

status

string

tags

array of string

Tag names/ids to apply to the appointment.

customFields

object

vendorId

string

Assign a vendor / subcontractor by id (GET /v1/vendors). The vendor's name is filled in automatically. Empty string clears the vendor. An id that does not belong to your organization is rejected with a 422 validation_error naming `vendorId`.

vendor

string

Vendor display name. Optional when `vendorId` is given (the record's name is used). Sent alone, it is matched case-insensitively against your vendors so the id is linked when one exists; otherwise it is kept as free text.

subStatus

string

Sub status NAME configured in the organization (case-insensitive; the one under the appointment's `status` is preferred when several share a name). Unknown names are rejected with 422. Empty string clears it.

tagIds

array of string

Tag ids (GET /v1/tags). May be combined with `tags` (names); both are stored as the organization's tag records. An unknown id is rejected with 422 naming `tagIds`.

addTags

array of string

PATCH only. Tag names to ADD without touching the existing tags. Cannot be combined with `tags`.

removeTags

array of string

PATCH only. Tag names to REMOVE, matched case-insensitively. Cannot be combined with `tags`.

startAt

string <date-time>

Appointment start time (ISO-8601, Date, or epoch millis).

endAt

string <date-time>

Appointment end time (ISO-8601, Date, or epoch millis).

timezone

string

IANA time zone the appointment's wall-clock times are in (validated; 400 on an unknown zone). Empty string clears it.

total

number

Grand total of the appointment, tax-inclusive, for an appointment WITHOUT line items (a quoted price). When the appointment carries a tax rate the tax is split back out (subtotal and taxTotal follow); otherwise the stored tax is kept and the subtotal is the remainder. The balance follows the total and keeps what was already collected. An appointment with line items answers 422 - its totals come from the items. Also accepted as a numeric string ("189.00").

subtotal

number

Subtotal before tax, for an appointment without line items. Send it with taxTotal to set both exactly (total becomes their sum); alone, the stored tax is kept.

taxTotal

number

Tax total, for an appointment without line items. With total, the subtotal is the remainder; alone, the stored subtotal is kept.

employeeCost

number

Team cost of the appointment (what the team is paid for it). Reduces the commission base.

companyCost

number

Company cost of the appointment (parts, materials, subcontractors). Reduces the commission base.

lineItems

array of object

Priced work on the appointment. The whole list is REPLACED (send every line); subtotal, taxTotal and total are computed from the lines exactly as the app does, and the balance follows the total. Send `[]` to make the appointment itemless again (its totals stay). Do not send total / subtotal / taxTotal next to lines (422). A line without taxRate inherits the applied tax when it is taxable; when the body applies a tax, every taxable line is rewritten to it. unitCost is accepted only from keys that can read cost; a catalog line's cost comes from the price book otherwise.

entryId

string

Keep the id from GET to update a line in place (tracked-product links survive).

itemId

string

Price book item id, when the line comes from the catalog.

namerequired

string

description

string

quantityrequired

number

unitPricerequired

number

unitCost

number

taxable

boolean

Defaults to true.

taxRate

string

Percent like "10%", a number 0-100, or a fraction 0-1.

type

string

appliedTaxId

string

Apply one of the assigned company's taxes (Operations -> Taxes; the company comes from companyId). Fills appliedTaxName and taxRate, rewrites every taxable line to the rate, and re-derives the tax of an itemless job from its subtotal. null clears the tax. 422 on an unknown id or when the appointment has no company.nullable

appliedTaxName

string

Free-text tax label; filled from the tax record when appliedTaxId is sent.nullable

taxRate

string

A rate without a tax record - a percent like "8.25" or "8.25%" (a number above 1 is a percent, 1 or below a fraction). null clears it.nullable

balance

number

What the client still owes (a payment recorded elsewhere, a deposit, a write-off). Never above the total. When omitted the balance follows the total and keeps what was already collected.

currency

string

ISO 4217 code (3 letters, like USD). Empty string clears it.

terms

integer

Payment terms in days. null clears it.

note

string

Add ONE note to the appointment, signed by the API key's owner (also accepted as { text }). It is a real note: it appears in the Notes panel of the appointment in Genaya and comes back in `notes` with its id.

notes

array of string

A list of notes (strings or { text } objects). On POST it seeds the new appointment's notes. On PATCH it REPLACES the notes that were added through the API; a note somebody typed in Genaya is never removed by it. To change or remove one note, use /appointments/{id}/notes/{noteId}.

latitude

number

Coordinates of the address - send latitude and longitude together (both null to clear).nullable

longitude

number

nullable

startAtLocal

string

Alias of startAt in the org-local wall-clock spelling the response uses ("YYYY-MM-DD HH:MM:SS"). startAt wins when both are sent.

endAtLocal

string

Alias of endAt (org-local wall clock).

createdById

string

POST only - the team member who booked the appointment (GET /v1/team). Defaults to the API key's owner. 422 when not a member of this organization.

createdByName

string

POST only - display name of who booked it, when no member id fits.

Response 201

FieldTypeDescription

id

string

Unique appointment id.

object

string

The object type. Always "appointment".

appointmentId

integer

The organization's sequential numeric appointment id (the number shown in the app), distinct from the opaque `id`. Null when numbering was unavailable at create time.nullable

uuid

string

Short human-shareable appointment code.nullable

clientId

string

Id of the linked client record.nullable

clientFullName

string

Full client/patient name (explicit or derived from first + last).

firstName

string

lastName

string

company

string

phone

string

secondaryPhone

string

email

string

appointmentType

string

appointmentTypeId

string

nullable

leadSource

string

nullable

leadSourceId

string

nullable

description

string

address

object

Canonical address sub-object. Emitted only when at least one address field is present; individual keys are omitted when empty.

line1

string

Street address line.

unit

string

Unit, apartment, or suite.

city

string

state

string

zip

string

country

string

fullAddress

string

serviceArea

string

nullable

serviceAreaId

string

nullable

companyId

string

Id of the organization company the appointment is billed from.nullable

companyName

string

Display name of the billed-from organization company.nullable

team

array of object

Team members assigned to the appointment.

id

string

Team member id (teamId).nullable

name

string

nullable

role

string

The member's role as stored on the assignment (read-only; absent when unknown).

status

string

nullable

tags

array of string

Tag names/ids applied to the appointment.

customFields

object

Organization-defined custom field values, keyed by field id.

startAt

string <date-time>

Appointment start time (ISO-8601).nullable

endAt

string <date-time>

Appointment end time (ISO-8601).nullable

timezone

string

IANA time zone the appointment's wall-clock times were picked against. Absent on records created before time zones were captured.

assignedUserIds

array of string

Team-member ids assigned to this appointment (read-only).

lineItems

array of object

Billable line items. Writable on POST / PATCH - the whole list is replaced and subtotal, tax and total are computed from it (unitCost rides only for keys that can read cost; a line without taxRate inherits the applied tax).

entryId

string

itemId

string

name

string

description

string

quantity

number

unitPrice

number

unitCost

number

taxable

boolean

taxRate

number

amount

number

type

string

subtotal

number

Subtotal before tax. Derived from the line items when the appointment carries any; writable (POST / PATCH) on an appointment without line items.

taxTotal

number

Tax total. Derived from the line items when the appointment carries any; writable on an appointment without line items.

total

number

Grand total (tax-inclusive). Derived from the line items when the appointment carries any; writable on an appointment without line items.

balance

number

Outstanding balance - what the client still owes. Follows the total (what was already collected stays collected) unless the body sends an explicit balance.

appliedTaxId

string

Applied tax id - one of the assigned company's taxes (Operations -> Taxes). Writable; resolving it fills appliedTaxName and taxRate and taxable lines follow it.

appliedTaxName

string

Applied tax name (writable; filled from the tax record when appliedTaxId is sent).

taxRate

string

Applied tax rate as a PERCENT string ("8.25"). Writable - a number above 1 is a percent, 1 or below a fraction.

employeeCost

number

Team cost (writable on POST / PATCH).

companyCost

number

Company cost (writable on POST / PATCH).

currency

string

ISO 4217 currency code (writable).

terms

number

Payment terms in days (writable).

notes

array of object

Every note on the appointment, oldest first - the same notes the Notes panel of the appointment shows in Genaya, whether a person typed them there or an integration added them. Each one carries its id, so it can be corrected or removed through /appointments/{id}/notes/{noteId}. Add one with `note` (or POST /appointments/{id}/notes). A note written through the API before 2026-10-05 may still appear without an id until the next note is written on that appointment.

id

string

The note id. Use it to edit or delete the note.

object

string

appointmentId

string

The id of the appointment the note belongs to.

text

string

The words of the note.

createdByName

string

Who wrote the note (display name). For a note added through the API, the API key's owner.

pinned

boolean

Whether the note is pinned.

createdAt

string <date-time>

updatedAt

string <date-time>

Moves when the note is edited.

lastInvoiceId

string

Doc id of the most recent invoice generated from this appointment (read-only).

lastInvoicedAt

string <date-time>

When the last invoice was generated (read-only).nullable

lastEstimateId

string

Doc id of the most recent estimate generated (read-only).

lastEstimatedAt

string <date-time>

When the last estimate was generated (read-only).nullable

vendorId

string

Id of the assigned vendor / subcontractor (see GET /v1/vendors). Null when unassigned.nullable

vendor

string

Display name of the assigned vendor. Null when unassigned.nullable

subStatus

string

The appointment's sub status name (an organization-configured refinement of `status`). Null when none.nullable

tagIds

array of string

Ids of the appointment's tags (see GET /v1/tags). Companion to `tags`, which carries the names; a legacy free-text tag has a name but no id.

startAtLocal

string

Start time exactly as the calendar shows it, as an org-local wall-clock string ("YYYY-MM-DD HH:MM:SS"). Prefer this for display; `startAt` is the same value rendered as an instant.nullable

endAtLocal

string

End time as an org-local wall-clock string ("YYYY-MM-DD HH:MM:SS").nullable

createdByName

string

Display name of whoever booked the appointment. Writable on POST through createdById (a team member) or createdByName.nullable

latitude

number

Latitude of the appointment address (writable, with longitude).nullable

longitude

number

Longitude of the appointment address (writable, with latitude).nullable

createdAt

string <date-time>

When the appointment was created (ISO-8601).nullable

updatedAt

string <date-time>

When the appointment was last updated (ISO-8601).nullable

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

409Idempotency-Key reused with a different body

422Rejected by a business rule

429Rate limited

500Unexpected server error

curl -X POST https://api.genaya.com/v1/appointments \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "firstName": "Dana",
  "lastName": "Whitfield",
  "phone": "+15125550101",
  "email": "dana@example.com",
  "appointmentType": "Diagnostic Visit",
  "description": "AC not cooling on the second floor.",
  "address": {
    "line1": "123 Market St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  },
  "team": [
    {
      "id": "tm_8c1f0a",
      "name": "Jordan Rivera"
    }
  ],
  "status": "Scheduled",
  "startAt": "2026-06-20T15:00:00.000Z",
  "endAt": "2026-06-20T16:00:00.000Z",
  "total": 189
}'

Example response

{
  "data": {
    "id": "9Kd2pXq7Lm4",
    "object": "appointment",
    "appointmentId": 1042,
    "uuid": "K7QF3M",
    "clientId": "4Bf1nWq2Jp9",
    "clientFullName": "Dana Whitfield",
    "firstName": "Dana",
    "lastName": "Whitfield",
    "company": "Whitfield HVAC",
    "phone": "+15125550101",
    "email": "dana@example.com",
    "appointmentType": "Diagnostic Visit",
    "appointmentTypeId": "at_diag_01",
    "description": "AC not cooling on the second floor.",
    "address": {
      "line1": "123 Market St",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "country": "US"
    },
    "fullAddress": "123 Market St, Austin, TX, 78701, US",
    "serviceArea": "North Austin",
    "serviceAreaId": "sa_north",
    "companyId": "co_main",
    "companyName": "Whitfield HVAC LLC",
    "team": [
      {
        "id": "tm_8c1f0a",
        "name": "Jordan Rivera"
      }
    ],
    "status": "Scheduled",
    "tags": [
      "VIP",
      "Follow-up"
    ],
    "customFields": {
      "cf_priority": "High"
    },
    "startAt": "2026-06-20T15:00:00.000Z",
    "endAt": "2026-06-20T16:00:00.000Z",
    "createdAt": "2026-06-17T12:00:00.000Z",
    "updatedAt": "2026-06-17T12:30:00.000Z"
  }
}

GET/appointments/{id}

Retrieve an appointment

Returns a single appointment by id. A record belonging to another organization returns 404 rather than 403, so this can never confirm cross-tenant existence. Requires scope: appointments:read.

Parameters

Path

idrequired

string

The appointment id.

Response 200

FieldTypeDescription

id

string

Unique appointment id.

object

string

The object type. Always "appointment".

appointmentId

integer

The organization's sequential numeric appointment id (the number shown in the app), distinct from the opaque `id`. Null when numbering was unavailable at create time.nullable

uuid

string

Short human-shareable appointment code.nullable

clientId

string

Id of the linked client record.nullable

clientFullName

string

Full client/patient name (explicit or derived from first + last).

firstName

string

lastName

string

company

string

phone

string

secondaryPhone

string

email

string

appointmentType

string

appointmentTypeId

string

nullable

leadSource

string

nullable

leadSourceId

string

nullable

description

string

address

object

Canonical address sub-object. Emitted only when at least one address field is present; individual keys are omitted when empty.

line1

string

Street address line.

unit

string

Unit, apartment, or suite.

city

string

state

string

zip

string

country

string

fullAddress

string

serviceArea

string

nullable

serviceAreaId

string

nullable

companyId

string

Id of the organization company the appointment is billed from.nullable

companyName

string

Display name of the billed-from organization company.nullable

team

array of object

Team members assigned to the appointment.

id

string

Team member id (teamId).nullable

name

string

nullable

role

string

The member's role as stored on the assignment (read-only; absent when unknown).

status

string

nullable

tags

array of string

Tag names/ids applied to the appointment.

customFields

object

Organization-defined custom field values, keyed by field id.

startAt

string <date-time>

Appointment start time (ISO-8601).nullable

endAt

string <date-time>

Appointment end time (ISO-8601).nullable

timezone

string

IANA time zone the appointment's wall-clock times were picked against. Absent on records created before time zones were captured.

assignedUserIds

array of string

Team-member ids assigned to this appointment (read-only).

lineItems

array of object

entryId

string

itemId

string

name

string

description

string

quantity

number

unitPrice

number

unitCost

number

taxable

boolean

taxRate

number

amount

number

type

string

subtotal

number

Subtotal before tax. Derived from the line items when the appointment carries any; writable (POST / PATCH) on an appointment without line items.

taxTotal

number

Tax total. Derived from the line items when the appointment carries any; writable on an appointment without line items.

total

number

Grand total (tax-inclusive). Derived from the line items when the appointment carries any; writable on an appointment without line items.

balance

number

Outstanding balance - what the client still owes. Follows the total (what was already collected stays collected) unless the body sends an explicit balance.

appliedTaxId

string

Applied tax id - one of the assigned company's taxes (Operations -> Taxes). Writable; resolving it fills appliedTaxName and taxRate and taxable lines follow it.

appliedTaxName

string

Applied tax name (writable; filled from the tax record when appliedTaxId is sent).

taxRate

string

Applied tax rate as a PERCENT string ("8.25"). Writable - a number above 1 is a percent, 1 or below a fraction.

employeeCost

number

Team cost (writable on POST / PATCH).

companyCost

number

Company cost (writable on POST / PATCH).

currency

string

ISO 4217 currency code (writable).

terms

number

Payment terms in days (writable).

notes

array of object

id

string

The note id. Use it to edit or delete the note.

object

string

appointmentId

string

The id of the appointment the note belongs to.

text

string

The words of the note.

createdByName

string

Who wrote the note (display name). For a note added through the API, the API key's owner.

pinned

boolean

Whether the note is pinned.

createdAt

string <date-time>

updatedAt

string <date-time>

Moves when the note is edited.

lastInvoiceId

string

Doc id of the most recent invoice generated from this appointment (read-only).

lastInvoicedAt

string <date-time>

When the last invoice was generated (read-only).nullable

lastEstimateId

string

Doc id of the most recent estimate generated (read-only).

lastEstimatedAt

string <date-time>

When the last estimate was generated (read-only).nullable

vendorId

string

Id of the assigned vendor / subcontractor (see GET /v1/vendors). Null when unassigned.nullable

vendor

string

Display name of the assigned vendor. Null when unassigned.nullable

subStatus

string

The appointment's sub status name (an organization-configured refinement of `status`). Null when none.nullable

tagIds

array of string

Ids of the appointment's tags (see GET /v1/tags). Companion to `tags`, which carries the names; a legacy free-text tag has a name but no id.

startAtLocal

string

Start time exactly as the calendar shows it, as an org-local wall-clock string ("YYYY-MM-DD HH:MM:SS"). Prefer this for display; `startAt` is the same value rendered as an instant.nullable

endAtLocal

string

End time as an org-local wall-clock string ("YYYY-MM-DD HH:MM:SS").nullable

createdByName

string

Display name of whoever booked the appointment. Writable on POST through createdById (a team member) or createdByName.nullable

latitude

number

Latitude of the appointment address (writable, with longitude).nullable

longitude

number

Longitude of the appointment address (writable, with latitude).nullable

createdAt

string <date-time>

When the appointment was created (ISO-8601).nullable

updatedAt

string <date-time>

When the appointment was last updated (ISO-8601).nullable

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/appointments/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "9Kd2pXq7Lm4",
    "object": "appointment",
    "appointmentId": 1042,
    "uuid": "K7QF3M",
    "clientId": "4Bf1nWq2Jp9",
    "clientFullName": "Dana Whitfield",
    "firstName": "Dana",
    "lastName": "Whitfield",
    "company": "Whitfield HVAC",
    "phone": "+15125550101",
    "email": "dana@example.com",
    "appointmentType": "Diagnostic Visit",
    "appointmentTypeId": "at_diag_01",
    "description": "AC not cooling on the second floor.",
    "address": {
      "line1": "123 Market St",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "country": "US"
    },
    "fullAddress": "123 Market St, Austin, TX, 78701, US",
    "serviceArea": "North Austin",
    "serviceAreaId": "sa_north",
    "companyId": "co_main",
    "companyName": "Whitfield HVAC LLC",
    "team": [
      {
        "id": "tm_8c1f0a",
        "name": "Jordan Rivera"
      }
    ],
    "status": "Scheduled",
    "tags": [
      "VIP",
      "Follow-up"
    ],
    "customFields": {
      "cf_priority": "High"
    },
    "startAt": "2026-06-20T15:00:00.000Z",
    "endAt": "2026-06-20T16:00:00.000Z",
    "createdAt": "2026-06-17T12:00:00.000Z",
    "updatedAt": "2026-06-17T12:30:00.000Z"
  }
}

PATCH/appointments/{id}

Update an appointment

Updates an existing appointment. Ownership is verified before any write, so a cross-organization id returns 404. Only the fields supplied in the body are changed (merge semantics). Per-organization required-field configuration is enforced against the post-merge state, so a PATCH cannot blank a configured-required field. Requires scope: appointments:write.

Parameters

Path

idrequired

string

The id of the appointment to update.

Request body

FieldTypeDescription

clientId

string

clientFullName

string

Full client name. When omitted, it is computed from firstName + lastName.

firstName

string

lastName

string

company

string

phone

string

secondaryPhone

string

email

string

appointmentType

string

appointmentTypeId

string

Appointment type id (GET /v1/appointment-types). Fills `appointmentType` from the record; an unknown id is rejected with 422.

leadSource

string

leadSourceId

string

Lead source id (GET /v1/lead-sources). Fills `leadSource` from the record; an unknown id is rejected with 422.

description

string

address

object

Canonical address sub-object. Emitted only when at least one address field is present; individual keys are omitted when empty.

line1

string

Street address line.

unit

string

Unit, apartment, or suite.

city

string

state

string

zip

string

country

string

fullAddress

string

Full address string. When omitted, it is recomputed from the address sub-object.

serviceArea

string

serviceAreaId

string

Service area id (GET /v1/service-areas). Fills `serviceArea` from the record; an unknown id is rejected with 422.

companyId

string

Id of the organization company to bill the appointment from (GET /v1/companies). The company's name and logo are filled in; an unknown id is rejected with 422. Empty string clears it.

companyName

string

Display name of the billed-from organization company.

team

array of object

id

string

Team member id (teamId).nullable

name

string

nullable

role

string

The member's role as stored on the assignment (read-only; absent when unknown).

status

string

tags

array of string

Tag names/ids to apply to the appointment.

customFields

object

vendorId

string

vendor

string

subStatus

string

tagIds

array of string

Tag ids (GET /v1/tags). May be combined with `tags` (names); both are stored as the organization's tag records. An unknown id is rejected with 422 naming `tagIds`.

addTags

array of string

PATCH only. Tag names to ADD without touching the existing tags. Cannot be combined with `tags`.

removeTags

array of string

PATCH only. Tag names to REMOVE, matched case-insensitively. Cannot be combined with `tags`.

startAt

string <date-time>

Appointment start time (ISO-8601, Date, or epoch millis).

endAt

string <date-time>

Appointment end time (ISO-8601, Date, or epoch millis).

timezone

string

IANA time zone the appointment's wall-clock times are in (validated; 400 on an unknown zone). Empty string clears it.

total

number

subtotal

number

Subtotal before tax, for an appointment without line items. Send it with taxTotal to set both exactly (total becomes their sum); alone, the stored tax is kept.

taxTotal

number

Tax total, for an appointment without line items. With total, the subtotal is the remainder; alone, the stored subtotal is kept.

employeeCost

number

Team cost of the appointment (what the team is paid for it). Reduces the commission base.

companyCost

number

Company cost of the appointment (parts, materials, subcontractors). Reduces the commission base.

lineItems

array of object

entryId

string

Keep the id from GET to update a line in place (tracked-product links survive).

itemId

string

Price book item id, when the line comes from the catalog.

namerequired

string

description

string

quantityrequired

number

unitPricerequired

number

unitCost

number

taxable

boolean

Defaults to true.

taxRate

string

Percent like "10%", a number 0-100, or a fraction 0-1.

type

string

appliedTaxId

string

appliedTaxName

string

Free-text tax label; filled from the tax record when appliedTaxId is sent.nullable

taxRate

string

A rate without a tax record - a percent like "8.25" or "8.25%" (a number above 1 is a percent, 1 or below a fraction). null clears it.nullable

balance

number

What the client still owes (a payment recorded elsewhere, a deposit, a write-off). Never above the total. When omitted the balance follows the total and keeps what was already collected.

currency

string

ISO 4217 code (3 letters, like USD). Empty string clears it.

terms

integer

Payment terms in days. null clears it.

note

string

notes

array of string

latitude

number

Coordinates of the address - send latitude and longitude together (both null to clear).nullable

longitude

number

nullable

startAtLocal

string

Alias of startAt in the org-local wall-clock spelling the response uses ("YYYY-MM-DD HH:MM:SS"). startAt wins when both are sent.

endAtLocal

string

Alias of endAt (org-local wall clock).

createdById

string

POST only - the team member who booked the appointment (GET /v1/team). Defaults to the API key's owner. 422 when not a member of this organization.

createdByName

string

POST only - display name of who booked it, when no member id fits.

Response 200

FieldTypeDescription

id

string

Unique appointment id.

object

string

The object type. Always "appointment".

appointmentId

integer

The organization's sequential numeric appointment id (the number shown in the app), distinct from the opaque `id`. Null when numbering was unavailable at create time.nullable

uuid

string

Short human-shareable appointment code.nullable

clientId

string

Id of the linked client record.nullable

clientFullName

string

Full client/patient name (explicit or derived from first + last).

firstName

string

lastName

string

company

string

phone

string

secondaryPhone

string

email

string

appointmentType

string

appointmentTypeId

string

nullable

leadSource

string

nullable

leadSourceId

string

nullable

description

string

address

object

Canonical address sub-object. Emitted only when at least one address field is present; individual keys are omitted when empty.

line1

string

Street address line.

unit

string

Unit, apartment, or suite.

city

string

state

string

zip

string

country

string

fullAddress

string

serviceArea

string

nullable

serviceAreaId

string

nullable

companyId

string

Id of the organization company the appointment is billed from.nullable

companyName

string

Display name of the billed-from organization company.nullable

team

array of object

Team members assigned to the appointment.

id

string

Team member id (teamId).nullable

name

string

nullable

role

string

The member's role as stored on the assignment (read-only; absent when unknown).

status

string

nullable

tags

array of string

Tag names/ids applied to the appointment.

customFields

object

Organization-defined custom field values, keyed by field id.

startAt

string <date-time>

Appointment start time (ISO-8601).nullable

endAt

string <date-time>

Appointment end time (ISO-8601).nullable

timezone

string

IANA time zone the appointment's wall-clock times were picked against. Absent on records created before time zones were captured.

assignedUserIds

array of string

Team-member ids assigned to this appointment (read-only).

lineItems

array of object

entryId

string

itemId

string

name

string

description

string

quantity

number

unitPrice

number

unitCost

number

taxable

boolean

taxRate

number

amount

number

type

string

subtotal

number

Subtotal before tax. Derived from the line items when the appointment carries any; writable (POST / PATCH) on an appointment without line items.

taxTotal

number

Tax total. Derived from the line items when the appointment carries any; writable on an appointment without line items.

total

number

Grand total (tax-inclusive). Derived from the line items when the appointment carries any; writable on an appointment without line items.

balance

number

Outstanding balance - what the client still owes. Follows the total (what was already collected stays collected) unless the body sends an explicit balance.

appliedTaxId

string

Applied tax id - one of the assigned company's taxes (Operations -> Taxes). Writable; resolving it fills appliedTaxName and taxRate and taxable lines follow it.

appliedTaxName

string

Applied tax name (writable; filled from the tax record when appliedTaxId is sent).

taxRate

string

Applied tax rate as a PERCENT string ("8.25"). Writable - a number above 1 is a percent, 1 or below a fraction.

employeeCost

number

Team cost (writable on POST / PATCH).

companyCost

number

Company cost (writable on POST / PATCH).

currency

string

ISO 4217 currency code (writable).

terms

number

Payment terms in days (writable).

notes

array of object

id

string

The note id. Use it to edit or delete the note.

object

string

appointmentId

string

The id of the appointment the note belongs to.

text

string

The words of the note.

createdByName

string

Who wrote the note (display name). For a note added through the API, the API key's owner.

pinned

boolean

Whether the note is pinned.

createdAt

string <date-time>

updatedAt

string <date-time>

Moves when the note is edited.

lastInvoiceId

string

Doc id of the most recent invoice generated from this appointment (read-only).

lastInvoicedAt

string <date-time>

When the last invoice was generated (read-only).nullable

lastEstimateId

string

Doc id of the most recent estimate generated (read-only).

lastEstimatedAt

string <date-time>

When the last estimate was generated (read-only).nullable

vendorId

string

Id of the assigned vendor / subcontractor (see GET /v1/vendors). Null when unassigned.nullable

vendor

string

Display name of the assigned vendor. Null when unassigned.nullable

subStatus

string

The appointment's sub status name (an organization-configured refinement of `status`). Null when none.nullable

tagIds

array of string

Ids of the appointment's tags (see GET /v1/tags). Companion to `tags`, which carries the names; a legacy free-text tag has a name but no id.

startAtLocal

string

Start time exactly as the calendar shows it, as an org-local wall-clock string ("YYYY-MM-DD HH:MM:SS"). Prefer this for display; `startAt` is the same value rendered as an instant.nullable

endAtLocal

string

End time as an org-local wall-clock string ("YYYY-MM-DD HH:MM:SS").nullable

createdByName

string

Display name of whoever booked the appointment. Writable on POST through createdById (a team member) or createdByName.nullable

latitude

number

Latitude of the appointment address (writable, with longitude).nullable

longitude

number

Longitude of the appointment address (writable, with latitude).nullable

createdAt

string <date-time>

When the appointment was created (ISO-8601).nullable

updatedAt

string <date-time>

When the appointment was last updated (ISO-8601).nullable

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

422Rejected by a business rule

429Rate limited

500Unexpected server error

curl -X PATCH https://api.genaya.com/v1/appointments/{id} \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "firstName": "Dana",
  "lastName": "Whitfield",
  "phone": "+15125550101",
  "email": "dana@example.com",
  "appointmentType": "Diagnostic Visit",
  "description": "AC not cooling on the second floor.",
  "address": {
    "line1": "123 Market St",
    "city": "Austin",
    "state": "TX",
    "zip": "78701",
    "country": "US"
  },
  "team": [
    {
      "id": "tm_8c1f0a",
      "name": "Jordan Rivera"
    }
  ],
  "status": "Scheduled",
  "startAt": "2026-06-20T15:00:00.000Z",
  "endAt": "2026-06-20T16:00:00.000Z",
  "total": 189
}'

Example response

{
  "data": {
    "id": "9Kd2pXq7Lm4",
    "object": "appointment",
    "appointmentId": 1042,
    "uuid": "K7QF3M",
    "clientId": "4Bf1nWq2Jp9",
    "clientFullName": "Dana Whitfield",
    "firstName": "Dana",
    "lastName": "Whitfield",
    "company": "Whitfield HVAC",
    "phone": "+15125550101",
    "email": "dana@example.com",
    "appointmentType": "Diagnostic Visit",
    "appointmentTypeId": "at_diag_01",
    "description": "AC not cooling on the second floor.",
    "address": {
      "line1": "123 Market St",
      "city": "Austin",
      "state": "TX",
      "zip": "78701",
      "country": "US"
    },
    "fullAddress": "123 Market St, Austin, TX, 78701, US",
    "serviceArea": "North Austin",
    "serviceAreaId": "sa_north",
    "companyId": "co_main",
    "companyName": "Whitfield HVAC LLC",
    "team": [
      {
        "id": "tm_8c1f0a",
        "name": "Jordan Rivera"
      }
    ],
    "status": "Scheduled",
    "tags": [
      "VIP",
      "Follow-up"
    ],
    "customFields": {
      "cf_priority": "High"
    },
    "startAt": "2026-06-20T15:00:00.000Z",
    "endAt": "2026-06-20T16:00:00.000Z",
    "createdAt": "2026-06-17T12:00:00.000Z",
    "updatedAt": "2026-06-17T12:30:00.000Z"
  }
}

DELETE/appointments/{id}

Delete an appointment

Soft-deletes an appointment (it is marked deleted, never hard-removed). Ownership is verified before the write, so a cross-organization id returns 404. Returns a deletion confirmation object. Requires scope: appointments:write.

Parameters

Path

idrequired

string

The id of the appointment to delete.

Response 200

FieldTypeDescription

id

string

object

string

deleted

boolean

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X DELETE https://api.genaya.com/v1/appointments/{id} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "9Kd2pXq7Lm4",
    "object": "appointment",
    "deleted": true
  }
}

GET/appointments/{id}/notes

List an appointment's notes

Returns every note on the appointment, newest first - the same notes the Notes panel of the appointment shows in Genaya, whether a person typed them there or an integration added them. The list is complete in one response (has_more is always false). An appointment of another organization returns 404. Requires scope: appointments:read.

Parameters

Path

idrequired

string

The id of the appointment.

Response 200

No fields.

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/appointments/{id}/notes \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "object": "list",
  "data": [
    {
      "id": "Hq2mT8vKx1Zp",
      "object": "appointment_note",
      "appointmentId": "9Kd2pXq7Lm4",
      "text": "Gate code 4411.",
      "createdByName": "Jordan Rivera",
      "pinned": false,
      "createdAt": "2026-01-15T09:30:00.000Z",
      "updatedAt": "2026-01-15T09:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

POST/appointments/{id}/notes

Add a note to an appointment

Adds one note, signed by the API key's owner. The note appears in the Notes panel of the appointment in Genaya right away and is returned with its id. Supports the Idempotency-Key header for safe retries. Requires scope: appointments:write.

Parameters

Path

idrequired

string

The id of the appointment.

Request body

FieldTypeDescription

textrequired

string

The words of the note.

Response 201

FieldTypeDescription

id

string

The note id. Use it to edit or delete the note.

object

string

appointmentId

string

The id of the appointment the note belongs to.

text

string

The words of the note.

createdByName

string

Who wrote the note (display name). For a note added through the API, the API key's owner.

pinned

boolean

Whether the note is pinned.

createdAt

string <date-time>

updatedAt

string <date-time>

Moves when the note is edited.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X POST https://api.genaya.com/v1/appointments/{id}/notes \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
  "text": "Customer asked for a morning visit."
}'

Example response

{
  "data": {
    "id": "Hq2mT8vKx1Zp",
    "object": "appointment_note",
    "appointmentId": "9Kd2pXq7Lm4",
    "text": "Gate code 4411.",
    "createdByName": "Jordan Rivera",
    "pinned": false,
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  }
}

GET/appointments/{id}/notes/{noteId}

Retrieve a note

Returns one note of the appointment. A note that was deleted, belongs to another appointment or to another organization returns 404. Requires scope: appointments:read.

Parameters

Path

idrequired

string

The id of the appointment.

noteIdrequired

string

The id of the note.

Response 200

FieldTypeDescription

id

string

The note id. Use it to edit or delete the note.

object

string

appointmentId

string

The id of the appointment the note belongs to.

text

string

The words of the note.

createdByName

string

Who wrote the note (display name). For a note added through the API, the API key's owner.

pinned

boolean

Whether the note is pinned.

createdAt

string <date-time>

updatedAt

string <date-time>

Moves when the note is edited.

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X GET https://api.genaya.com/v1/appointments/{id}/notes/{noteId} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "Hq2mT8vKx1Zp",
    "object": "appointment_note",
    "appointmentId": "9Kd2pXq7Lm4",
    "text": "Gate code 4411.",
    "createdByName": "Jordan Rivera",
    "pinned": false,
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  }
}

PATCH/appointments/{id}/notes/{noteId}

Edit a note

Corrects the words of a note and / or pins it. Any note on the appointment can be edited, including one a person typed in Genaya. The change shows in the Notes panel of the appointment right away. Requires scope: appointments:write.

Parameters

Path

idrequired

string

The id of the appointment.

noteIdrequired

string

The id of the note.

Request body

FieldTypeDescription

text

string

The corrected words of the note.

pinned

boolean

Pin or unpin the note.

Response 200

FieldTypeDescription

id

string

The note id. Use it to edit or delete the note.

object

string

appointmentId

string

The id of the appointment the note belongs to.

text

string

The words of the note.

createdByName

string

Who wrote the note (display name). For a note added through the API, the API key's owner.

pinned

boolean

Whether the note is pinned.

createdAt

string <date-time>

updatedAt

string <date-time>

Moves when the note is edited.

Errors

400Malformed or missing parameters

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X PATCH https://api.genaya.com/v1/appointments/{id}/notes/{noteId} \
  -H "Authorization: Bearer gny_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Customer asked for an afternoon visit.",
  "pinned": false
}'

Example response

{
  "data": {
    "id": "Hq2mT8vKx1Zp",
    "object": "appointment_note",
    "appointmentId": "9Kd2pXq7Lm4",
    "text": "Gate code 4411.",
    "createdByName": "Jordan Rivera",
    "pinned": false,
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  }
}

DELETE/appointments/{id}/notes/{noteId}

Delete a note

Removes a note from the appointment. It leaves the Notes panel in Genaya and every notes list of the API. Returns a deletion confirmation object. Requires scope: appointments:write.

Parameters

Path

idrequired

string

The id of the appointment.

noteIdrequired

string

The id of the note.

Response 200

FieldTypeDescription

id

string

object

string

deleted

boolean

Errors

401Bad, missing, or revoked key

402The prepaid balance has nothing left for API requests past the included pool, or the trial requests are used up

403Lacks scope, plan without API access, live key on a trial, test key writing, or feature switched off

404No such resource in this organization

429Rate limited

500Unexpected server error

curl -X DELETE https://api.genaya.com/v1/appointments/{id}/notes/{noteId} \
  -H "Authorization: Bearer gny_live_xxx"

Example response

{
  "data": {
    "id": "Hq2mT8vKx1Zp",
    "object": "appointment_note",
    "deleted": true
  }
}