/check_handle

A "handle" works like a username in the Sila ecosystem. This endpoint ensures that a potential handle is available for use. If an entity has already been created with that handle, this endpoint will respond with a message that says that the handle is already in use and a "status": "FAILURE" in the JSON response body.

Request

Authorization / Authentication

Apps using Access Token Authorization

Use a valid access token in a Authorization: Bearer request header.

See Auth Token Overview for more details.

Apps using ECDSA Authentication

Both authsignature and usersignature headers are required for this request. The usersignature header should be generated with a keypair registered to the user (either registered from the /register endpoint or the /register_wallet endpoint).

See our ECDSA overview for more.

Note - We recently renamed the field auth_handle to app_handle. For backward compatibility, auth_handle is still valid but has been removed from our documentation.

POST /0.2/check_handle HTTP/1.1
Host: sandbox.silamoney.com
Content-Type: application/json
// if using OAuth2
Authorization: Bearer [GENERATED JWT TOKEN HERE]
// if using ECDSA
authsignature: [GENERATED AUTHSIGNATURE HEX STRING HERE]

{
  "header": {
    "created": 1234567890, 
    "app_handle": "app_handle", 
    "user_handle":"user_handle", 
    "version": "0.2", 
    "reference": "<your unique id>"
  }, 
  "message": "header_msg"
}

***

HTTP/1.1 200 OK

{
  "success": true,
  "reference": "<your unique id>",
  "sila_reference_id": "sila_assigned_id",
  "message": "user_handle is available.",
  "response_time_ms": "171",
  "status": "SUCCESS"
}

const userHandle = 'user_handle';

const res = await Sila.checkHandle(userHandle);

// Success Response Object

console.log(res.statusCode); // 200
console.log(res.data.success); // true
console.log(res.data.reference); // your unique id
console.log(res.data.status); // SUCCESS
console.log(res.data.message); // User is available!

// Failure Response Object

console.log(res.statusCode); // 200
console.log(res.data.success); // false
console.log(res.data.reference); // your unique reference id
console.log(res.data.status); // FAILURE
console.log(res.data.message); // User is already taken

payload = {
  "user_handle": "user_handle" # Required
}

# Make sure silaApp is initialized with registered app_private_key and app_handle.
User.checkHandle(silaApp, payload)

### Success Response Object _200 OK_
{
    'success': True,
    'message': 'user_handle is available!',
    'reference': 'd725a285-3cda-47cb-aa55-60db70460ae4',
    'status': 'SUCCESS',
    'status_code': 200
}

### Failure Response Object _200 OK_
{
    'success': False,
    'status': 'FAILURE',
    'message': 'user_handle is taken',
    'reference': 'd725a285-3cda-47cb-aa55-60db70460ae4',
    'status_code': 200
}

String userHandle = "user_handle";
ApiResponse response = api.checkHandle(userHandle);

##### Success Response Object 200 

System.out.println(response.getStatusCode()); // 200
System.out.println(((BaseResponse)response.getData()).getReference()); // Random reference number
System.out.println(((BaseResponse)response.getData()).getStatus()); // SUCCESS
System.out.println(((BaseResponse)response.getData()).getMessage()); // user is available!
System.out.println(((BaseResponse)response.getData()).getSuccess()); // true

##### Failure Response Object 200

System.out.println(response.getStatusCode()); // 200
System.out.println(((BaseResponse)response.getData()).getReference()); // your unique reference id
System.out.println(((BaseResponse)response.getData()).getStatus()); // FAILURE
System.out.println(((BaseResponse)response.getData()).getMessage()); // user is already taken.
System.out.println(((BaseResponse)response.getData()).getSuccess()); // false

$userHandle = 'user_handle';
$response = $client->checkHandle($userHandle); // Returns Silamoney\Client\Api\ApiResponse

### Success 200
echo $response->getStatusCode(); // 200
echo $response->getData()->getReference(); // your unique id
echo $response->getData()->getStatus(); // SUCCESS
echo $response->getData()->getMessage(); // User is available

### Failure 200
echo $response->getStatusCode(); // 200
echo $response->getData()->getReference(); // your unique reference id
echo $response->getData()->getStatus(); // FAILURE
echo $response->getData()->getMessage(); // User is already taken

string userHandle = "user_handle";
ApiResponse<object> response =  api.CheckHandle(userHandle);

// Success Response Object 200

Console.WriteLine(response.StatusCode); // 200
Console.WriteLine(((BaseResponse)response.Data).Reference); // your unique reference id
Console.WriteLine(((BaseResponse)response.Data).Status); // SUCCESS
Console.WriteLine(((BaseResponse)response.Data).Message); // user is available!

// Failure Response Object 200

Console.WriteLine(response.StatusCode); // 200
Console.WriteLine(((BaseResponse)response.Data).Reference); // your unique reference id
Console.WriteLine(((BaseResponse)response.Data).Status); // FAILURE
Console.WriteLine(((BaseResponse)response.Data).Message); // user is already taken

Key	Type	Description
header	JSON object	Required. Required keys: `created` - Unix epoch timestamp in seconds. Must not be future-dated and must not be dated more than 5 minutes in the past. `app_handle` - your app handle `user_handle` - the user_handle to be checked Optional keys: `reference`: Can be any value for your own reference. If not provided, one will be assigned. `version`: Cannot be null if key is present. Valid values: 0.2, v0.2, V0.2

Responses

Both the status and success keys indicate the availability the user_handle being checked.

If the handle is available:

success: true
status: "SUCCESS"

If the handle is not available:

success: false
status: "FAILURE"

Status Code	`success`Attribute	Description
200	`true`	Handle sent in `header.user_handle` is available.
200	`false`	Handle sent in `header.user_handle` is taken.
400	`false`	Bad request format - check `validation_details` for more information.
401	`false`	Auth signature is absent or derived address does not belong to app_handle.