PATCH /api/v1/bookings/{bookingId}/details
Reads or edits the public information and private preparation notes for one sales call. Omitted fields remain unchanged; explicit null clears a field.
| Role in the organization | This endpoint |
|---|
OWNER | Allowed with current organization permissions |
ADMIN | Allowed with current organization permissions |
MEMBER | Conditional on the business role and scope below |
| Requirement | Rule for this endpoint |
|---|
| Business role | Assigned closer; setters cannot edit |
| Resource scope | Organization bound to the API key |
| Participation | Call must be visible to the bearer |
| Resource state | No additional state restriction |
Private notes are returned only to owner/admin and the currently assigned closer. Setter responses omit the privateNotes property entirely.
| Parameter | Type | Required | Description |
|---|
bookingId | UUID | yes | Booking identifier |
| Header | Required | Description |
|---|
x-api-key | yes | Organization API key |
X-Correlation-Id | no | Correlation UUID for support |
Idempotency-Key | yes | Stable key for one intention |
Content-Type | yes | application/json |
Request body
| Field | Type | Required | Nullable | Description |
|---|
meetingUrl | string | no | yes | HTTP or HTTPS URL, maximum 2048 characters, no credentials or whitespace |
publicInstructions | string | no | yes | Plain text, maximum 4000 characters |
privateNotes | string | no | yes | Private plain text, maximum 10000 characters; replaces the complete note |
sendUpdateEmail | boolean | no | no | Default false; true only after explicit operator confirmation |
Unknown fields, including organizationId, are refused. At least one editable field must be provided.
curl -X PATCH "$COHORTE_API_BASE_URL/api/v1/bookings/11111111-1111-4111-8111-111111111111/details" \
-H "x-api-key: $COHORTE_API_KEY" \
-H "Idempotency-Key: call-details-001" \
-H "Content-Type: application/json" \
-d '{"meetingUrl":"https://meet.example.com/my-room"}'
200: successful read, save or replay.400: invalid identifier, payload or missing idempotency key.401: invalid key or membership.403: insufficient permissions.404: booking absent or outside this organization.429: rate limit reached.500: unexpected failure.
| Field | Type | Nullable | Description |
|---|
success | boolean | no | Successful request |
data.details.bookingId | UUID | no | Booking identifier |
data.details.meetingUrl | string | yes | Effective link stored on this call |
data.details.publicInstructions | string | yes | Public information |
data.details.privateNotes | string | yes | Private note; property omitted for setters |
data.details.canEdit | boolean | no | Current editing permission |
data.details.hasProspectEmail | boolean | no | Whether a prospect email is available |
data.email.status | string | no | not_requested, sent, skipped, or failed |
data.email.reason | string | yes | log_mode, no_email, delivery_failed, delivery_not_completed, or null |
{
"success": true,
"data": {
"details": {
"bookingId": "11111111-1111-4111-8111-111111111111",
"meetingUrl": null,
"publicInstructions": null,
"privateNotes": null,
"canEdit": true,
"hasProspectEmail": true
},
"email": {
"status": "not_requested",
"reason": null
}
}
}
A mutation records an audit and change event. Reusing the same key does not apply the edit twice. The returned data reflects the current resource; replay does not resend email.
Meeting-link updates appear on the personal public page and newly generated calendar exports. Already imported external events are not synchronized. Notes never appear on the prospect page, emails or calendars. No management link is recovered or replaced.
An update email is attempted only when the link changes and sendUpdateEmail is explicitly true. Ask the operator before setting it. Email failure does not undo the saved call. sent means accepted for sending, not delivered or read. Replies go to the assigned closer through Reply-To. The update email includes its private management link directly, while previous personal links remain valid. A retry resumes the same durable delivery and stable provider idempotency key; delivery_not_completed can indicate an interrupted attempt with uncertain delivery.
The optional update email carries the meeting details and recipient context captured at the approved save. Later changes made without sending do not replace the contents of that already approved email.
All update-email attempts appear in call history with approved content, actor and actual send/result timestamps. Later unsent edits do not change an already approved email snapshot. Personal capabilities are redacted from operator history.
