Employee Photo Update API - Interface Control Document

1. Document Information

Item	Description
Document Title	Employee Photo Update API - Interface Control Document
API Name	updateEmployeePhoto
Interface Type	REST API (Integration Service)
Version	0.0.1
Last Updated	2025-10-15
Status	Active

The Employee Photo Update API enables HR systems to update employee photos in the EPC (Emirates Platinum Club) system. This integration service allows external HR systems to push employee photo updates when photos are changed in the HR system.

2.2 Integration Context

This API is part of the broader Emirates Employee Photo Update Flow. For complete flow documentation, see:

3. Interface Specification

3.1 Endpoint Details

Property	Value
HTTP Method	POST
Endpoint Pattern	`/:projectId/CALL/Member/updateEmployeePhoto/:instanceId`
Protocol	HTTPS
Content-Type	application/json
Authentication	API Key (x-api-key header)
Authorization	userIdentity.integration_user

3.2 Path Parameters

Parameter	Type	Required	Description	Example
`projectId`	string	Yes	The EPC project identifier	`13ra108se`
`instanceId`	string	Yes	Member ID or Staff ID with prefix	`staffId!EMP001` or `MEM12345`

Instance ID Format:

Member ID: Direct member identifier (e.g., MEM12345)
Staff ID: Staff identifier prefixed with staffId! (e.g., staffId!EMP001)

3.3 Request Headers

Header	Type	Required	Description
`x-api-key`	string	Yes	API authentication key
`Content-Type`	string	Yes	Must be `application/json`

3.4 Request Body

Field	Type	Required	Constraints	Description
`photo`	string	Yes	Base64 encoded	Base64 encoded image data
`fileExtension`	string	Yes	Enum: `jpg`, `jpeg`, `png`, `gif`, `webp`	Image file extension

TypeScript Input Schema:

export const UpdateEmployeePhotoInput = z.object({
    photo: z.string(),
    fileExtension: z.nativeEnum(ImageFileExtension),
})

export enum ImageFileExtension {
    JPG = 'jpg',
    JPEG = 'jpeg',
    PNG = 'png',
    GIF = 'gif',
    WEBP = 'webp',
}

MIME Type Mapping:

jpg → image/jpeg
jpeg → image/jpeg
png → image/png
gif → image/gif
webp → image/webp

3.5 Response Format

Success Response (HTTP 200)

{
  "success": true
}

Field	Type	Description
`success`	boolean	Always `true` on successful upload

Error Response (HTTP 4xx/5xx)

{
  "code": 10000,
  "message": "Error description",
  "details": {}
}

Field	Type	Description
`code`	number	Error code identifier (e.g., 10018 for EMPLOYEE_PHOTO_UPLOAD_FAILED)
`message`	string	Localized human-readable error message
`details`	object	Additional error context and debugging information (optional)

4. Request/Response Examples

4.1 Request with Staff ID

POST /13ra108se/CALL/Member/updateEmployeePhoto/staffId!EMP001
Content-Type: application/json
x-api-key: your-api-key-here

{
  "photo": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==",
  "fileExtension": "png"
}

4.2 Request with Member ID

POST /13ra108se/CALL/Member/updateEmployeePhoto/MEM12345
Content-Type: application/json
x-api-key: your-api-key-here

{
  "photo": "/9j/4AAQSkZJRgABAQEAYABgAAD/2wBDAAIBAQIBAQICAgICAgICAwUDAwMDAwYEBAMFBwYHBw...",
  "fileExtension": "jpg"
}

4.3 Success Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "success": true
}

4.4 Error Response Examples

Validation Error

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "code": 10005,
  "message": "Invalid file extension. File extension must be one of: jpg, jpeg, png, gif, webp"
}

Upload Error

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "code": 10018,
  "message": "Failed to upload employee photo.",
  "details": {
    "message": "File upload failed.",
    "code": 6006
  }
}

Instance Not Found Error (Rio Framework)

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "message": "There is no instance with id '87LN5X4ZQR8C8G5TMFPTDX402' in '107jif3ja/Member'"
}

Note: Instance not found errors are handled by the Rio framework before the method handler is invoked, so they return a different format.

5. Data Validation Rules

5.1 Photo Field Validation

Format: Must be valid Base64 encoded string
Content: Must represent a valid image in the specified format

5.2 File Extension Validation

Allowed Values: jpg, jpeg, png, gif, webp
Case Sensitivity: Lowercase only
Validation: Uses Zod enum validation (z.nativeEnum(ImageFileExtension))

5.3 Instance ID Validation

Member ID: Direct member identifier (no prefix)
Staff ID: Must use staffId! prefix followed by employee identifier

6. Security

6.1 Authentication

Method: API Key authentication
Header: x-api-key
Authorization: Requires userIdentity.integration_user permission

6.2 Data Security

All communication must use HTTPS
Base64 encoding for image data in transit
API keys must be securely stored and rotated periodically
Photos stored in secure file storage with access controls
File access URLs generated with expiry tokens

7. Error Handling

7.1 Common Error Scenarios

Error Code	HTTP Status	Description	Resolution
`UNAUTHORIZED`	401	Invalid or missing API key	Verify x-api-key header and value
`VALIDATION_ERROR`	400	Invalid input data	Check Zod schema validation errors
N/A (Rio Framework)	500	Member/Employee instance not found	Verify instanceId exists in system. Response: `{"message":"There is no instance with id 'X' in 'projectId/Member'"}`
`EMPLOYEE_PHOTO_UPLOAD_FAILED`	400	Employee photo upload failed	Check photo format and size, retry request
`FILE_UPLOAD_FAILED`	500	File storage error (FileManager)	Internal file storage issue, contact support
`INVALID_FILE_FORMAT`	400	Invalid file format	Ensure photo is in supported format (jpg, jpeg, png, gif, webp)

Error Handling Flow:

File upload errors from FileManager are caught and wrapped in EMPLOYEE_PHOTO_UPLOAD_FAILED error
Original FileManager error details are preserved in error response for debugging
All errors follow standard ErrorResponse format with localized messages
Instance not found errors are handled by Rio framework before reaching the method handler

Platinum