/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.

Requests

Authorization / Authentication

Apps using Access Token Authorization

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

See Authenticating with an Access Token for more details.

Apps using ECDSA Authentication

An authsignature header is required for this request. Create this using the keypair associated with the auth_handle.

See the section on ECDSA Authentication for more detail about ECDSA signature generation.

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": "handle.silamoney.eth", 
    "user_handle":"user.silamoney.eth", 
    "version": "0.2", 
    "crypto": "ETH", 
    "reference": "<your unique id>"
  }, 
  "message": "header_msg"
}

***

HTTP/1.1 200 OK

{
  "success": true,
  "reference": "<your unique id>",
  "message": "user.silamoney.eth is available.",
  "response_time_ms": "171",
  "status": "SUCCESS"
}

const userHandle = 'user.silamoney.eth';

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.silamoney.eth" # 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.silamoney.eth is available!',
    'reference': 'd725a285-3cda-47cb-aa55-60db70460ae4',
    'status': 'SUCCESS',
    'status_code': 200
}

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

String userHandle = "user.silamoney.eth";
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.silamoney.eth';
$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.silamoney.eth";
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. Used for API authentication of signatures. Requires these keys in JSON format: created app_handle user_handle.
header.created	Integer	Required. UTC Unix Timestamp in seconds or milliseconds. This value should match the required regex pattern: ^[0-9]{10,14}$. The date must not be future-dated and must not be dated more than 5 minutes in the past. Example: 1234567890
header.app_handle	String	Required. Alphanumeric value, must be globally unique. Min length 3, Max 100 (not including . silamoney.com portion, which can be optionally left off). This value should match the required regex pattern: ^[-a-zA-Z0-9_.]+$ (not including .silamoney.com portion). Examples: handle.silamoney.eth or handle
header.user_handle	String	Required. Alphanumeric value, must be globally unique. Min length 3, Max 100 (not including . silamoney.com portion, which can be optionally left off). This value should match the required regex pattern: ^[-a-zA-Z0-9_.]+$ (not including .silamoney.com portion). Examples: user.silamoney.eth or user
header.version	String	Optional. May not be null, but can be left out of request. Valid values: 0.2, v0.2, V0.2 Example: 0.2
header.crypt	String	Optional. Must be UPPER-CASE. Only valid value is ETH. Example: ETH
header.reference	String	Optional. Can be any string, uniqueness not required. May not be null. Example: ref

Responses

The status attribute is a JSON key sent in the response body with possible values of "SUCCESS" and "FAILURE". We now also include a success attribute with a boolean value ("success": true = "status": "SUCCESS" and "success": false = "status": "FAILURE"). Both of these keys will be included in every response returned as a JSON object.

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.