--- title: External user ID description: The External Users ID endpoints of the PingOne Recognize Mobile SDK Server API let you manage external user IDs. component: recognize page_id: recognize:mobile-sdk:mobile-sdk-server-api-external-user-id canonical_url: https://docs.pingidentity.com/recognize/mobile-sdk/mobile-sdk-server-api-external-user-id.html llms_txt: https://docs.pingidentity.com/recognize/llms.txt docs_for_agents: https://developer.pingidentity.com/build-with-ai/docs-for-agents.md revdate: May 5, 2026 section_ids: endpoint-external-user-post: POST /users/{userId}/external-user path-params-external-user-post: Path parameters request-body-external-user-post: Request body — application/json responses-external-user-post: Responses example-external-user-post: Example endpoint-external-user-patch: PATCH /users/{userId}/external-user path-params-external-user-patch: Path parameters request-body-external-user-patch: Request body — application/json responses-external-user-patch: Responses example-external-user-patch: Example endpoint-external-user-delete: DELETE /external-users/{externalUserId} path-params-external-user-delete: Path parameters responses-external-user-delete: Responses example-external-user-delete: Example endpoint-external-user-users-get: GET /external-users/{externalUserId}/users path-params-external-user-users-get: Path parameters responses-external-user-users-get: Responses example-external-user-users-get: Example --- # External user ID External user IDs let you set custom usernames for PingOne Recognize. Custom user IDs are typically easier to remember than globally unique identifiers (GUIDs) or similar structures. You shouldn't use personally identifiable information (PII) for custom user IDs, such as custom usernames, real names, or email addresses. All endpoints require the `X-Api-Key` header for authentication, which should contain your PingOne Recognize authorization key. For help, contact Support. | | | | - | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | For customers using the Authentication Service (which supports IDV Bridge SaaS and WebSDK), the External User ID documented on this page is mapped automatically to the Username in that service for ease of use. | ## POST /users/{userId}/external-user Create an external user Associate an external user ID with an existing Keyless user. A user can only have one external user associated at a time. ### Path parameters | Name | Type | Description | | --------------------- | -------------- | --------------------------------------------- | | `userId` **required** | `string (HEX)` | Uppercase HEX string representing the user ID | ### Request body — `application/json` | Field | Type | Description | | ----------------------------- | -------- | -------------------------------------- | | `externalUserId` **required** | `string` | Your system's identifier for this user | ### Responses | Status | Description | | ----------------------------------- | ------------------------------------------------------------------------------------------------------- | | `201` | `ExternalUserResponse` — contains `sdkCustomerId`, `userId`, `externalUserId`, `createdAt`, `updatedAt` | | `400 / 401 / 404 / 406 / 409 / 415` | Standard error responses | | `500` | Internal server error | ### Example **Request** ```none POST /v2/users/A1B2C3D4E5F6/external-user X-Api-Key: your-api-key Content-Type: application/json { "externalUserId": "custom-name@example.com" } ``` **Response 201** ```json { "sdkCustomerId": 42, "userId": "A1B2C3D4E5F6", "externalUserId": "custom-name@example.com", "createdAt": "2025-05-21T10:00:00.000", "updatedAt": "2025-05-21T10:00:00.000" } ``` *** ## PATCH /users/{userId}/external-user Update an external user Modify the external user associated with a Keyless user. This operation is idempotent and safe to retry. ### Path parameters | Name | Type | Description | | --------------------- | -------------- | --------------------------------------------- | | `userId` **required** | `string (HEX)` | Uppercase HEX string representing the user ID | ### Request body — `application/json` | Field | Type | Description | | ----------------------------- | -------- | ------------------------------------- | | `externalUserId` **required** | `string` | The new external user ID to associate | ### Responses | Status | Description | | ----------------------------- | --------------------------------------------------- | | `200` | `ExternalUserResponse` — updated external user data | | `400 / 401 / 404 / 406 / 415` | Standard error responses | | `500` | Internal server error | ### Example **Request** ```none PATCH /v2/users/A1B2C3D4E5F6/external-user X-Api-Key: your-api-key Content-Type: application/json { "externalUserId": "custom-name@example.com" } ``` **Response 200** ```json { "sdkCustomerId": 42, "userId": "A1B2C3D4E5F6", "externalUserId": "custom-name@example.com", "createdAt": "2025-05-21T10:00:00.000", "updatedAt": "2025-05-21T11:30:00.000" } ``` *** ## DELETE /external-users/{externalUserId} Delete an external user The external user ID is case-sensitive. Returns a success response even if the external user doesn't exist. ### Path parameters | Name | Type | Description | | ----------------------------- | -------- | ------------------------------------------- | | `externalUserId` **required** | `string` | Customer-meaningful user ID. Case-sensitive | ### Responses | Status | Description | | ----------------------- | ------------------------------------------------------------------------------- | | `204` | External user deleted (also returned if user didn't exist) | | `400 / 401 / 404 / 406` | Standard error responses (404 indicates endpoint not found, not user not found) | | `500` | Internal server error | ### Example **Request** ```none DELETE /v2/external-users/custom-name@example.com X-Api-Key: your-api-key ``` **Response 204** ```none // No response body ``` *** ## GET /external-users/{externalUserId}/users Get Keyless users by external ID Get all Keyless users associated with the given external user ID. Returns an empty list if none are found. The external user ID lookup is case-insensitive. ### Path parameters | Name | Type | Description | | ----------------------------- | -------- | ------------------------------------------------------------- | | `externalUserId` **required** | `string` | Customer-meaningful user ID. Case-insensitive for this lookup | ### Responses | Status | Description | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | `200` | Array of `UserResponse` objects — each with `userId`, `biometricPublicSigningKey`, `createdAt`, `updatedAt`. Empty array if no users found | | `400 / 401 / 404 / 406 / 409` | Standard error responses | | `500` | Internal server error | ### Example **Request** ```none GET /v2/external-users/custom-name@example.com/users X-Api-Key: your-api-key ``` **Response 200** ```json [ { "userId": "A1B2C3D4E5F6", "biometricPublicSigningKey": "BJSafl+GrMLT2y43...", "createdAt": "2025-01-10T08:00:00.000", "updatedAt": "2025-05-21T10:00:00.000" } ] ```