Create User — Proposed Guide

Planned API — Reference Only

Create User: A proposed user creation operation would establish an organizational profile. Creating that profile should not automatically invite the…

Overview

A proposed user creation operation would establish an organizational profile. Creating that profile should not automatically invite the person, grant administrator privileges or initiate payroll enrollment.

Key concepts

Validate the organization, work email and optional department reference. Choose a stable external reference for source-system matching.

Implementation considerations

Specify duplicate handling for email and external identifiers. An idempotent replay should not create a second profile or send additional invitations.

Proposed API behavior

POST /v1/users 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.

Illustrative request fields
Name	Type	Description
organization_id	string	Stable fictional organization reference; not a secret and not evidence that a resource exists.
email	string	Fictional work contact. This reserved example address does not identify a real employee.
display_name	string	Synthetic display label, not a stable identifier or permission assignment.
department_id	string	Stable fictional department reference; not a secret and not evidence that a resource exists.
external_id	string	Fictional source/provider correlation value, not a credential or proof of synchronization.

Static example requests

Proposed, non-executing request examples

# Proposed request text only; this reserved host is not a live API.
curl -X POST 'https://api.remizen.example/v1/users' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{
  "organization_id": "org_example_123",
  "email": "taylor@example.com",
  "display_name": "Taylor Example",
  "department_id": "dept_example_123",
  "external_id": "external_example_123"
}'

Fictional response example

201 (proposed example)Static response fixture

Fictional documentation data only. No request was sent, record created, review performed, payment initiated or provider connection activated.

JSON

{
  "data": {
    "organization_id": "org_example_123",
    "email": "taylor@example.com",
    "display_name": "Taylor Example",
    "external_id": "external_example_123",
    "id": "usr_example_123",
    "status": "active"
  },
  "meta": {
    "request_id": "req_example_123",
    "reference_only": true
  }
}

Illustrative error case

Review this failure case in context: Specify duplicate handling for email and external identifiers. An idempotent replay should not create a second profile or send additional invitations.

422 (illustrative; final error contracts are undecided)Proposed error fixture

Synthetic diagnostic example. Human-readable messages must not be used as stable programmatic contracts.

JSON

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

Proposed data types

Illustrative field dictionary
Name	Type	Description
organization_id	string	Stable fictional organization reference; not a secret and not evidence that a resource exists.
email	string	Fictional work contact. This reserved example address does not identify a real employee.
display_name	string	Synthetic display label, not a stable identifier or permission assignment.
department_id	string	Stable fictional department reference; not a secret and not evidence that a resource exists.
external_id	string	Fictional source/provider correlation value, not a credential or proof of synchronization.

Retrieve User

Users & Organizations

Update User