📘 Add New User API (Enroll User)

Enterprise backend servers can use this API to register a new user into the Ditto ID system under a specified group. Optionally, access credentials for activation (access code or OTP) can be predefined or auto-generated. This API will return an error if the user already exists.

🔗 Endpoint

POST https://REL-ID-SERVER-IP:9442/v1/users

🔐 Authorization

Authorization: Bearer <access_token>
Content-Type: application/json

🧾 Request Parameters (as per Ditto ID GM API Guide)

Parameter	Required	Description
`userId`	✅ Yes	Ditto ID user ID of the user to be created.
`primaryGroup`	✅ Yes	Group name under which the user needs to be enrolled. This group must already exist in Ditto ID.
`firstName`	✅ Yes	First name of the user to be created.
`lastName`	✅ Yes	Last name of the user to be created.
`secondaryGroups`	✅ Yes	Comma-separated names of additional Ditto ID groups to which the user should also belong.
`emailId`	✅ Yes	Email address of the user. If provided and `predefinedCode` is not set, then a random access code will be generated by the server and sent through email to this ID.
`mobileNumber`	✅ Yes	Mobile number of the user. If provided and `predefinedCode` is not set, then a random access code will be generated by the server and sent via SMS. The number must be 10 to 15 digits, optionally starting with '+'.
`preferredStatus`	❌ Optional	Default: `'CREATED'`. Must be either `'ONBOARDING'` or `'CREATED'`. Used for identity verification (IDV) flows.
`predefinedCode`	❌ Optional	Predefined activation code to be used during activation. If not provided, one will be generated dynamically.
`predefinedVerKey`	❌ Optional	Verification key shown during activation. If not set, it will be generated dynamically.
`sourceType`	❌ Optional	Source type of the user being enrolled. Default: `RELID`. Allowed values: `RELID`, `UNIKEN-AD`.
`loginId`	❌ Optional	Login ID for Ditto ID apps. Defaults to the value of `userId` if not provided.
`comments`	❌ Optional	Extra information about the caller (e.g., maker/checker). Visible in Admin Activity Report.
`selfieImage`	❌ Optional	Base64-encoded selfie image. Compliance checks will be applied. On success, biometric fields are generated: `server_bio_template_hash`, `server_bio_template_hash_created_ts`, and `server_bio_template_source`.

🧪 Sample Requests

Basic Request

{
  "userId": "abc1",
  "primaryGroup": "group1",
  "firstName": "John",
  "lastName": "Doe",
  "emailId": "[email protected]",
  "mobileNumber": "+919876543210"
}

✅ Success Response

HTTP Code	Response
`201 Created`	Empty body. `Location` header contains: `/v1/users/<userId>`

❌ Error Responses

🔄 Error Table

HTTP Code	Scenario	Message Example
`409`	User already exists (any status: DELETED, CREATED, ACTIVE)	`"User is DELETED"`
`409`	Primary and secondary groups are the same	`"Primary and secondary group name cannot be same."`
`409`	Group does not exist	`"The group name : gs1 does not exist in the system."`
`409`	Mobile number is already registered	`"Mobile number already registered"`
`422`	Invalid field or validation error	`"[Invalid field First Name]"`
`400`	Malformed body / wrong JSON structure	`"Malformed request body"`
`400`	Facial recognition compliance failed (e.g., selfie too far)	`"Failed.[FACE_TOO_FAR]"`
`415`	Content-Type is not `application/json`	`"Content type 'text/plain;charset=UTF-8' not supported"`
`401`	Access token is invalid or expired	`"Invalid access token"`
`401`	IP address not whitelisted	`"IP not whitelisted"`
`405`	HTTP method other than POST used	`"Request method 'PUT' is not supported"`
`500`	Internal server error (e.g., DB or Aware server error)	`"Failed to consume aware server's analyze API."`

🧾 Error Examples

🔁 User Already Exists

{
  "timestamp": "2023-05-30T12:33:32IST",
  "status": 409,
  "error": "Invalid data.",
  "message": "User is DELETED",
  "path": "/v1/users",
  "userStatus": "DELETED"
}

🔁 Duplicate Groups

{
  "timestamp": "2023-06-23T11:52:56IST",
  "status": 409,
  "error": "Invalid data.",
  "message": "Primary and secondary group name cannot be same.",
  "path": "/v1/users"
}

🔁 Group Not Present

{
  "timestamp": "2023-06-23T11:52:56IST",
  "status": 409,
  "error": "Invalid data.",
  "message": "The group name : gs1 does not exist in the system.",
  "path": "/v1/users"
}

🔁 Mobile Number Already Registered

{
  "timestamp": "2023-10-10T10:23:45IST",
  "status": 409,
  "error": "Invalid data.",
  "message": "Mobile number already registered",
  "path": "/v1/users"
}

🛑 Invalid Field

{
  "timestamp": "2023-05-30T12:33:32IST",
  "status": 422,
  "error": "Invalid data.",
  "message": "[Invalid field First Name]",
  "path": "/v1/users"
}

🛑 Malformed JSON

{
  "timestamp": "2024-08-14T06:21:38UTC",
  "status": 400,
  "error": "Bad Request",
  "message": "Malformed request body",
  "path": "/v1/users"
}

🛑 Selfie Compliance Failed

{
  "timestamp": "2024-10-03T07:49:05UTC",
  "status": 400,
  "error": "Bad Request",
  "message": "Failed.[FACE_TOO_FAR]",
  "path": "/v1/users"
}

🛑 Unsupported Media Type

{
  "timestamp": "2024-09-09T07:43:25UTC",
  "status": 415,
  "error": "Unsupported Media Type",
  "message": "Content type 'text/plain;charset=UTF-8' not supported",
  "path": "/v1/users"
}

🔒 Invalid Access Token

{
  "error_description": "Invalid access token: <token>",
  "error": "invalid_token"
}

🔒 IP Not Whitelisted

{
  "timestamp": "2023-05-30T12:33:32IST",
  "status": 401,
  "error": "Unauthorized",
  "message": "IP not whitelisted",
  "path": "/v1/users"
}

🚫 Method Not Allowed

{
  "timestamp": "2024-09-09T07:43:25UTC",
  "status": 405,
  "error": "Method Not Allowed",
  "message": "Request method 'PUT' is not supported",
  "path": "/v1/users"
}

💥 Internal Server Error

{
  "timestamp": "2024-10-07T13:27:21UTC",
  "status": 500,
  "error": "Internal Server Error",
  "message": "Failed to consume aware server's analyze API.",
  "path": "/v1/users"
}

Best Practices

Always provide a unique userId that follows your organization's naming conventions.
Ensure that the primaryGroup exists before creating a user.
For security reasons, prefer generating random access codes rather than providing predefined ones.
When creating bulk users, monitor for potential conflicts with existing users.
When providing a mobileNumber, ensure it follows the correct format (10-15 digits with optional "+" sign).
Keep comments field informative but concise for audit purposes.
Handle error responses appropriately in your client application.