Employee Invitations — Proposed Guide

Employee Invitations: A proposed invitation would request onboarding for an identified work contact. It is a separate action from creating a profile and…

Overview

A proposed invitation would request onboarding for an identified work contact. It is a separate action from creating a profile and should have an explicit expiration and acceptance state.

Key concepts

Bind the invitation to an organization and intended role. Track pending, accepted, expired and revoked states.

Implementation considerations

This example sends no email. A future system must avoid duplicate invitations and ensure that acceptance cannot escalate the invited role.

Proposed API behavior

POST /v1/invitations is an illustrative design for this topic. Path and field names may change before implementation. Access would require an authorized organization context and operation-specific permission; no public API or authorization grant is available here.

Static example requests

# Proposed request text only; this reserved host is not a live API.
curl -X POST 'https://api.remizen.example/v1/invitations' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "email": "taylor@example.com",
  "organization_id": "org_example_123",
  "role_id": "role_example_123",
  "expires_at": "2026-01-15T12:00:00Z"
}'

Fictional response example

{
  "data": {
    "email": "taylor@example.com",
    "organization_id": "org_example_123",
    "role_id": "role_example_123",
    "expires_at": "2026-01-15T12:00:00Z",
    "id": "invitations_example_123"
  },
  "meta": {
    "request_id": "req_example_123",
    "reference_only": true
  }
}

Illustrative error case

Review this failure case in context: This example sends no email. A future system must avoid duplicate invitations and ensure that acceptance cannot escalate the invited role.

{
  "error": {
    "code": "validation_error",
    "message": "The proposed employee invitations operation requires review of its input or authorization.",
    "request_id": "req_example_123"
  }
}

Proposed data types

Related documentation