How can we help you?

Advanced documentation search

Create or update a calendar person

Product: FeraCalendar Topic: API Versions: Applies to all documented versions Current
Written by user
Updated

Audience: Application developers
Editorial status: Published — Source Validated
Product: FeraCalendar
Classification: administrative

POST /api/v1/people

Overview

Implements controller.createOrUpdate in routes/api/v1/person/routes.js:8. The authenticated boundary enforces managed-product and owner/member role rules, uses owner-scoped keys/UUIDs, applies visibility masks only after access resolution, and records mutations.

Deprecated compatibility paths

  • POST /api/people

Use the versioned canonical path for new integrations.

Authentication and access

Security scheme: authToken

Control Contract
Authentication authenticated
Authorization The route validates a JWT but does not invoke the available FeraAuth named-permission checker; VIEW/EDIT calendar, person, resource, and event grants are provisioned for owners but are not enforced by this router.
Licensing The global managed-product middleware requires the resolved FeraCal product instance to exist in Active lifecycle state before this route executes.
Instance Context The instance header selects the FeraCal product instance. A trusted API-plane caller may replace it only with signed x-feradel-owner-instance, service, timestamp, and scope-signature headers.
Ownership The command’s owner field defaults to the resolved product instance but, in the current implementation, a caller-supplied owner UUID is used without an equality check against that instance. This is a documented runtime isolation constraint; role checks described for sharing/events still apply.

Parameters

No operation parameters.

Request body

Source-traced FeraCal JSON command.

application/json

Schema: CalMutation

{
    "owner": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
    "key": "person-1001",
    "firstName": "Avery",
    "lastName": "Developer",
    "displayName": "Avery Developer",
    "email": "developer@example.com"
}

Example request

cURL

curl --request POST \ \
  --url 'https://cal.feradel.com/api/v1/people' \
  --header 'x-auth-token: $FERA_AUTH_TOKEN' \
  --header 'content-type: application/json' \
  --data '{"owner":"715c9ebb-0470-11f1-a928-0ed2cd1b87df","key":"person-1001","firstName":"Avery","lastName":"Developer","displayName":"Avery Developer","email":"developer@example.com"}'

Responses

200 The source-traced FeraCal handler completed and returned its calendar, event, person, resource, access, invitation, or lifecycle representation.

Content type: application/json; schema: CalResult

{
    "success": true,
    "item": {
        "uuid": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
        "name": "Client consultation",
        "calendarUuid": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
        "startsAt": "2026-09-01T13:00:00Z",
        "endsAt": "2026-09-01T14:00:00Z",
        "attendees": [],
        "resources": []
    },
    "items": [],
    "uuid": "715c9ebb-0470-11f1-a928-0ed2cd1b87df",
    "visibility": 7
}

400 UUID, key, date range, fields, invite target, or command validation failed.

Content type: application/json; schema: CalError

{
    "success": false,
    "error": {
        "message": "The calendar operation could not be completed.",
        "category": "calendar",
        "number": 800000
    }
}

401 The x-auth-token or lifecycle HMAC is invalid.

Content type: application/json; schema: CalError

{
    "success": false,
    "error": {
        "message": "The calendar operation could not be completed.",
        "category": "calendar",
        "number": 800000
    }
}

403 Managed-product, owner, role, share/inviter, or lifecycle sender permission is missing.

Content type: application/json; schema: CalError

{
    "success": false,
    "error": {
        "message": "The calendar operation could not be completed.",
        "category": "calendar",
        "number": 800000
    }
}

404 The owner-scoped calendar, event, person, resource, or invite target was not found.

Content type: application/json; schema: CalError

{
    "success": false,
    "error": {
        "message": "The calendar operation could not be completed.",
        "category": "calendar",
        "number": 800000
    }
}

500 Persistence, invitation, lifecycle, or internal calendar processing failed.

Content type: application/json; schema: CalError

{
    "success": false,
    "error": {
        "message": "The calendar operation could not be completed.",
        "category": "calendar",
        "number": 800000
    }
}

Status and retry matrix

Status Condition Retryable Developer action
200 The source-traced FeraCal handler completed and returned its calendar, event, person, resource, access, invitation, or lifecycle representation. No Continue with the returned calendar state.
400 UUID, key, date range, fields, invite target, or command validation failed. No Correct identity, scope, role, dates, invitation, resource, or dependency before retrying.
401 The x-auth-token or lifecycle HMAC is invalid. No Correct identity, scope, role, dates, invitation, resource, or dependency before retrying.
403 Managed-product, owner, role, share/inviter, or lifecycle sender permission is missing. No Correct identity, scope, role, dates, invitation, resource, or dependency before retrying.
404 The owner-scoped calendar, event, person, resource, or invite target was not found. No Correct identity, scope, role, dates, invitation, resource, or dependency before retrying.
500 Persistence, invitation, lifecycle, or internal calendar processing failed. Yes Correct identity, scope, role, dates, invitation, resource, or dependency before retrying.

Related operations and events

  • Operation calendar_get_peopleOKKey}
  • Operation calendar_get_peopleAvailableSStartAtEEndAt}
  • Operation calendar_delete_peopleIUuid}
  • Operation calendar_delete_peopleKKey}

Source trace

Repository: feradelinc/feradel.calendar.api
Route: routes/api/v1/person/routes.js
Handler: controller.createOrUpdate
Contract: OpenAPI 3.1, source-traced and publication-validated.