Cancel appointment · Vene Docs

Cancel an existing appointment.

POST/v1/actions

typecancel_appointment

Input

patientobjectRequired
Who the visit is for.
refstringRequired
Your ID for the patient. Vene uses it to match callbacks. Up to 255 characters.
first_namestringRequired
As the place has it on file. Up to 120 characters.
last_namestringRequired
As the place has it on file. Up to 120 characters.
date_of_birthdateRequired
Places check it with the name.
appointmentobjectRequired
The appointment to cancel.
starts_attimestampRequired
duration_minutesinteger
1 to 1,440.
provideranyRequired
Needs npi or practice, so Vene can find the office.
locationobject
line1stringRequired
Street address. Up to 255 characters.
line2string
Suite or unit. Up to 255 characters.
citystringRequired
Up to 120 characters.
statestringRequired
Such as CA. Two-letter state code.
postal_codestringRequired
Five-digit ZIP code. 5 digits.
confirmation_numberstring
Up to 64 characters.
arrival_instructionsstring
Up to 2,000 characters.
max_feeobject
The most the patient will pay to cancel; 0 means no fee. Omit it and Vene cancels and reports any fee.
amount_centsintegerRequired
Whole cents.
currencyenumRequired
Always USD.
Possible values
USDUS dollars.

Returns

The action, with this result once it ends.

summarystring
What happened, in a sentence or two. Up to 2,000 characters.
failure_reasonenum, nullable
Why it failed. Null unless failed.
Possible values
- patient_authorization_requiredThe place needs the patient herself to authorize it.
- place_would_not_helpThe place would not discuss it with Vene.
- place_unreachableClosed, never answered, or no working number.
- declined_by_youYou declined something the action needed.
- fee_over_maxThe fee was over max_fee. The result names it.
- internal_errorA Vene fault.
next_stepstring, nullable
What you could do next. Up to 1,000 characters.
cancelledboolean, nullable
Whether the office cancelled it.
cancellation_feeobject, nullable
What the office will charge.
amount_centsinteger
Whole cents.
currencyenum
Always USD.
Possible values
USDUS dollars.

Questions

inputtextnumberbooleandatechoice

How to answer them

Calls

cancel_provider_appointment

Errors

400invalid_request
The body or query failed validation.
401unauthorized
The API key is missing, unknown, or revoked.
403forbidden
The key lacks the scope.
409idempotency_conflict
The key was used with a different body.
429rate_limited
Over a limit. Wait for Retry-After.
500internal_error
A Vene fault.

curl -X POST https://api.venehealth.com/v1/actions \
  -H "Authorization: Bearer <api_key>" \
  -H "Idempotency-Key: <idempotency_key>" \
  -H "Content-Type: application/json" \
  --data @- <<'JSON'
{
  "type": "cancel_appointment",
  "input": {
    "patient": {
      "ref": "pt_456",
      "first_name": "Luis",
      "last_name": "Ortega",
      "date_of_birth": "1971-07-02"
    },
    "appointment": {
      "starts_at": "2026-11-03T10:00:00-08:00",
      "provider": {
        "first_name": "Priya",
        "last_name": "Raman",
        "practice": {
          "name": "Bayview Dermatology",
          "address": {
            "line1": "400 Bay St",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94133"
          }
        }
      }
    },
    "max_fee": {
      "amount_cents": 7500,
      "currency": "USD"
    }
  }
}
JSON

const response = await fetch('https://api.venehealth.com/v1/actions', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer <api_key>',
    'Idempotency-Key': '<idempotency_key>',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "type": "cancel_appointment",
    "input": {
      "patient": {
        "ref": "pt_456",
        "first_name": "Luis",
        "last_name": "Ortega",
        "date_of_birth": "1971-07-02"
      },
      "appointment": {
        "starts_at": "2026-11-03T10:00:00-08:00",
        "provider": {
          "first_name": "Priya",
          "last_name": "Raman",
          "practice": {
            "name": "Bayview Dermatology",
            "address": {
              "line1": "400 Bay St",
              "city": "San Francisco",
              "state": "CA",
              "postal_code": "94133"
            }
          }
        }
      },
      "max_fee": {
        "amount_cents": 7500,
        "currency": "USD"
      }
    }
  }),
})
const result = await response.json()

Response 201

{
  "id": "<action_id>",
  "type": "cancel_appointment",
  "status": "succeeded",
  "input": {
    "patient": {
      "ref": "pt_456",
      "first_name": "Luis",
      "last_name": "Ortega",
      "date_of_birth": "1971-07-02"
    },
    "appointment": {
      "starts_at": "2026-11-03T10:00:00-08:00",
      "provider": {
        "first_name": "Priya",
        "last_name": "Raman",
        "practice": {
          "name": "Bayview Dermatology",
          "address": {
            "line1": "400 Bay St",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94133"
          }
        }
      }
    },
    "max_fee": {
      "amount_cents": 7500,
      "currency": "USD"
    }
  },
  "questions": [],
  "result": {
    "summary": "Cancelled the Nov 3 visit with Dr. Raman. The office will bill a $50 late-cancellation fee, under your $75 limit.",
    "failure_reason": null,
    "next_step": null,
    "cancelled": true,
    "cancellation_fee": {
      "amount_cents": 5000,
      "currency": "USD"
    }
  },
  "trail": [
    {
      "id": "<call_id>",
      "call_type": "cancel_provider_appointment",
      "place": {
        "name": "Bayview Dermatology",
        "address": {
          "line1": "400 Bay St",
          "city": "San Francisco",
          "state": "CA",
          "postal_code": "94133"
        },
        "phone": "+14155550162"
      },
      "started_at": "2026-11-02T21:00:10.000Z",
      "ended_at": "2026-11-02T21:03:40.000Z",
      "ended_reason": "completed"
    }
  ],
  "created_at": "2026-11-02T21:00:00.000Z",
  "updated_at": "2026-11-02T21:03:55.000Z",
  "ended_at": "2026-11-02T21:03:55.000Z"
}