Tuhund - Register Service Request API

API # : 8040 | API Name : registersr

This API is used to register a Service Request in Tuhund.

URL : <domain>/apic/registersr
Methods Allowed : POST

The registersr API is used to create and register a Service Request in the Tuhund platform. It is the primary interface for capturing service related incidents such as breakdowns, complaints, maintenance requests and operational issues originating from customer portals, mobile applications, third party systems or internal tools.

This API is designed to support both strict ID based integrations and flexible name based integrations. For most reference entities, the API accepts either system identifiers, descriptive names or a combination of both. When an identifier is provided, the system validates its existence and links the request to the corresponding record. When an identifier is not provided, the system intelligently probes existing master data using a balanced score card based matching mechanism, evaluating multiple attributes to identify the most appropriate existing record. This approach enables seamless integration even when upstream systems do not maintain Tuhund internal IDs.

Upon successful validation and resolution of all related entities, the API registers the service request and associates it with the relevant company, branch, customer, address, assets, assignments and activities. The request is then placed into Tuhund’s Service Management workflow where it can be assigned, scheduled, worked upon, monitored and closed.

The API supports comprehensive service request data in a single call, including service items, materials consumed, assignments, technician activity logs, images, documents and site address details. This allows external systems to create a fully contextualised service request without requiring multiple follow up API calls.

The system enforces business validations, permission checks and organisational rules during registration. Where name based matching is used, resolution outcomes are internally logged, ensuring traceability and preventing unintended duplication. Behaviour in cases of ambiguous matches is governed by system configuration, which may include rejection, manual review or controlled master creation.

On successful registration, Tuhund generates or confirms a unique Service Request reference, which can be used for tracking, reporting, billing and all subsequent operations such as updates, reassignment and closure.

This API is built for enterprise scale usage and is suitable for high volume, transactional and automated integrations while maintaining data integrity, operational clarity and long term master data hygiene.

 

Payload Schema :

Postman Collection (v2.1)

Request Headers :

Name Description
device A short name of your application. Device is mandatory but any value between 3 and 20 characters is accepted.
Authentication Authentication code generated for API call.

Sample Payload 1 :

Sample Payload 2:

Sample Response :

Error Codes

Error Code Error Scope Message Description
80401001 payload There seems to an error in the payload structure. Please check the payload The request payload structure is invalid or malformed
80401002 payload Failed to parse the payload into a valid request object Payload could not be deserialised into the expected request object
80401003 payload branchid (Branch ID) is a mandatory field Mandatory field branchid is missing
80401004 payload branchid (Branch ID) incorrect. No active branch or entity found with ID The provided branchid does not match any active branch
80401005 payload companyid (Company ID) is a mandatory field Mandatory field companyid is missing
80401006 payload companyid (Company ID) incorrect. No active company found with ID The provided companyid does not match any active company
80401007 payload categoryid (Category ID) is a mandatory field Mandatory field categoryid is missing
80401008 payload categoryid (Category ID) incorrect. No active category found with ID The provided categoryid does not match any active category
80402001 item Failed to parse item number N Item object could not be parsed correctly
80402002 item productid, model or productname and brand are missing for item N Insufficient product identification details were provided
80402003 item productid for item N does not correspond to any product Provided productid does not exist or is inactive
80402004 item Failed to create product record for item N System failed to resolve or create product during item processing

Note : N represents the item sequence number in the items array.

Root Object: Service Request

Core Identification and Context

Field Type Mandatory Description
categoryid string Yes* Unique identifier of the service category. If provided, existence is validated
categoryname string Yes* Category name used for name based resolution when categoryid is not provided
companyid string Yes* Unique company identifier. Validated if present
companyname string Yes* Company name used for balanced score card matching when companyid is not provided
branchid string Yes Branch or organisational unit under which the service request is registered
parentid string No Parent service request ID for linked or follow up requests
parent string No Human readable parent reference

* Either ID or name must be provided

Request Lifecycle Dates

Field Type Mandatory Description
requestdate string Yes Date and time when the service request was registered
problemdate string No Date and time when the problem was first observed
startdate string No Actual service work start date
finishdate string No Date when service work was completed
closingdate string No Date when the service request was formally closed
finishedin number No Total time taken to complete the request in system defined units

Caller and Ownership

Field Type Mandatory Description
callerid string No Identifier of the caller or reporting person
callername string No Name of the caller used for matching if ID is not provided
recieverid string No User or system that received or logged the request
assignedto string No Primary resource or employee assigned to the request

Request Details

Field Type Mandatory Description
summary string Yes Short summary of the service issue
description string No Detailed description of the issue
problemtype string No Type of issue such as BREAKDOWN or MAINTENANCE
status number Yes Current status code of the service request
ltype number No Logical or linking type for advanced workflows
lid string No Linked entity identifier based on ltype

Agent and Resource Information

Field Type Mandatory Description
agentid string No Assigned service agent identifier
agentname string No Agent name used for resolution
agenttag string No Agent role or tag
agentshortname string No Short display name of the agent

Effort and Financials

Field Type Mandatory Description
estimatedcharges number No Estimated service charges
finalcharges number No Final billed service charges
effort number No Total effort in hours
effortcost number No Cost associated with effort
materialcost number No Cost of materials used
materialvalue number No Value of materials issued
expenses number No Additional expenses incurred
othercharges number No Any miscellaneous charges
billed number No Indicates whether the service is billed

Items Array

Represents service items or assets involved.

items[]

Field Type Mandatory Description
summary string Yes Summary of the service item
inventoryid string No Inventory reference
productid string No Product identifier
productname string No Product name used for matching
producttype number No Product classification
serial string No Serial number
snid string No Internal serial identifier
ciid string No Configuration item ID
model string No Product model
brand string No Product brand
productdescription string No Product description
problemsummary string No Item specific issue
status number No Item level status
estimatedcharges number No Estimated item charges
finalcharges number No Final item charges

Warranty and Assembly

Field Type Mandatory Description
warrantyid string No Warranty record ID
warrantynumber string No Warranty number
warrantyterms string No Warranty coverage terms
warrantyvalidity number No Warranty validity in months
startdate string No Warranty start date
enddate string No Warranty end date
assebmlyid string No Assembly ID
assebmlycode string No Assembly code
assebmlyname string No Assembly name
assebmlyserial string No Assembly serial
categoryid string No Item specific category

Material Array

Represents consumables or spares used.

material[]

Field Type Mandatory Description
productid string Yes* Material product identifier
materialname string Yes* Material name for matching
unitid string Yes Unit of measure
required number Yes Quantity required
used number No Quantity used
price number No Unit price
billable number No Indicates billable material
billed number No Billing status
producttype string No Material type
materialcategoryid string No Material category
sourceid string No Source store or location
hscode string No Harmonised system code

* Either productid or materialname is required

Assignments Array

assignments[]

Field Type Mandatory Description
assignedto string Yes Resource assigned
assignedby string No Assigned by
assignmentdate string Yes Assignment date and time
proposeddate string No Proposed service date
status string Yes Assignment status
duration number No Planned duration
actualduration number No Actual duration
effortrate number No Cost per hour
resourcecost number No Calculated resource cost

Activity Array

activity[]

Field Type Mandatory Description
personid string Yes Person performing the activity
timein string Yes Activity start time
timeout string No Activity end time
duration number No Duration in minutes
comments string No Activity remarks
recordedby string No Logged by
subid string No Activity subtype
xc number No Latitude
yc number No Longitude

Images Array

images[]

Field Type Mandatory Description
imageid string No Image identifier
filepath string Yes File storage path
filename string Yes Image file name
fileformat string Yes File format
filesize number No File size in bytes
width number No Image width
height number No Image height
title string No Image title
uploaddate string No Upload date
position number No Display order

Attachments Array

attachments[]

Field Type Mandatory Description
attachmentid string No Attachment identifier
docid string No Document ID
title string Yes Document title
filepath string Yes File path
originalname string Yes Original file name
filetype string Yes File type
filesize number No File size
addeddate string No Date added
addedby string No Added by
locked number No Lock status

Address Object

address

Field Type Mandatory Description
addressid string Yes* Address identifier
addresstitle string No Address title
address string Yes Address line
city string Yes City
stateid string Yes* State identifier
state string Yes* State name
postcode string Yes Postal code
countrycode string Yes Country code
countryname string Yes Country name
phone1 string No Primary phone
mobile string No Mobile number
email string No Email
addresstype string No Address usage type
iscurrent number No Indicates active address
xc number No Latitude
yc number No Longitude

* ID or name based resolution applies

 

Tuhund Logo
TUHUND®
Home About us Modules CRM HR SALES BI SERVICES MANAGEMENT INVENTORY MANAGEMENT ACCOUNTING AND FINANCE PROCUREMENT PROJECT MANAGEMENT ERP ADMINISTRATION DATA REPOSITORY API & SUB PORTALS Careers Community Blog
M Home Schedule Demo About us Community Blog
CRM HR SALES BI SERVICES MANAGEMENT INVENTORY MANAGEMENT ACCOUNTING AND FINANCE PROCUREMENT PROJECT MANAGEMENT ERP ADMINISTRATION DATA REPOSITORY API & SUB PORTALS Careers
API Documents
Request Demo