APIs for User Registration

This article covers the following topics:

Endpoint: An endpoint is one end of a communication channel. When an API interacts with another system, the touchpoints of this communication are considered endpoints. For APIs, an endpoint can include a URL of a server or service. Each endpoint is the location from which APIs can access the resources they need to carry out their function. For example, https://luma.serviceaide.com/vsa.

The following sections cover the various APIs available to be used during the different stages of user registration.

Check if a user already exists in Luma

Use the following JSON code to validate whether the user already exists in Luma.

Request Code Block

GET: {{ENDPOINT}}/public/get-contacts?reconciliationkey=(username/email/phone/firstname/lastname)

Copy the Inbound API Access Token from Luma and pass it in the Header as the Authorization – Bearer token.

To fetch the Inbound API Access Token, and pass it to the Header as the Authorization - Bearer token, in the Luma Skills Builder, click Settings menu and then click the Tenant Information tab as shown below.

For example, to validate whether the user already exists in Luma using the user's phone number, use the following sample request:

Request Code Block

GET: {{ENDPOINT}}/public/get-contacts?reconciliationkey=xxxxxxxxxx

Copy the Inbound API Access Token from Luma and pass it in the Header as the Authorization – Bearer token by following the steps referred above.

If user exists, then Luma returns an array of users. If the ''data'' array returns any value, then it means that a single or multiple users exist in Luma, that align to that data as shown below.

Sample Response Code Block

{
    "timestamp": 1562831242123,
    "status": 200,
    "message": "OK",
    "errors": [],
    "data": [
        {
            "id": 7,
            "tenant": 1054,
            "createdDate": 1551360119403,
            "createdByContact": {
                "id": -1,
                "name": "system-user"
            },
            "modifiedDate": 1553494021370,
            "modifiedByContact": {
                "id": -1,
                "name": "system-user"
            },
            "recordsStatus": 1,
            "createdBy": {
                "id": -1,
                "name": "System User"
            },
            "modifiedBy": {
                "id": -1,
                "name": "System User"
            },
            "subTenant": 1,
            "userName": "john",
            "email": "john.williams@gmail.com",
            "firstName": "john",
            "lastName": "williams",
            "middleName": "",
            "title": null,
            "phone": null,
            "roles": [
                {
                    "id": -1,
                    "roleName": "Administrator",
                    "isItsmRole": "Yes"
                }
            ],
            "lastUpdatedSource": "ITSM",
            "language": {
                "id": 6,
                "tenant": 1054,
                "createdDate": 1549277386000,
                "createdByContact": {
                    "id": -1,
                    "name": "system-user"
                },
                "modifiedDate": 1549277386000,
                "modifiedByContact": {
                    "id": -1,
                    "name": "system-user"
                },
                "recordsStatus": 1,
                "createdBy": {
                    "id": -1,
                    "name": "System User"
                },
                "modifiedBy": {
                    "id": -1,
                    "name": "System User"
                },
                "subTenant": 1,
                "code": "en",
                "name": "English",
                "displayName": "English (United States)",
                "locale": "United States"
            },
            "groupNames": null,
            "contactGlobalAttributesVos": null
        }
    ]
}

If the user does not exist, Luma returns an empty ''data'' array as shown below.

Sample Response Code Block

{
    "timestamp": 1562831242123,
    "status": 200,
    "message": "OK",
    "errors": [],
    "data": []
}

Check if a user is authenticated in the Channel

Use the following JSON code to validate whether the user is authenticated in the current Luma chat channel. No channel name needs to be passed as the call will leverage the current channel the user is on.

Request Code Block

GET: {{ENDPOINT}}/public/isuserauthorizedtochannel?username=@user.userName

Copy the Inbound API Access Token from Luma and pass it in the Header as the Authorization – Bearer token by following the steps referred above.

Note

It is mandatory to pass @user.userName in the request.

If the user is authenticated to the channel, then the response returned is true as shown below.

Sample Response Code Block

{
    "timestamp": 1562837529912,
    "status": 200,
    "message": "OK",
    "errors": [],
    "data": true
}

If the user is not authenticated to the channel, then the response returned is false as shown below.

Sample Response Code Block

{
    "timestamp": 1562837529912,
    "status": 200,
    "message": "OK",
    "errors": [],
    "data": false
}

Note

This API will work only if it is called from a skill from Luma, since some more information will be passed implicitly from the respective channel from where the user invokes the skill. This is not possible when the API is called directly from the REST client.

Create a new user

Use the following JSON code while creating a new user in Luma.

Request Code Block

POST: {{ENDPOINT}}/public/create-user
Request headers: Authorization =Bearer {{authorizationToken}}
OutBoundMapping:{  
   "firstName":"samson",
   "lastName":"wilson",
   "middleName":"john",
   "userName":"samson",
   "email":"samsonwilson@acmecompany.com",
   "recordsStatus":1,
   "title":"",
   "phone":"",
   "language":{  
      "id":6
   },
   "roles":[  
      {  
         "roleName":"Self-Service User"
      }
   ]
}

Copy the Inbound API Access Token from Luma and pass it in the Header as the Authorization – Bearer token by following the steps referred above.

Luma returns the following sample response when the user was created successfully.

Sample Response Code Block

{  
   "timestamp":1562831242123,
   "status":200,
   "message":"OK",
   "errors":[  

   ],
   "data":{  
      "id":15692,
      "tenant":1054,
      "createdDate":1563197759156,
      "createdByContact":{  
         "id":7,
         "name":"samson"
      },
      "modifiedDate":1563197759156,
      "modifiedByContact":{  
         "id":7,
         "name":"samson"
      },
      "recordsStatus":1,
      "createdBy":{  
         "id":7,
         "name":"samson wilson"
      },
      "modifiedBy":{  
         "id":7,
         "name":"samson wilson"
      },
      "subTenant":1,
      "userName":"samsonwilson",
      "email":"samsonwilson@gmail.com",
      "firstName":"samson",
      "lastName":"wilson",
      "middleName":"john",
      "title":"",
      "phone":"",
      "roles":[  
         {  
            "id":-4,
            "roleName":"Self-Service User",
            "isItsmRole":"No"
         }
      ],
      "lastUpdatedSource":"API",
      "language":{  
         "id":6,
         "createdDate":0,
         "modifiedDate":0,
         "recordsStatus":1,
         "subTenant":0
      }
   }
}

If the user already exists in Luma, and therefore was not created, then it returns the following sample response.

Sample Response Code Block

{  
    "timestamp": 1563864522283,
    "status": 500,
    "message": "Internal Server Error",
    "errors": [
        "Please enter a valid email address"
    ],
    "data": null
}

Update Global Attributes for a user

Use the following JSON code to update the global attributes for a user.

Request Code Block

POST: {{ENDPOINT}}/public/global-user-attributes/relate
Request headers: Authorization: Bearer {{inbound_api_access_token}}
Content-Type:application/json
OutBoundMapping:
{
"globalAttributeName":"location",
"contactId":15691,
"value":"test"
}

Copy the Inbound API Access Token from Luma and pass it in the Header as the Authorization – Bearer token by following the steps referred above.

Luma returns the following sample response.

Sample Response Code Block

{
    "timestamp": 1563771401124,
    "status": 200,
    "message": "OK",
    "errors": [],
    "data": {
        "id": 2,
        "tenant": 1058,
        "createdDate": 1553856119302,
        "createdByContact": {
            "id": 1,
            "name": "Sam"
        },
        "modifiedDate": 1563771401014,
        "modifiedByContact": {
            "id": 1,
            "name": "Sam"
        },
        "recordsStatus": 0,
        "createdBy": {
            "id": 1,
            "name": "Sam Wilson"
        },
        "modifiedBy": {
            "id": 1,
            "name": "Sam Wilson"
        },
        "subTenant": 1,
        "globalAttributeId": 1,
        "contactId": 1,
        "value": "test"
    }
}