About the Integration API

The Integration API is a RESTful API for work items. This gives customers the ability to have a real-time connection between Irth systems and their own applications.

Using the API, you can:

  • Get user and group information
  • Create and modify users and groups
  • Create a work item
  • Modify a work item
  • Retrieve a single work item
  • Retrieve a list of work items based on search criteria
  • Add an attachment to a work item
  • Retrieve an attachment from a work item
  • Link a work item to another work item or ticket

Getting Started

Before you get started, make sure:

  • Your company's account has the Integration API add-on feature. If you do not already have this add-on feature, contact your Irth Solutions sales representative for more information: http://www.irthsolutions.com/contact
  • You have access to the Integration Configuration page. This is a group-level permission that is granted to Administrators by default only.

Creating an Integration

An integration is a link between Irth systems and your external application. It is required in order for an application to access the API. Each integration has an API key and a selection of forms it is authorized to access. Multiple integrations can be configured if one application needs permission to a set of different forms than another application.

  1. From the Administration menu, choose Integration Configuration (under the Work Management column).
  2. Click Create New Integration.
  3. Give your integration a unique name and click Continue.
  4. Note the API key. This needs to be included in the header of requests to the API. See the Security section below for details.

Add Forms to an Integration

If you intend to utilize the API to interact with work items, it is necessary to add the necessary forms to it. Integrations only have access to forms assigned to them.

  1. On the integration's administrative page, click Add Form.
  2. Choose a form from the dropdown menu.
  3. Select the permissions that the form should granted. By default, all permissions are selected. See the Security section for an explanation of form-level permissions.

Security

API Key

Each integration has an API key which must be passed in the request header:

Authorization: basic [yourkey]

Permissions

In addition to your API key, your integration must set permissions for each form. This is done on the integration's settings in the Integration Configuration area.

General Permissions

Permission Description
GetUsers Allows the ability to view a filterable list of users
GetGroups Allows the ability to view a filterable list of groups
CreateUser Allows the ability to create a user
ModifyUser Allows the ability to modify a specific user
GetQualifications Allows the ability to view a filterable list of qualifications
ModifyUserQualifications Allows the ability to add or update a user's qualifications
DeleteUserQualifications Allows the ability to delete a user's qualifications

Form-Level Permissions

Permission Description
GetItem Allows the ability to view an item or a filterable list of items of a specific form type
Create Allows creation of a specific form
Modify Allows modification of items or linking of items for a specific form
GetAttachment Allows the ability to view an attachment of an item of a specific form type
AddAttachment Allows the ability to add an attachment to an item of a specific form
Assign Allows the ability to perform the Assign action on an item of this specific form type
Unassign Allows the ability to perform the Unassign action on an item of this specific form type

Status Codes

Code Status Description
200 OK Everything went fine
400 Bad Request Data is malformed or there are missing fields
401 Unauthorized API key is missing or invalid
403 Forbidden API method is not activated for form
404 Not Found Method does not exist
405 Method Not Allowed Improper action for a method (GET for a POST method, for example)
413 Record Limit Reached Only applies to the GetItems method. More than 1000 records exist for the query. Use filtering to limit the results. The first 1000 records are still returned when you receive this error.
422 Validation Failed Form did not pass validation and saveWithErrors is set to false
422 Entity Not Found No item or attachment is found with given ID

Error Object

If an error or warning occurs, the response object will return with an error object with description of the error or errors. 

{ 'errors' : [
    { '<<fieldName>>' : [<<error messages>>] }
]}

General Methods

Get Users

POST https://www.irth.com/Irthnet/api/Integration/GetUsers

Get a list of users based on search criteria.

Request

Attributes

One of the below attributes is required in the body of the request.

Name Type Description
Username string User's username is or contains.
Active boolean True if the user is not deleted.
Group object One of the below parameters is required but cannot be both.
Name string The name of the group
ID integer The unique group ID
LastName string User's lastname is or contains
HasExpiredQualifications boolean True if the user has operator qualifications that are expired.
JSON

[
    {
        "Username": "testuser",
        "Active": true,
        "Group": 
        {
            "Name": "Company Administrators",
            "ID": 12345
        },
        "LastName": "User",
        "HasExpiredQualifications": true
    }
]

Response

Name Type Description
Username string User's username
LastName string User's lastname
CallbackNumber string User's phone number
IsActive boolean True if the user is not deleted.
IsTicketUser boolean True if the user has ticket management access
IsWorkItemUser boolean True if the user has work item access
CanAutoDisable boolean True if the user can be automatically disabled
PasswordExpirationDays integer Number of days until password expires, if applicable
PrimaryEmail string User's primary email address
SecondaryEmail string User's secondary email address
PagerEmail string User's pager email address
Groups array of Group objects Groups to which the user belongs
ID integer The unique group ID
Name string The name of the group
Description string The description of the group
JSON
[
    {
        "Username": "testuser",
        "FirstName": "Test",
        "LastName": "User",
        "CallbackNumber": "614-555-1212",
        "IsActive": true,
        "IsTicketUser": true,
        "IsWorkItemUser": true,
        "CanAutoDisable": true,
        "PasswordExpirationDays": null,
        "PrimaryEmail": "testuser@irthsolutions.com",
        "SecondaryEmail": "testuser@anotherdomain.com",
        "PagerEmail": null,
        "Groups": [
            {
                "ID": 12345,
                "Name": "Company Administrators",
                "Description": "Company Administrators"
            }
        ]
    },
    [...]
]

Get Groups

POST https://www.irth.com/Irthnet/api/Integration/GetGroups

Get a list of groups based on search criteria.

Request

Attributes

Provide one of the below attributes in the request.

Name Type Description
Name string Group's name is or contains.
ID integer Unique ID of the group
JSON

[
    {
        "Name": "Company Administrators",
        "ID": 385,
    }
]

Response

Name Type Description
ID integer Unique ID of the group
Name string Name of the group
Description string The group's description
JSON
[
    {
        "ID": 385,
        "Name": "Company Administrators",
        "Description": "Company Administrators"
    },
    {
        "ID": 414,
        "Name": "Company Users",
        "Description": "Basic users of the company"
    },
    {
        "ID": 445,
        "Name": "Company Locators",
        "Description": "Locators"
    }
]

Create User

POST https://www.irth.com/Irthnet/api/Integration/CreateUser

Create a user in UtiliSphere.


Note: Attributes whose name are emboldened are required.

Request

Attributes
Name Type Description
Username string User's username
FirstName string User's first name
LastName string User's last name
CallbackNumber string User's phone number. Required for ticket management users.
IsActive boolean True if the user should be active and granted access.
IsTicketUser boolean True if the user has ticket management access
IsWorkItemUser boolean True if the user has work item access
CanAutoDisable boolean True if the user can be automatically disabled
PasswordExpirationDays integer Number of days until password expires, if applicable
PrimaryEmail string User's primary email address
SecondaryEmail string User's secondary email address
PagerEmail string User's pager email address
Groups array of Group objects Groups to which the user belongs. Specify only one of the below for each group.
ID integer The unique group ID
Name string The name of the group
Qualifications array of Qualifications Operator qualifications for the user.
QualificationID integer The unique qualification ID. Available from the GetQualifications API method.
ExpirationDateTime date/time Expiration date of the qualification for the user.
JSON
[
    {
        "Username": "testuser",
        "FirstName": "Test",
        "LastName": "User",
        "CallbackNumber": "614-555-1212",
        "IsActive": true,
        "IsTicketUser": true,
        "IsWorkItemUser": true,
        "CanAutoDisable": true,
        "PasswordExpirationDays": 1,
        "PrimaryEmail": "testuser@irthsolutions.com",
        "SecondaryEmail": "testuser@anotherdomain.com",
        "PagerEmail": "testpager@irth.com",
        "Groups": [
            {
                "ID": 12345,
                "Name": "Company Administrators"
            }
        ]
    }
]

Response

If the method executed successfully, the string "success" will return. Otherwise, an error object will return.

Name Type Description
error object An error if one exists.
JSON
[
    "success"
]

Modify User

POST https://www.irth.com/Irthnet/api/Integration/ModifyUser

Modify a user in UtiliSphere by Username.

Request

Attributes
Name Type Description
Username string User's username
FirstName string User's first name
LastName string User's last name
CallbackNumber string User's phone number. Required for ticket management users.
IsActive boolean True if the user should be active and granted access.
IsTicketUser boolean True if the user has ticket management access
IsWorkItemUser boolean True if the user has work item access
CanAutoDisable boolean True if the user can be automatically disabled
PasswordExpirationDays integer Number of days until password expires, if applicable
PrimaryEmail string User's primary email address
SecondaryEmail string User's secondary email address
PagerEmail string User's pager email address
Groups array of Group objects Groups to which the user belongs. Specify only one of the below for each group.
ID integer The unique group ID
Name string The name of the group
Qualifications array of Qualifications Operator qualifications for the user.
QualificationID integer The unique qualification ID. Available from the GetQualifications API method.
ExpirationDateTime date/time Expiration date of the qualification for the user.
JSON
[
    {
        "Username": "testuser",
        "FirstName": "Test",
        "LastName": "User",
        "CallbackNumber": "614-555-1212",
        "IsActive": true,
        "IsTicketUser": true,
        "IsWorkItemUser": true,
        "CanAutoDisable": true,
        "PasswordExpirationDays": 1,
        "PrimaryEmail": "testuser@irthsolutions.com",
        "SecondaryEmail": "testuser@anotherdomain.com",
        "PagerEmail": "testpager@irth.com",
        "Groups": [
            {
                "ID": 12345,
                "Name": "Company Administrators"
            }
        ]
    }
]

Response

If the method executed successfully, the string "success" will return. Otherwise, an error object will return.

Name Type Description
error object An error if one exists.
JSON
[
    "success"
]

Get Qualifications

POST https://www.irth.com/Irthnet/api/Integration/GetQualifications

Get a list of qualifications based on search criteria.

Request

Attributes

Provide only one of the below attributes in the request.

Name Type Description
Name string Qualification's name is or contains.
ID integer Unique ID of the qualification
JSON
[
    {
        "Name": "Test",
        "ID": 1,
    }
]

Response

Name Type Description
QualificationID integer Unique ID of the qualification
Name string Name of the qualification
Description string The qualification's description
JSON
[
    {
        "QualificationID": 1,
        "Name": "Test",
        "Description": "User has a test certification"
    }
]

Modify a User Qualification

POST https://www.irth.com/Irthnet/api/Integration/SaveUserQualification/<Username>

Updates or adds a new qualification for the user.

Parameters

Name Type Description
Username string The UtiliSphere Username of the person who's qualifications are being updated.

Request

Attributes
Name Type Description
QualificationID integer The unique qualification ID. Available from the GetQualifications API method.
ExpirationDateTime date/time Expiration date of the qualification for the user.

Example

JSON
{
    "QualificationID": 1,
    "ExpirationDateTime": "2024-05-18T17:09:39" 
}

Modify User Qualifications

POST https://www.irth.com/Irthnet/api/Integration/SaveUserQualifications/<Username>

Updates or adds a list of qualification for the user.
NOTE: Existing user qualifications that are not present in the request will be deleted

Parameters

Name Type Description
Username string The UtiliSphere Username of the person who's qualifications are being updated.

Request

Attributes
Name Type Description
Qualifications array of Qualifications Operator qualifications for the user.
QualificationID integer The unique qualification ID. Available from the GetQualifications API method.
ExpirationDateTime date/time Expiration date of the qualification for the user.

Example

JSON
[{
    "QualificationID": 1,
    "ExpirationDateTime": "2024-05-18T17:09:39" 
},{
    "QualificationID": 2,
    "ExpirationDateTime": "2024-05-22T17:09:39" 
}]

Delete a User Qualification

POST https://www.irth.com/Irthnet/api/Integration/DeleteUserQualification/<Username>/<QualificationID>

Removes a qualification from the user.

Parameters

Name Type Description
Username string The UtiliSphere Username of the person who's qualifications are being updated.
QualificationID integer The unique qualification ID. Available from the GetQualifications API method.

Create Map Layer

POST https://www.irth.com/Irthnet/api/Integration/CreateMapLayer

Creates a map layer in UtiliSphere.

Request

Attributes
Name Data Description
Layer Name string Name of the layer to be created (required and cannot be changed)
Type of Layer string One of the following values:
"ESRI Dynamic Map Layer", "ESRI Image Map Layer", "ESRI Tiled Map Layer", "ESRI Feature Layer","WFS Map Layer", "WMS Map Layer"
Endpoint string The URL serving features or tiles
Format string The mime type of the image e.g. 'image/png'
Minimum Zoom Level integer The zoom level that the layer should begin displaying: a Zoom level of 1 indicates the most visible area (the continental US is visible), 19 the least (roughly street level)
Maximum Zoom Level integer The zoom level that the layer should stop displaying: a Zoom level of 1 indicates the most visible area (the continental US is visible), 19 the least (roughly street level)
Opacity Decimal Number between 0 and 1, with 1 being fully opaque
Is Base layer boolean Is this layer a base map layer? This is almost always false.
CRS string One of the following coordinate reference systems supported by the layer's end point:
"EPSG3395", "EPSG3857", "EPSG4326", "EPSG900913" This is only used (and required) when the 'Type Of Layer' field is 'WFS map layer'
Position string The layer's relative position with respect to other custom layers 'Front' or 'Back'
Authentication Token string The Authentication token (if any) passed with the feature/tile request to the configured end point
Layer Names string Comma delimited list of layers to request from the WMS end point
Version string The WMS version supported by the end point e.g. 1.3.0

Example

JSON
{
	"Layer Name":"Layer Example",
    "Type Of Layer":"WMS Map Layer",
    "Endpoint":"https://irth.com/mapping/",
    "Format":"image/png",
    "Minimum Zoom Level":3,
    "Maximum Zoom Level":19,
    "Opacity":1,
    "Is Base Layer":false,
    "CRS":"EPSG4326",
    "Position":"Front",
    "Authentication Token":"4a31d08249ae40b0821783b202a919e4",
    "Layer Names":"Streets,Highways",
    "Version":"1.3.0"
}

Response

If the method executed successfully, a status of 200 is returned with the message "Map Layer was created successfully.".

Name Type Description
error string An error if one exists.
JSON
[
    "Status" : "Ok",
    "Message" : "Map Layer was created successfully"
]

Modify Map Layer

POST https://www.irth.com/Irthnet/api/Integration/ModifyMapLayer

Modify a map layer in UtiliSphere.

Note: In addition to Layer Name and Endpoint, specific attributes are required based on the Type of Layer specified as shown in Type of Layer Required Attributes table.

Request

Attributes
Name Data Description
Layer Name string Name of the layer to be modified (required and cannot be changed)
Type of Layer string One of the following values:
"ESRI Dynamic Map Layer", "ESRI Image Map Layer", "ESRI Tiled Map Layer", "ESRI Feature Layer","WFS Map Layer", "WMS Map Layer"
Endpoint string The URL serving features or tiles
Format string The mime type of the image e.g. 'image/png'
Minimum Zoom Level integer The zoom level that the layer should begin displaying: a Zoom level of 1 indicates the most visible area (the continental US is visible), 19 the least (roughly street level)
Maximum Zoom Level integer The zoom level that the layer should stop displaying: a Zoom level of 1 indicates the most visible area (the continental US is visible), 19 the least (roughly street level)
Opacity Decimal Number between 0 and 1, with 1 being fully opaque
Is Base layer boolean Is this layer a base map layer? This is almost always false.
CRS string One of the following coordinate reference systems supported by the layer's end point:
"EPSG3395", "EPSG3857", "EPSG4326", "EPSG900913" This is only used (and required) when the 'Type Of Layer' field is 'WFS map layer'
Position string The layer's relative position with respect to other custom layers 'Front' or 'Back'
Authentication Token string The Authentication token (if any) passed with the feature/tile request to the configured end point
Layer Names string Comma delimited list of layers to request from the WMS end point
Version string The WMS version supported by the end point e.g. 1.3.0

Type of Layer Required Attributes

Type of Layer Required Attributes
ESRI Dynamic Map Layer Layer Name, Opacity
ESRI Image Map Layer Layer Name, Endpoint, Opacity, Format
ESRI Tiled Map Layer, ESRI Feature Layer Layer Name, Endpoint
WMS Map Layer Layer Name, Endpoint, Layer Names, Version, Opacity, Format

Example

JSON
{
	"Layer Name":"Layer Example",
    "Type Of Layer":"WMS Map Layer",
    "Endpoint":"https://irth.com/mapping/",
    "Format":"image/png",
    "Minimum Zoom Level":3,
    "Maximum Zoom Level":19,
    "Opacity":1,
    "Is Base Layer":false,
    "CRS":"EPSG4326",
    "Position":"Front",
    "Authentication Token":"4a31d08249ae40b0821783b202a919e4",
    "Layer Names":"Streets,Highways",
    "Version":"1.3.0"
}

Response

If the method executed successfully, the string "success" will return. Otherwise, an error object will return.

Name Type Description
error string An error if one exists.
JSON
[
    "success"
]

Get Data Source

GET https://www.irth.com/Irthnet/api/Integration/GetDataSource/<Name>

Get a Data Source in UtiliSphere.

Parameters

Name Data Description
Name string Name of the data source in UtiliSphere (required)

Response

Name Type Description
Name string Name of the data source (unique and cannot be changed)
Data Array An array of an array of values.
The first array will be treated as the field names for the rest of the data
JSON
{
	"Name":"Data Source Name",
	"Data":[
        [
            "Field 1", 
            "Field 2", 
            "Field 3"
        ],
		[
            "row 0 value 1",
            "row 0 value 2",
            "row 0 value 3"
        ],
		[
            "row 1 value 1", 
            "row 1 value 2", 
            null
        ],
		[
            "row 2 value 1", 
            "row 2 value 2", 
            "row 2 value 3"
        ]
	]
}

Create Data Source

POST https://www.irth.com/Irthnet/api/Integration/CreateDataSource

Create a Data Source in UtiliSphere.

Request

Attributes
Name Data Description
Name string Name of the data source to be created (required, must be unique and cannot be changed later)
Data Array An array of an array of values.
The first array will be treated as the field names for the rest of the data

Example

JSON
{
	"Name":"Data Source Name",
	"Data":[
        [
            "Field 1", 
            "Field 2", 
            "Field 3"
        ],
		[
            "row 0 value 1",
            "row 0 value 2",
            "row 0 value 3"
        ],
		[
            "row 1 value 1", 
            "row 1 value 2", 
            null
        ],
		[
            "row 2 value 1", 
            "row 2 value 2", 
            "row 2 value 3"
        ]
	]
}

Response

If the method executed successfully, the string "success" will return. Otherwise, an error object will return.

Name Type Description
error string An error if one exists.
JSON
[
    "success"
]

Modify Data Source

POST https://www.irth.com/Irthnet/api/Integration/ModifyDataSource

Modify a Data Source in UtiliSphere.

Request

Attributes
Name Data Description
Name string Name of the data source to be modified (required and cannot be changed)
Data Array An array of an array of values.
The first array will be treated as the field names for the rest of the data

Example

JSON
{
    "Name":"Data Source Name",
    "Data":[
	    [
            "Field 1", 
            "Field 2", 
            "Field 3"
        ],
	    [
            "row 0 value 1",
            "row 0 value 2",
            "row 0 value 3"
        ],
	    [
            "row 1 value 1", 
            "row 1 value 2", 
            null
        ],
	    [
            "row 2 value 1", 
            "row 2 value 2", 
            "row 2 value 3"
        ]
    ]
}

Response

If the method executed successfully, the string "success" will return. Otherwise, an error object will return.

Name Type Description
error string An error if one exists.
JSON
[
    "success"
]

Get Work Logs

POST https://www.irth.com/Irthnet/api/Integration/GetWorkLogs

Get user work logs in UtiliSphere.

Note: Start and End date is required and one of Username, supervisor, or group is required.

Request

Attributes
Name Data Description
Username string User's username is or contains
Supervisor string Supervisor's username is or contains
Group object One of the below parameters is required but cannot be both.
Name string The name of the group
ID integer The unique group ID
StartDate date/time Start date of work logs.
EndDate date/time End date of work logs.

Example

JSON
{
    "Username":"testuser",
    "Supervisor":"testsupervisor",
    "Group":
    {
        "Name": "Company Administrators",
        "ID": 12345
    },
    "StartDate":"2024-05-11",
    "EndDate":"2024-05-18"
}

Response

Name Type Description
Username string User's username
FirstName string User's first name
LastName string User's last name
Supervisor string User's supervisor's username
EmployeeID string User's employee id
HomeState string User's home state
TimeZone string User's time zone
IsActive boolean True if the user is not deleted.
IsTicketUser boolean True if the user has ticket management access
IsWorkItemUser boolean True if the user has work item access
CanAutoDisable boolean True if the user can be automatically disabled
PasswordExpirationDays integer Number of days until password expires, if applicable
IncludeInPayroll boolean True if the user is in the payroll export
ReceivesVehicleFringeAdjustment boolean True if the user receives a fringe adjustment
CallbackNumber string User's phone number
PrimaryEmail string User's primary email address
SecondaryEmail string User's secondary email address
PagerEmail string User's pager email address
Groups array of Group objects Groups to which the user belongs
ID integer The unique group ID
Name string The name of the group
Description string The description of the group
WorkLogEntries array of Work Log Entry objects Work Logs created by the user
TicketLocateInfoID int Ticket Locate Info ID of the user's "Start/End Work" action (will be null if this is a "Check In/Out")
CaseID int Work Item ID of the user's "Start/End Work" action (will be null if this is a "Check In/Out")
StartTime date/time Start time of the entry
EndTime date/time End time of the entry
StartLat double Latitude where the user started the time entry
StartLon double Longitude where the user started the time entry
EndLat double Latitude where the user ended the time entry
EndLon double Longitude where the user ended the time entry
OnCall boolean True if the user was on call
PTO boolean True if the time entry was for PTO
PTODetails string Type of PTO
WorkReason string Work Reason of the time entry
JSON
[
    {
        "Username": "testuser",
        "FirstName": "Test",
        "LastName": "User",
        "Supervisor": "testsupervisor",
        "EmployeeID": "abc123",
        "HomeState": "OH",
        "TimeZone": "Eastern Standard Time",
        "IsActive": true,
        "IsTicketUser": true,
        "IsWorkItemUser": true,
        "CanAutoDisable": true,
        "PasswordExpirationDays": 1,
        "IncludeInPayroll": true,
        "ReceivesVehicleFringeAdjustment": true,
        "CallbackNumber": "614-555-1212",
        "PrimaryEmail": "testuser@irthsolutions.com",
        "SecondaryEmail": "testuser@anotherdomain.com",
        "PagerEmail": "testpager@irth.com",
        "Groups": [
            {
                "ID": 12345,
                "Name": "Company Administrators",
                "Description": "Company Administrators"
            }
        ],
        "WorkLogEntries": [
            {
                "TicketLocateInfoID": 12345,
                "CaseID": null,
                "StartTime": "2024-05-18T09:09:39",
                "EndTime": "2024-05-18T17:09:39",
                "StartLat": 40.06231332631171,
                "StartLon": -83.101977388199529,
                "EndLat": 40.06231332631171,
                "EndLon": -83.101977388199529,
                "OnCall": false,
                "PTO": true,
                "PTODetails": "Vacation",
                "WorkReason": "Time Off"
            }
        ]
    },
    [...]
]

Form Field Data Types

Below are the field types supported by the Integration API. Proper data formatting is validated by the API in addition to any field validations set with the App Designer.

Data Type Accepted Value Supports Filters Example
Multiple Choice An array of one or more strings Yes
(single select)		 
"SingleChoice" : "My choice"
"MultiChoice" : ["First choice", "Second choice"]
Yes/No A string value of "Yes" or "No" Yes 
"AddBacon" : "Yes"
"AddLettuce" : "No"
Text A string Yes 
"Company Name" : "Irth Solutions"
Number A numerical value Yes 
"Quantity" : "50"
"Distance" : "5.009"
Currency USD or CAD Yes 
"Amount" : "$50.09"
Date A date passed as a string - must be in yyyy-MM-dd format. Yes 
"OrderDate" : "2017-03-31"
Date/Time A date/time passed as a string - must be in yyyy-MM-ddTHH:mm format. Times should be passed in GMT. Yes 
"OrderTime" : "2017-03-31T08:30"
Time A time passed as a string - must be in HH:mm:ss format. Times should be passed in GMT. Yes 
"OrderTime" : "13:30:00"
Phone Number US or Canadian phone number Yes 
"Phone" : "1-800-555-1212"
Location A location object
(Required fields indicated in App Designer) 		Yes 
"DeliveryAddress": {
"Name": "DeliveryAddress",
"Address": "5009 Horizons Dr",
"Place": "Columbus",
"County": "",
"State": "OH",
"Zip": "43220",
"Country": "United States",
"Lat": 40.0626826002229,
"Lon": -83.1020415646657
}
Mailing Address An address object
(Required fields indicated in App Designer) 		Yes 
"DeliveryAddress": {
"Name": "DeliveryAddress",
"Address": "5009 Horizons Dr",
"Place": "Columbus",
"County": "",
"State": "OH",
"Zip": "43220",
"Country": "United States"
}
Email A string with a valid email address Yes 
"Email" : "somebody@example.com"
Signature A base64 string Yes 
"CustomerSig" : "<<base64 string>>"
Photo A photo object:
  • Data: A base64-encoded image binary
  • FileName: A string with the desired file name
  • MimeType: The image's MIME type (jpg, png, or gif)
  • Note: An optional string
 Yes 
"Pic": {
"Data": "<<base64 encoded image binary>>",
"FileName": "house.jpg",
"MimeType": "image/jpg", 
"Note": "Customer house"
}
Data List A field from a data source
  • Must match the field type indicated in the App Designer
 No 
"Category" : "Food",
"Type" : "Vegetables",
"Options" : ["Carrots", "Peas"]
Component A component object
  • Must include required fields for component
  • Value types must match
  • Can only pass multiple components if specified in App Designer
 Yes 
"FoodPicker" : [
{
    "Values" : {
        "Item" : "Hamburger",
        "Quantity" : "2"
    }
},
{
    "Values" : {
        "Item" : "Fries",
        "Quantity" : "2"
    }
}
]

Methods

Assign Ticket

POST https://www.irth.com/Irthnet/api/Integration/AssignTicket/<ID>/<Username>

Assigns or unassigns a ticket to a specified user

Parameters

Name Type Description
ID string The Irth systems identifier of the ticket to assign the user to
Username string Desired username to assign the ticket to (unassigns item if this is not included)

Response

If the method executed successfully, the string "success" will return. Otherwise, an error object will return.

Name Type Description
error string An error if one exists.
JSON
[
    "success"
]

Methods

Create Item

POST https://www.irth.com/Irthnet/api/Integration/CreateWorkItem

Create a new item.

Request

Attributes
Name Type Description
FormName string The name of the form used to create the item
CategoryName string The category to which the form belongs
ExternalID
(optional)		 string Optional custom ID field that can be used to get the item after creation. Note that this ID is unique for your company rather than per work item type.
Values object JSON object containing name/value pairs of item.
SaveWithErrors boolean true to save item with validation errors. Default is false
RelatedItems object An array of related items. As defined below.
ItemID integer Work Item ID or Ticket ID
DisplayID string Work Item Display ID or Ticket OCC Ticket ID
Type string Work Item form name or "Ticket" for tickets
Status string The related Work Item's status
DueDate Date/Time The related Work Item's due date
FormatName string The related Work Item's format name
FormID integer The related Work Item's Form ID
CategoryID integer The related Work Item's Category ID
IsChild boolean True of the related Work Item is a child, otherwise false.
TicketLocateID integer The Ticket Locate ID. Required if the related item is a ticket.
TicketCreatedTime Date/Time The related ticket's created time.
FacilityType string The related ticket's facility type.
Version integer The related ticket's version number.
OneCallCenter string The related ticket's one call center.
IsTicket boolean True if the related item is a ticket, otherwise false.
IsSubform boolean True if the related item is a subform, otherwise false.

Response

Name Type Description
ItemId integer Internal ID of the created object
error
(optional)		 object Error object if an error occurred
JSON
{
    "ItemId" : "1"
}

Update Item

POST https://www.irth.com/Irthnet/api/Integration/UpdateWorkItem

Update an item with a given ID.

Invoked using the same request parameters as Create Item The 'ItemID' or 'ExternalID' parameter of the request object must match the item to be updated
Set the OnlyUpdateProvided parameter to true to change the behavior of the endpoint. Instead of removing values from fields that aren't provided, values will be updated only for the fields provided. Locations, Address, and Attachments can be updated this way. Any Subforms provided will overwrite any current values. For example, if you have 3 subform items and you pass only one, the item will be updated to only include the one you provided. If you leave it empty, however, it will retain the current value.
For a photo field, to remove the value, do not pass the field in the request and omit the OnlyUpdateProvided parameter. To change the value, pass in a new value. To retain the current value, pass in the AttachmentID, or use the OnlyUpdateProvided .

Request

Attributes
Name Type Description
FormName string The name of the form used to create the item
CategoryName string The category to which the form belongs
ItemID
(required if no ExternalID)		 integer Irth systems internal item identifier
ExternalID
(required if no ItemID)		 string Optional custom ID field that can be used to get the item after creation. Note that this ID is unique for your company rather than per work item type.
Values object JSON object containing name/value pairs of item.
Note: For unchanged attachments, you may include the "AttachmentID" only
RelatedItems object An array of related items. As defined below.
ItemID integer Work Item ID or Ticket ID
DisplayID string Work Item Display ID or Ticket OCC Ticket ID
Type string Work Item form name or "Ticket" for tickets
Status string The related Work Item's status
DueDate Date/Time The related Work Item's due date
FormatName string The related Work Item's format name
FormID integer The related Work Item's Form ID
CategoryID integer The related Work Item's Category ID
IsChild boolean True of the related Work Item is a child, otherwise false.
TicketLocateID integer The Ticket Locate ID. Required if the related item is a ticket.
TicketCreatedTime Date/Time The related ticket's created time.
FacilityType string The related ticket's facility type.
Version integer The related ticket's version number.
OneCallCenter string The related ticket's one call center.
IsTicket boolean True if the related item is a ticket, otherwise false.
IsSubform boolean True if the related item is a subform, otherwise false.

Response

Name Type Description
id string Internal ID of the created object
error
(optional)		 object Error object if an error occurred
JSON
{
    "ItemId" : "1"
}

Update Status

POST https://www.irth.com/Irthnet/api/Integration/UpdateStatus/<ID>/<IdentifierType>

Parameters

Name Type Description
ID string The Irth systems identifier or ExternalID of the item to retrieve
IdentifierType string 0 if the ID is an Irth systems identifier, 1 if ExternalID
Assumed 0 (Irth systems identifier) if not specified

Request

Attributes
Name Type Description
Status string The name of the status
(Required if StatusID is not provided)
StatusID int The Irth systems identifier for the status
(Required if Status is not provided)		 
{
    "Status": "Open",
    "StatusID": 0
}

Link Items

POST https://www.irth.com/Irthnet/api/Integration/AddLink/<ID>/<IdentifierType>

Link an item to another item or ticket.

Parameters

Name Type Description
ID string The Irth systems identifier or ExternalID of the item to retrieve
IdentifierType string 0 if the ID is an Irth systems identifier, 1 if ExternalID
Assumed 0 (Irth systems identifier) if not specified

Request

Name Type Description
ItemID string The Irth Systems identifier or ExternalID of the item to be linked to.
IdentifierType string 0 if the ItemID is an Irth systems identifier, 1 if ExternalID
Assumed 0 (Irth systems identifier) if not specified
Type string “Ticket” or the form name of the work item to be linked to
JSON

    {
    "ItemID": "Unique item identifier",
    "IdentifierType": "1",
    "Type": "Ticket",
    }

Response

If the method executed successfully, the string "success" will return. Otherwise, an error object will return.

Name Type Description
error object An error if one exists.
JSON
[
    "success"
]

Get Item

GET https://www.irth.com/Irthnet/api/Integration/GetItem/<ID>/<IdentifierType>

Get an item by ID.

Parameters

Name Type Description
ID string The Irth systems identifier or ExternalID of the item to retrieve
IdentifierType string 0 if the ID is an Irth systems identifier, 1 if ExternalID
Assumed 0 (Irth systems identifier) if not specified

Response

Name Type Description
CreateDateTime Date/Time The creation date/time in UTC
ExternalID string Custom identifier of the item, if any
ItemId integer Irth systems identifier of the item
DisplayId string Item's display identifier on the summary screen
FormId integer Unique identifier of item's form
Form string The name of the item's form
Category string The category of the item's form
Status string The work item's status (open or closed)
ScheduledDate Date/Time The item's scheduled date/time in UTC
AssignedToUser object An assigned user object
ID integer The assigned user's identifier
Username string The assigned user's username
Name string The assigned user's name
Email string The assigned user's email address
Values object Name/value collection of the item's fields and values
Attachments object Attachments, if any
RelatedItems object Related items to the item, if any
Audit object Audit history of the event
Description string Description of the event
Time string Date of the event, in yyyy-MM-ddTHH:mm format
error
(optional)		 object Error object if an error occurred
JSON
{
    "CreateDateTime": "Item create date/time in UTC",
    "ItemID": "Unique item identifier",
    "DisplayID": "Summary display identifier of item",
    "ExternalID": "Your custom item identifier, if any",
    "FormID": "Unique form identifier",
    "Name": "Form's name",
    "Category": "Form's category",
    "ScheduledDate": "Item's scheduled date",
    "AssignedToUser": {
    "ID": "User ID",
    "Username": "User's username",
    "Email": "User's email address"
    },
    "Values": {
    "field1" : "value1",
    "field2" : "value2",
    ...
    },
    "Attachments": [
    "Attachments, if any"
    ],
    "RelatedItems": [
    "Related items, if any "
    ],
    "Audit": [
    "Item history events"
    ]
}

Get Items

POST https://www.irth.com/Irthnet/api/Integration/GetItems

Get items for a given form based on search criteria.

Request

Attributes
Name Type Description
Form string The name of the form.
Category string The form's category.
Filters object An array of filters that can be applied - a filter acts as a search of items. See the Filters section below for detailed information.
FieldName string Name of the field to perform filter against
Operation string The filter operation (see table below)
Value
(optional)		 string Value for filter (if used, must be matching data type)
JSON
{
    "form" : "Book Orders",
    "category" : "E-Commerce",
    "filters" : [
        {
            "FieldName" : "quantity",
            "Operation" : "EQUAL_OR_GREATER_THAN",
            "Value" : "3"
        },
        {
            "FieldName" : "order date",
            "Operation" : "DATE_BETWEEN",
            "Value" : "2017-03-01 & 2017-03-02"
        }
    ]
}

Response

Name Type Description
items object The returned items
error
(optional)		 object Error object if an error occurred
JSON
[
    { object 1 },
    { object 2 },
    { ... }
]

Get Statuses

GET https://www.irth.com/Irthnet/api/Integration/GetStatuses/<Category Name>/<Form Name>

Gets the available statuses for a form

Parameters

Name Type Description
Category Name string The Category of the form.
Form Name string The Name of the form.

Response

Name Type Description
StatusID int Internal ID of the status
Name string The Name of the status
IsClosedStatus boolean Is the status a 'closed' status
JSON
[
    {
        "StatusID": 0,
        "Name": "Status Zero",
        "IsClosedStatus": false
    },
    {
        "StatusID": 1,
        "Name": "Status One",
        "IsClosedStatus": true
    }
]

Get Attachment

GET https://www.irth.com/Irthnet/api/Integration/GetAttachment/<attachmentID>

Get the base64 string of an attachment by ID.

Parameters

Name Type Description
attachmentID string The ID of the attachment to retrieve

Response

Name Type Description
AttachmentId integer The id of the attachment
FileName string The file name of the attachment
MimeType string File type of the attachment
Data base64 string The returned attachment in base64 format
error
(optional)		 object Error object if an error occurred
JSON

    {
    "AttachmentId": 999,
    "FileName" : "logo.png",
    "MimeType": "image/png",
    "Data": "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",
    }

Add Attachment

POST https://www.irth.com/Irthnet/api/Integration/AddAttachment/<ID>/<IdentifierType>

Add an attachment to an item.

Parameters

Name Type Description
ID string The Irth systems identifier or ExternalID of the item to which to add the attachment.
IdentifierType string 0 if the ID is an Irth systems identifier, 1 if ExternalID
Assumed 0 (Irth systems identifier) if not specified

Request

Attributes
Name Type Description
Data base64 string base64 encoded string of the attachment
FileName string Desired file name of attachment
Note
(optional)		 string Optional comment 

    {
    "Data" : "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",
    "FileName" : "logo.png",
    "Note" : "Hi"
    }

Response

Name Type Description
id string Internal ID of the created attachment
error
(optional)		 object Error object if an error occurred
JSON
{"id" : "1"}

Assign Item

POST https://www.irth.com/Irthnet/api/Integration/Assign/<ID>/<Username>/<IdentifierType>

Assigns or unassigns an item to a specified user

Parameters

Name Type Description
ID string The Irth systems identifier of the work item to assign the user to
Username string Desired username to assign the item to (unassigns item if this is not included)
IdentifierType string 0 if the ID is an Irth systems identifier, 1 if ExternalID
Assumed 0 (Irth systems identifier) if not specified

Response

If the method executed successfully, the string "success" will return. Otherwise, an error object will return.

Name Type Description
error string An error if one exists.
JSON
[
    "success"
]

Unassign Item

POST https://www.irth.com/Irthnet/api/Integration/Unassign/<ID>/<IdentifierType>

Unassigns an item

Parameters

Name Type Description
ID string The Id of the work item to unassign
IdentifierType string 0 if the ID is an Irth systems identifier, 1 if ExternalID
Assumed 0 (Irth systems identifier) if not specified

Response

If the method executed successfully, the string "success" will return. Otherwise, an error object will return.

Name Type Description
error string An error if one exists.
JSON
[
    "success"
]

Filters

When querying for items with GetItems, a filter object is required. The filter allows you to narrow down search results. If you want all items for a form, you can pass an empty filter object. Otherwise, there are various ways to filter item data.

Filter Operations

The following operations can be used in your filter.

Text Operands

Operator Description
IS_NULL Field value is null
NOT_NULL Field value is not null
EQUALS Field value is equal to filter value
LIKE Field value is like filter value
BEGINS_WITH Field value begins with filter value
ENDS_WITH Field value ends with filter value

Number Operands

Operator Description
IS_NULL Field value is null
NOT_NULL Field value is not null
EQUALS Field value is equal to filter value
NOT_EQUAL Field value is not equal to filter value
GREATER_THAN Field value greater than filter value
LESS_THAN Field value less than filter value
EQUAL_OR_GREATER_THAN Field value &rt;= filter value
EQUAL_OR_LESS_THAN Field value <= than filter value

Multiple Choice Fields Operands

Operator Description
IS_NULL Field value is null
NOT_NULL Field value is not null
EQUALS Field value is equal to filter value
NOT_EQUAL Field value is not equal to filter value

Address/Location Fields Operands

Operator Description
IS_NULL Field value is null
NOT_NULL Field value is not null
LIKE A part of the address matches the filter

Date Operands

Operator Description
IS_NULL Field value is null
NOT_NULL Field value is not null
IS_N_MINUTES_FROM_NOW Field value is N minutes within current time
IS_WITHIN_LAST_N_MINUTES Field value is within N minutes in the past
IS_OLDER_THAN_N_MINUTES Field value is more than N minutes in the past
DATE_BETWEEN Field value within date range (in UTC). Make sure you take your time zone into consideration.
TIME_BETWEEN Field value within date/time range (in UTC). Make sure you take your time zone into consideration.

Other Operands

Can be used with any other field type.

Operator Description
IS_NULL Field value is null
NOT_NULL Field value is not null

Supported Field Types

The following field types are available for filtering operations.

Field Type Operand Examples
Multiple Choice (single-select only) Multiple Choice 
{
    "FieldName" : "Flavor",
    "Operation" : "EQUALS",
    "Value" : "Chocolate"
}
Address/Location Address/Location 
{
    "FieldName" : "MailingAddress",
    "Operation" : "LIKE",
    "Value" : "5009 Horizons Dr"
}
Yes/No Multiple Choice 
{
    "FieldName" : "LikesChocolate",
    "Operation" : "EQUALS",
    "Value" : "Yes"
}
Text Text 
{
    "FieldName" : "CollegeName",
    "Operation" : "EQUALS",
    "Value" : "The Ohio State University"
},
{
    "FieldName" : "FavoriteTeam",
    "Operation" : "LIKE",
    "Value" : "Buckeyes"
},
{
    "FieldName" : "FavoriteAnimal",
    "Operation" : "NOT_NULL"
}
integer integer 
{
    "FieldName" : "Quantity",
    "Operation" : "EQUALS",
    "Value" : "3"
},
{
    "FieldName" : "NumberOfPets",
    "Operation" : "EQUAL_OR_GREATER_THAN",
    "Value" : "2"
}
Currency integer 
{
    "FieldName" : "Price",
    "Operation" : "EQUAL_OR_LESS_THAN",
    "Value" : "50.00"
}
Date/Time Date 
{
    "FieldName" : "DigDate",
    "Operation" : "DATE_BETWEEN",
    "Value" : "2017-03-01 & 2017-03-22"
}
{
    "FieldName" : "DigDate",
    "Operation" : "TIME_BETWEEN",
    "Value" : "2017-03-01T08:00 & 2017-03-01T09:00"
}
Phone Text 
{
    "FieldName" : "HomePhone",
    "Operation" : "EQUALS",
    "Value" : "(614)555-1212"
},
{
    "FieldName" : "CellPhone",
    "Operation" : "BEGINS_WITH",
    "Value" : "(212)"
}
Email Text 
{
    "FieldName" : "EmailAddress",
    "Operation" : "ENDS_WITH",
    "Value" : "@domain.com"
}
Signature Other 
{
    "FieldName" : "Sig",
    "Operation" : "NOT_NULL"
}
Photo Other 
{
    "FieldName" : "BackyardPicture",
    "Operation" : "NOT_NULL"
}
Component
[FormFieldName].[ComponentFieldName]		 Depends on field target 
{
    "FieldName" : "Employee.IsMarried",
    "Operation" : "EQUALS",
    "Value" : "Yes"
},
{
    "FieldName" : "Employee.FirstName",
    "Operation" : "LIKE",
    "Value" : "Bob"
}

System Fields

In addition to form field types, the following system fields can be used in filtering operations.

Field Name Operand Examples
Create time Date 
{
    "FieldName" : "Create time",
    "Operation" : "DATE_BETWEEN",
    "Value" : "2017-03-22 & 2017-03-22"
}
Update time Date 
{
    "FieldName" : "Update time",
    "Operation" : "DATE_BETWEEN",
    "Value" : "2017-03-22 & 2017-03-22"
}
Due time Date 
{
    "FieldName" : "Due time",
    "Operation" : "DATE_BETWEEN",
    "Value" : "2017-03-22T09:00 & 2017-03-22T10:00"
}
Status Text 
{
    "FieldName" : "Status",
    "Operation" : "EQUALS",
    "Value" : "Open"
}
Item Closed Text 
{
    "FieldName" : "Item Closed",
    "Operation" : "EQUALS",
    "Value" : "False"
}
Folder Text (EQUALS operator only) 
{
    "FieldName" : "Folder",
    "Operation" : "EQUALS",
    "Value" : "My Custom Folder"
}

Webhooks

Using the Process Automation with Webhook devices, you can send items to your own systems triggered by certain events. This allows your applications to be in sync with work items in Irth systems. Below are steps to set up webhooks. Confirm that your systems are capable of consuming the webhook messages.

Set Up a Web Request Device

The first step is to create a web request device. This is the communication mechanism that creates a relationship between Irth systems and an external application.

  1. In order to set up webhook devices, you will need the Web Request device add-on feature.
  2. Click on Devices under "General" from the Administration menu.
  3. Click on Go to Web Request Device Summary
  4. Click on Add a Web Request Device
  5. Name the device and enter the URL endpoint. Make sure Webhook is selected under the "Protocol" drop-down list.
  6. Irth recommends you create a secret key so that you can ensure the request is being sent by Irth. This will be sent in the header as: 
    Authorization: basic [key]

Set Up a Process Rule

Now that the web request device has been created, data can be sent to the URL endpoint with a process rule.

  1. Click on Process Automation under "Work Management" from the Administration menu.
  2. Click on Create New Rule and give the new rule a unique name.
  3. Select the forms for the rule.
  4. Select the events that trigger the rule to run.
  5. Select any conditions that must be met for the rule to run. This is optional.
  6. Select actions that will happen when the rule is run. This is optional.
  7. Click on Add Notification and choose "Device message format" for the protocol. Configure the schedule if you require a custom schedule for the rule.
  8. Select your web device from the list of devices.
  9. Now, when the rule is triggered, a POST is sent to the URL endpoint specified in the web request device. The body of this request is a JSON object of the item, exactly as it appears in the GetItem API call. The header of the request will contain your secret key for the device if you specified one.