Reference dashboard

End-to-end scenario

The most common integration path: create a person, handle the duplicate-code error, and recover with a lookup. Authentication uses the x-api-key header on every request.

Endpoints

Method Path Description
POST/api/personsCreate a person.
GET/api/persons/code/{code}Look up by code.
PUT/api/persons/{id}Update person.
POST/api/visitorsRegister visitor with QR.
GET/api/access-levelsList access levels.

Scenario · Create person

200 — Success

Request

curl -X POST "$HOST/api/persons" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "personCode":       "EMP20260428001",
  "personGivenName":  "Mostafa",
  "personFamilyName": "Ahmed",
  "gender":           1,
  "orgIndexCode":     "ORG_TATWEER_001",
  "beginTime":        "2026-04-28T13:00:00+03:00",
  "endTime":          "2033-04-28T13:00:00+03:00"
}'

Response

{
  "success": true,
  "data": {
    "code": "0",
    "data": { "person": { "personId": "119" } }
  }
}
409 — Duplicate

If personCode already exists

Returned when the directory already contains a person with the same personCode.

{
  "success": false,
  "data": {
    "code": "99999",
    "msg": "Person with personCode 'EMP20260428001' already exists",
    "errorDetails": {
      "field": "personCode",
      "constraint": "UNIQUE",
      "suggestion": "Use a unique personCode or call GET /api/persons/code/{code}"
    }
  }
}
Resolution. Look up the existing record with GET /api/persons/code/EMP20260428001, then issue a PUT to update — don't retry the POST.