User API Specification¶

Overview¶

The User API provides endpoints for user authentication, registration, profile management, and password operations.

Base Path: /user

Content Types: - Request: application/json - Response: application/json

Response Format¶

All endpoints return a TlinqApiResponse object:

{
  "apiStatus": {
    "errorCode": "OK",
    "errorMessage": "Success"
  },
  "apiData": { ... }
}

Date Format: All dates are returned in ISO 8601 format (yyyy-MM-dd'T'HH:mm:ss)

Authentication Endpoints¶

GET /user/authenticate¶

Authenticates a user with username and password.

Query Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | username | string | Yes | User login name | | password | string | Yes | User password |

Response Structure:

href="#__codelineno-1-1">{ "apiStatus": { "errorCode": "OK", "errorMessage": "Success" }, "apiData": { "userId": 101, "userCode": "USR-001", "userLogin": "john.smith@example.com", "userName": "John Smith", "userEmail": "john.smith@example.com", "mobile": "+971501234567", "phone": "+97142345678", "street": "123 Main Street", "city": "Dubai", "countryId": 784, "countryName": "United Arab Emirates", "isCompany": false, "isEmployee": false, "isCustomer": true, "isActive": true, "isPortalUser": true, "companyId": 5001, "companyName": "Travel World LLC", "companyType": "B2B", "contactId": 1001, "auth": "OK", "createDate": "2025-01-15T10:00:00" } }

Error Codes: - MISSING_PARAMETER - Username and password required - NOTFOUND - User not found or invalid credentials

POST /user/authenticate¶

Authenticates a user with credentials object.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | username | string | Yes | User login name | | password | string | Yes | User password |

Request Example:

{
  "username": "john.smith@example.com",
  "password": "mySecurePassword123"
}

Response Structure: Same as GET /user/authenticate.

Registration Endpoints¶

POST /user/register¶

Registers a new user.

Query Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | pk | string | No | System session token |

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | userLogin | string | Yes | Login email | | password | string | Yes | Password | | userName | string | No | Display name | | userEmail | string | Yes | Email address | | mobile | string | No | Mobile phone | | street | string | No | Street address | | city | string | No | City | | countryId | integer | No | Country ID |

Request Example:

{
  "userLogin": "jane.doe@example.com",
  "password": "securePassword456",
  "userName": "Jane Doe",
  "userEmail": "jane.doe@example.com",
  "mobile": "+971509876543",
  "city": "Dubai",
  "countryId": 784
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "userId": 102,
    "userCode": "USR-002",
    "userLogin": "jane.doe@example.com",
    "userName": "Jane Doe",
    "userEmail": "jane.doe@example.com",
    "mobile": "+971509876543",
    "city": "Dubai",
    "countryId": 784,
    "countryName": "United Arab Emirates",
    "isActive": false,
    "isCustomer": true,
    "signupToken": "abc123xyz",
    "signupTokenType": "ACTIVATION",
    "signupExpiry": "2025-06-22T10:00:00",
    "signupTokenValid": true,
    "createDate": "2025-06-15T10:00:00"
  }
}

Error Codes: - MISSING_PARAMETER - User data with login required

POST /user/check¶

Checks if a user exists by email.

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | No | User session token | | email | string | Yes | Email to check |

Request Example:

{
  "email": "john.smith@example.com"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": true
}

Activation Endpoints¶

GET /user/activate¶

Activates a user account with token.

Query Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | token | string | Yes | Activation token |

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "userId": 102,
    "userLogin": "jane.doe@example.com",
    "userName": "Jane Doe",
    "userEmail": "jane.doe@example.com",
    "isActive": true,
    "signupTokenValid": false,
    "auth": "OK"
  }
}

Error Codes: - MISSING_PARAMETER - Activation token required - NOTFOUND - Invalid or expired token

POST /user/activate¶

Activates a user account with token (POST version).

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | token | string | Yes | Activation token |

Request Example:

{
  "token": "abc123xyz"
}

Response Structure: Same as GET /user/activate.

Profile Endpoints¶

POST /user/update¶

Updates user profile information.

Query Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token |

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | userId | integer | Yes | User ID | | userName | string | No | Display name | | userEmail | string | No | Email address | | mobile | string | No | Mobile phone | | phone | string | No | Landline phone | | street | string | No | Street address | | street2 | string | No | Street address line 2 | | city | string | No | City | | countryId | integer | No | Country ID |

Request Example:

{
  "userId": 101,
  "userName": "John M. Smith",
  "mobile": "+971501234568",
  "street": "456 New Street",
  "city": "Abu Dhabi"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "userId": 101,
    "userCode": "USR-001",
    "userLogin": "john.smith@example.com",
    "userName": "John M. Smith",
    "userEmail": "john.smith@example.com",
    "mobile": "+971501234568",
    "street": "456 New Street",
    "city": "Abu Dhabi",
    "countryId": 784,
    "countryName": "United Arab Emirates",
    "isActive": true
  }
}

Error Codes: - NOT_LOGGED_IN - User must be logged in

Password Endpoints¶

POST /user/updatepwd¶

Updates password for logged-in user.

Query Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | session | string | Yes | User session token |

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | userId | integer | Yes | User ID | | password | string | Yes | Current password for verification | | newPassword | string | Yes | New password |

Request Example:

{
  "userId": 101,
  "password": "currentPassword123",
  "newPassword": "newSecurePassword456"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": {
    "userId": 101,
    "userLogin": "john.smith@example.com",
    "userName": "John Smith",
    "auth": "OK"
  }
}

Error Codes: - NOT_LOGGED_IN - User must be logged in - INVALID_CREDENTIALS - Current password incorrect

POST /user/resetpwdRequest¶

Requests a password reset email.

Query Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | pk | string | No | System session token |

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | f_useremail | string | Yes | User email address |

Request Example:

{
  "f_useremail": "john.smith@example.com"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": "Password reset request sent successfully."
}

POST /user/resetpwd¶

Resets password using reset token.

Query Parameters: | Field | Type | Required | Description | |-------|------|----------|-------------| | pk | string | No | System session token |

Request Body: | Field | Type | Required | Description | |-------|------|----------|-------------| | resetToken | string | Yes | Reset token from email | | newPassword | string | Yes | New password |

Request Example:

{
  "resetToken": "xyz789resettoken",
  "newPassword": "myNewSecurePassword789"
}

Response Structure:

{
  "apiStatus": { "errorCode": "OK", "errorMessage": "Success" },
  "apiData": "Password reset successfully."
}

Error Codes: - NOTFOUND - Invalid or expired reset token

Data Models¶

CRegUser¶

Field	Type	Description
userId	integer	User ID
userCode	string	User code
userLogin	string	Login username/email
userName	string	Display name
userEmail	string	Email address
password	string	Password (write only)
newPassword	string	New password (for updates)
mobile	string	Mobile phone
phone	string	Landline phone
street	string	Street address
street2	string	Street address line 2
city	string	City
countryId	integer	Country ID
countryName	string	Country name
contactId	integer	Associated contact ID
isCompany	boolean	Is company user
isEmployee	boolean	Is employee
isCustomer	boolean	Is customer
isActive	boolean	Account active status
isPortalUser	boolean	Portal access enabled
companyType	string	Company type
companyId	integer	Associated company ID
companyName	string	Company name
signupToken	string	Signup/activation token
signupTokenType	string	Token type (ACTIVATION, RESET)
signupExpiry	datetime	Token expiry date
signupTokenValid	boolean	Token validity
createDate	datetime	Account creation date
auth	string	Authentication status (OK, NO)

LoginCredentials¶

Field	Type	Description
username	string	Login username/email
password	string	Password

Session Token¶

Upon successful authentication, the user receives a session token. This token should be included in subsequent API requests using one of these methods: - As session parameter in request body - As session query parameter - As X-Auth-Request-Access-Token header