Overview:

The API is only available for Unee-T Enterprise Users.

This API allows a 3rd party application to create a case in Unee-T.

If you specify any invalid fields, an error will be thrown stating which field is invalid. If you specify any field you are not allowed to set, they will just be set to their defaults or ignored.

API Key in Header vs API Key in body:

It is possible to specify the API key either

  • In the body of the payload:
    "apiKey": "xxxxxxx"
  • Outside the body of the payload in an Authorization https header:
    Authorization: Bearer xxxxxxx

The Property associated to the case:

When a case is created the Property where the incident happened MUST be specified as part of the payload.

Internal Unee-T Ids vs Aliases:

Properties and users can be identified by

  • Their internal Unee-T “unit_id” or “user_id”
    OR
  • An alias for this internal Unee-T “unit_id” or “user_id”.

Option 1: Use Unee-T Internal “unit_id” and (optional) “user_id” :

For more details on

Option 2: Use aliases for “unit_id” and (optional) “user_id”:

Some organization may prefer to use their own unique internal ID for the property instead of the “unit_id” and their own unique internal ID for the optional “user_id” too.

This allows the 3rd party app to only store the Master API key and use their internal id when they need to interact with Unee-T.

The aliases for the “mefe_unit_id” and optional “user_id”:

  • MUST be unique.
  • MUST be identical to the alias that was used to create the Unit or User in Unee-T. See the [documentation on the API to create a unit] for more information.

Case Assignee:

As explained in the feature Highlight for cases, Unee-T has a built in automatic case routing engine. It is possible to override the default “Assignee” for the case and replace it with a specific user.

  • The user MUST be allowed to see cases for this property.
  • The user specified by this attribute must have been created by the user associated with the ‘apiKey‘ (See below).

Case Reporter:

Unee-T also automatically captures the information about the user who created the case (the Reporter – for more information see the Unee-T feature Overview).

The API allows the 3rd party app to define who the “Reporter” is for the newly created case. This allows the 3rd party app to create cases “on behalf of” another user.

  • This user MUST be allowed to see and create cases for this property.
  • The user specified by this attribute must have been created by the user associated with the ‘apiKey‘ (See below).

How it works:

Request:

To create a new case in Unee-T

POST https://case.unee-t.com/api/cases

There are only 4 mandatory parameters that MUST be set, or an error will be thrown. These parameters are marked in bold in the section below:

  • apiKey
  • unitId or unitAliasId
  • title
  • assignedRole

You can also set 11 additional optional parameters when you create a case:

  • details
  • category
  • subCategory
  • assigneeId or assigneeAliasId
  • reporterId or reporterAliasId
  • severity
  • priority
  • solution
  • nextSteps
  • solutionDeadline
  • nextStepsBy

Details on the information you can specify when you create a case:

NameTypeDescriptionExample of payload
apiKeystringThe Master API key for the 3rd party App. “Mq9wLSeimafdausbqMeO9yUGao”
unitId
or
unitAliasId
String unitId: The unique id for this unit in Unee-T
or
unitAliasId: The unique id for the unit in your internal system.

The payload MUST include either the unitId or the unitAliasId
unitId: “THNMpfpMeRhZ4adwnU”
or
unitAliasId: “SG_SIN_LUM_01-02”
titleStringA title for the case“Not hot water in the kitchen”
assignedRoleStringThe role that we are assigning the case to. This MUST be one of the followning values:
– “Management Company”
– “Tenant”
– “Owner/Landlord”
– “Agent”
“Management Company”
detailsStringMore information about the case“This was working well yesterday but as of this morning the water is still flowing but is cold”
categorystringIf nothing is sent, the default value “” is used.

If you specify a value for category, you MUST use one of the following categories:
– “—“
– “Furnitures/Fixtures”
– “Appliances/Equipment”
– “Electrical”
– “Plumbing”
– “Aircon/Heating”
– “Structural”
– “Landscape”
– “Housekeeping”
– “Extra Service”
– “Projects”
– “Other”
– “Utilities”
– “Devices”
– “Maintenance”
– “Renovation”
– “Repair”
– “Other”
“Plumbing “
subCategorystringIf nothing is sent, the default value “” is used.

If you specify a value for subCategory , you MUST use one of the following subCategory :

A subCategory can be Generic or Specific.

Generic subCategories are applicable to any category.

The Generic subCategory are:
– “—“
– “Repair”
– “Maintenance”
– “Replace”
– “Other”

Specific subCategory are only applicable to certain categories:

Category “Housekeeping”
Allowed Specific subCategory:
– “Cleaning”
– “Linens”
– “Textile”
– “Curtains”
– “NOT SPECIFIED”

Category “Extra Service”
Allowed Specific subCategory:
– “Extra Furnitures/Fixtures”
– “Housekeeping”
– “Ironing”
– “Laundry”
– “Cable Upgrade”
– “Internet Upgrade”
– “Transportation”
– “Early/Late”

Category “Utilities”
Allowed Specific subCategory:
– “Electricity”
– “Water”
– “Gas”
– “Internet”
– “Cable”

Category “Projects”
Allowed Specific subCategory:
– “Set Up”
– “Refurbishing”
– “Check”
– “Light Renovation”
– “Renovation”
– “Hand Over”

Category “Other”
Allowed Specific subCategory:
– “Security”
– “Viewing”
“Repair”
assigneeId
or
assigneeAliasId
stringThis should only be used if the desired assignee is not the default assignee for the role specified under ‘assignedRole‘.

assigneeId : The “user_id” of the user who should be the assignee of the case.
or
assigneeAliasId: The alias ID associated to the “user_id” for the user who’ll be assigned to this case, in the context of the user specified by ‘apiKey‘.
assigneeId: “e6mFnhN6HtT3trsuh”
or
assigneeAliasId: “john.smith@example.com”
reporterId
or
reporterAliasId
stringThis should only be used if the desired Reporter is not the same as the generic user associated to ‘apiKey‘.

This allows a 3rd party app to report a case “on behalf of” a Unee-T user.

The user specified by this attribute must have been created by the user associated with ‘apiKey‘.

reporterId : The “user_id” of the user who will be recorded as the Reporter of this case.
or
reporterAliasId: The alias ID associated to the “user_id” for the user who will be recorded as the Reporter of this case.
reporterId: “e6mFnhN6HtT3trsuh”
or
reporterAliasId: “john.smith@example.com”
severitystringIf nothing is sent, the default value “normal” is used.

If you specify a value for severity you MUST use one of the following value for severity:
– “DEAL BREAKER!“
– “critical“
– “major“
– “normal“
– “minor “
“CONFIRMED”
prioritystringIf nothing is sent, the default value “P2” is used.

If you specify a value for priority you MUST use one of the following value for priority:
– “P1”
– “P2”
– “P3”
“P1”
solution string How are we going to resolve that case.“We need to replace the water heater”
nextSteps string Description of the next action that needs to be taken so we can resolve this case“Get a quote from a contractor to estimate the cost of replacing the water heater.”
solutionDeadlinedateWhen is this case supposed to be resolved“2019-06-15”
nextStepsBy datetimeWhen is the Next Step supposed to happen“2019-06-13 12:00:00”

Response:

The response is the ID for the new case.

Example response body: (Contains the new case’s id)

{
    "id": 73464
}

Examples of Payloads:

With Unee-T internal Ids for unit and userWith aliases for unit and user
with the API Key in the Body{
"apiKey": "Mq9wLSeim7iusbqMeO9yUGao",
"unitId": "THNMpfpMeRhZ2bLnU",
"title": "test api 2",
"details": "detailssssss",
"assignedRole": "Tenant",
"category": "Electrical",
"subCategory": "Maintenance",
"assigneeId": "e6mFnhN6HtT6tSguh"
}
{
"apiKey": "Mq9wLSeim7iusbqMeO9yUGao",
"unitAliasId": "myUnitAlias",
"title": "test api 2",
"details": "detailssssss",
"assignedRole": "Tenant",
"category": "Electrical",
"subCategory": "Maintenance",
"assigneeAliasId": "john.smith@example.com"
}
With the API Key in the header{
"unitId": "THNMpfpMeRhZ2bLnU",
"title": "test api 2",
"details": "detailssssss",
"assignedRole": "Tenant",
"category": "Electrical",
"subCategory": "Maintenance",
"assigneeId": "e6mFnhN6HtT6tSguh"
}
{
"unitAliasId": "myUnitAlias",
"title": "test api 2",
"details": "detailssssss",
"assignedRole": "Tenant",
"category": "Electrical",
"subCategory": "Maintenance",
"assigneeAliasId": "john.smith@example.com"
}

Test it in the DEMO environment:

The Endpoint in the Unee-T Demo environment

POST https://case.demo.unee-t.com/api/cases

Demo Organization Key: “BBrTJFXgiFTbsNmuetn51xk5”

Demo Units:

  • SG_SIN_LUM_39-05:
    • mefe_unit_id: (unitId) “0UYwxsizPVzxzHAIH”
    • Alias (unitAliasId) “DEMO_SG_SIN_LUM_39-05”
  • SG_SIN_RW_13-01_02R:
    • mefe_unit_id: (unitId) “1bqaVGSlCpC6mMCqE”
    • Alias (unitAliasId) “DEMO_SG_SIN_RW_13-01_02R”
  • SG_SIN_6SK-A_03-01
    • mefe_unit_id: (unitId) “2LUqFOtEv0aKnEdq7”
    • Alias (unitAliasId) “DEMO_SG_SIN_6SK-A_03-01”

Demo Users

  • Community Manager:
    • mefe_user_id: (reporterId or assigneeId)
      “NkhmByXN4vKPgrfYe”
    • Alias (reporterAliasId or assigneeAliasId)
      “demo.email+cm_1@unee-t.com”
  • Help Desk:
    • mefe_user_id: (reporterId or assigneeId)
      “w4KF5fiBzMnmmhcGQ”
    • Alias (reporterAliasId or assigneeAliasId)
      “demo.email+help_sg@unee-t.com”
  • Field Person 1:
    • mefe_user_id: (reporterId or assigneeId)
      “NYZsX4wWssksjbAi4”
    • Alias (reporterAliasId or assigneeAliasId)
      “demo.email+fp_1@unee-t.com”
  • Field Person 2:
    • mefe_user_id: (reporterId or assigneeId)
      “mRyp2M3dKPuF8FFBY”
    • Alias (reporterAliasId or assigneeAliasId)
      “demo.email+fp_2@unee-t.com”

Leave a Reply