You are using an unsupported browser. Please update your browser to the latest version on or before July 31, 2020.
close
API for Asset Management
print icon

API provided by the HappyFox helpdesk is a RESTful web service. It supports operations like creating a ticket, adding updates to a ticket, listing tickets and users of the Helpdesk. It supports JSON, Form Url encoded and Multipart Form Data formats as payload.

 

Requirements:

The API requires following skills in any programming language.

  • Making HTTP requests (using GET and POST HTTP methods as a minimum requirement).
  • Doing HTTP Basic Authentication.
  • Generating and reading data in the JSON format.
  • Optionally making HTTP POST requests using content type of "multipart/form-data" (needed for ticket attachments)

Documentation Conventions:

The documentation indicates parameters that need to be replaced with actual values using the format . The entire string including the enclosing < and > should be replaced.

For example, if the parameter email is it should be replaced with the required email address

Endpoint url format: 

 

Eg. https://customersuppport.happyfox.com/api/1.1/

Note: If you are using a custom domain, please use the custom domain url

API key and auth code are to be passed in Basic HTTP authentication format only.

 A full constructed example url is shown below.

https://customersuppport.happyfox.com/api/1.1/json/assets/

This knowledge base article consists of all operations that can be done via the tickets endpoint.

If your HappyFox account is hosted in EU, please use .happyfox.net

 

1.Read all assets

2.Read one asset by asset ID

3.Create asset

4.Update asset

5.Delete asset

6.Read all asset custom fields

7.Read one asset custom field by id

8.Read all asset types

9.Asset type details

 

1.Read all assets

 

This returns a paginated list of all assets in your HappyFox account.

 

API Endpoint url: /api/1.1/json/assets/?asset_type=<asset_type_ID>&size=<size value>&page=<page number>

 

HTTP Method: GET

 

Parameter Required Description
size No Number of assets to return per page.
Default page size is 10.
Maximum allowed page size is 50
page No Page Number
asset_type Yes ID of the asset type which is required. If this query parameter is not passed, assets belonging to the first asset type will be returned

 

 

Sample results:

{
    "page_info": {
        "count": 10, 
        "last_index": 198, 
        "page_count": 20, 
        "start_index": 1, 
        "end_index": 10
    }, 
    "data": [
        {
            "display_id": "2", 
            "name": "21", 
            "contacts": [], 
            "created_by": 1, 
            "id": 659, 
            "asset_type": {
                "id": 1, 
                "name": "General"
            }, 
            "custom_fields": [
                {
                    "name": "Serial Number", 
                    "type": "text", 
                    "order": 1, 
                    "value": null, 
                    "id": 45
                }, 
                {
                    "name": "Manufacturer", 
                    "type": "text", 
                    "order": 2, 
                    "value": null, 
                    "id": 46
                }, 
                {
                    "name": "Model", 
                    "type": "text", 
                    "order": 3, 
                    "value": null, 
                    "id": 47
                }
            ], 
            "updated_by": 1
        }, 
        {
            "display_id": "ADDISD-W10PC", 
            "name": "ADDISD-W10PC", 
            "contacts": [
                {
                    "email": "dwayne.wade@gmail.com", 
                    "name": "Dwyane Wade", 
                    "id": 27662
                }
            ], 
            "created_by": 1, 
            "id": 6748, 
            "asset_type": {
                "id": 1, 
                "name": "General"
            }, 
            "custom_fields": [
                {
                    "name": "Serial Number", 
                    "type": "text", 
                    "order": 1, 
                    "value": "GCJ1353", 
                    "id": 45
                }, 
                {
                    "name": "Manufacturer", 
                    "type": "text", 
                    "order": 2, 
                    "value": "Dell", 
                    "id": 46
                }, 
                {
                    "name": "Model", 
                    "type": "text", 
                    "order": 3, 
                    "value": "Latitude 5500", 
                    "id": 47
                }
            ], 
            "updated_by": 1
        }, 
        {
            "display_id": "ALEXANDRAS-W10P", 
            "name": "ALEXANDRAS-W10P", 
            "contacts": [], 
            "created_by": 1, 
            "id": 6749, 
            "asset_type": {
                "id": 1, 
                "name": "General"
            }, 
            "custom_fields": [
                {
                    "name": "Serial Number", 
                    "type": "text", 
                    "order": 1, 
                    "value": "CB62BT2", 
                    "id": 45
                }, 
                {
                    "name": "Manufacturer", 
                    "type": "text", 
                    "order": 2, 
                    "value": "Dell", 
                    "id": 46
                }, 
                {
                    "name": "Model", 
                    "type": "text", 
                    "order": 3, 
                    "value": "OptiPlex 3060", 
                    "id": 47
                }
            ], 
            "updated_by": 1
        }, 
        {
            "display_id": "ALEXS-W10PC", 
            "name": "ALEXS-W10PC", 
            "contacts": [], 
            "created_by": 1, 
            "id": 6750, 
            "asset_type": {
                "id": 1, 
                "name": "General"
            }, 
            "custom_fields": [
                {
                    "name": "Serial Number", 
                    "type": "text", 
                    "order": 1, 
                    "value": "JYG42B3", 
                    "id": 45
                }, 
                {
                    "name": "Manufacturer", 
                    "type": "text", 
                    "order": 2, 
                    "value": "Dell", 
                    "id": 46
                }, 
                {
                    "name": "Model", 
                    "type": "text", 
                    "order": 3, 
                    "value": "Latitude 5520", 
                    "id": 47
                }
            ], 
            "updated_by": 1
        }, 
        {
            "display_id": "AMANDAO-W10PC", 
            "name": "AMANDAO-W10PC", 
            "contacts": [], 
            "created_by": 1, 
            "id": 6751, 
            "asset_type": {
                "id": 1, 
                "name": "General"
            }, 
            "custom_fields": [
                {
                    "name": "Serial Number", 
                    "type": "text", 
                    "order": 1, 
                    "value": "4V2W433", 
                    "id": 45
                }, 
                {
                    "name": "Manufacturer", 
                    "type": "text", 
                    "order": 2, 
                    "value": "Dell", 
                    "id": 46
                }, 
                {
                    "name": "Model", 
                    "type": "text", 
                    "order": 3, 
                    "value": "Latitude 5500", 
                    "id": 47
                }
            ], 
            "updated_by": 1
        }, 
        {
            "display_id": "AMANDAZ-W10PC", 
            "name": "AMANDAZ-W10PC", 
            "contacts": [], 
            "created_by": 1, 
            "id": 6752, 
            "asset_type": {
                "id": 1, 
                "name": "General"
            }, 
            "custom_fields": [
                {
                    "name": "Serial Number", 
                    "type": "text", 
                    "order": 1, 
                    "value": "2ZG42B3", 
                    "id": 45
                }, 
                {
                    "name": "Manufacturer", 
                    "type": "text", 
                    "order": 2, 
                    "value": "Dell", 
                    "id": 46
                }, 
                {
                    "name": "Model", 
                    "type": "text", 
                    "order": 3, 
                    "value": "Latitude 5520", 
                    "id": 47
                }
            ], 
            "updated_by": 1
        }, 
        {
            "display_id": "AMYK-VDI", 
            "name": "AMYK-VDI", 
            "contacts": [], 
            "created_by": 1, 
            "id": 6753, 
            "asset_type": {
                "id": 1, 
                "name": "General"
            }, 
            "custom_fields": [
                {
                    "name": "Serial Number", 
                    "type": "text", 
                    "order": 1, 
                    "value": "CBB8BT2", 
                    "id": 45
                }, 
                {
                    "name": "Manufacturer", 
                    "type": "text", 
                    "order": 2, 
                    "value": "Dell", 
                    "id": 46
                }, 
                {
                    "name": "Model", 
                    "type": "text", 
                    "order": 3, 
                    "value": "OptiPlex 3060", 
                    "id": 47
                }
            ], 
            "updated_by": 1
        }, 
        {
            "display_id": "AMYM-W10PC", 
            "name": "AMYM-W10PC", 
            "contacts": [], 
            "created_by": 1, 
            "id": 6754, 
            "asset_type": {
                "id": 1, 
                "name": "General"
            }, 
            "custom_fields": [
                {
                    "name": "Serial Number", 
                    "type": "text", 
                    "order": 1, 
                    "value": "9L66Y93", 
                    "id": 45
                }, 
                {
                    "name": "Manufacturer", 
                    "type": "text", 
                    "order": 2, 
                    "value": "Dell", 
                    "id": 46
                }, 
                {
                    "name": "Model", 
                    "type": "text", 
                    "order": 3, 
                    "value": "LATITUDE 5520", 
                    "id": 47
                }
            ], 
            "updated_by": 1
        }, 
        {
            "display_id": "ANITAM-W10PC", 
            "name": "ANITAM-W10PC", 
            "contacts": [], 
            "created_by": 1, 
            "id": 6755, 
            "asset_type": {
                "id": 1, 
                "name": "General"
            }, 
            "custom_fields": [
                {
                    "name": "Serial Number", 
                    "type": "text", 
                    "order": 1, 
                    "value": "613X9G3", 
                    "id": 45
                }, 
                {
                    "name": "Manufacturer", 
                    "type": "text", 
                    "order": 2, 
                    "value": "Dell", 
                    "id": 46
                }, 
                {
                    "name": "Model", 
                    "type": "text", 
                    "order": 3, 
                    "value": "Latitude 5520", 
                    "id": 47
                }
            ], 
            "updated_by": 1
        }, 
        {
            "display_id": "ANTONIOV-W10PC", 
            "name": "ANTONIOV-W10PC", 
            "contacts": [], 
            "created_by": 1, 
            "id": 6756, 
            "asset_type": {
                "id": 1, 
                "name": "General"
            }, 
            "custom_fields": [
                {
                    "name": "Serial Number", 
                    "type": "text", 
                    "order": 1, 
                    "value": "HWG42B3", 
                    "id": 45
                }, 
                {
                    "name": "Manufacturer", 
                    "type": "text", 
                    "order": 2, 
                    "value": "Dell", 
                    "id": 46
                }, 
                {
                    "name": "Model", 
                    "type": "text", 
                    "order": 3, 
                    "value": "Latitude 5520", 
                    "id": 47
                }
            ], 
            "updated_by": 1
        }
    ]
}

2. Read one asset by asset ID

 

Each asset and its details can be accessed using this API endpoint

 

API Endpoint: /api/1.1/json/asset/<id>/

 

HTTP Method: GET

 

Sample result:

{
    "display_id": "2", 
    "name": "21", 
    "contacts": [], 
    "created_by": 1, 
    "id": 659, 
    "asset_type": {
        "id": 1, 
        "name": "General"
    }, 
    "custom_fields": [
        {
            "name": "Serial Number", 
            "type": "text", 
            "order": 1, 
            "value": null, 
            "id": 45
        }, 
        {
            "name": "Manufacturer", 
            "type": "text", 
            "order": 2, 
            "value": null, 
            "id": 46
        }, 
        {
            "name": "Model", 
            "type": "text", 
            "order": 3, 
            "value": null, 
            "id": 47
        }
    ], 
    "updated_by": 1
}

3. Create asset

 

API Endpoint: /api/1.1/json/assets/?asset_type=<asset_type_id>

 

Query Parameter:

 

asset_type is the only mandatory parameter here. Please pass ID of the asset type in which this asset should be created. If this query parameter is not passed, asset will be created in the first asset type.
 

 

HTTP Method: POST

 

Payload fields:

 

Field Type Is Required? Description
name String Yes Name of the asset
display_id String Yes Display ID of the asset for the UI
contact_ids List No IDs of existing contacts to be linked to this asset. Refer this doc to fetch IDs of contacts
contacts List No This has to be a JSON array with the details of new contacts to be linked created, along with asset creation.
Required fields for each element in the JSON array are name and email/phone number.
For an agent to create contacts when creating or updating an asset, the agent should have Manage all Contacts permission
custom fields JSON No JSON array of custom field and their values for this asset
created_by Integer Yes ID of the agent that who is creating this asset. Refer this article to see agents list in your HappyFox account

 

Only an active agent who has Manage Assets permission can create an asset.

 

Rules for specifying custom field values in request data for the above option:

 

Custom Field Type Value format Example
Text String “Lorem ipsum”
Textarea String “Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor”
Number integer 12
Dropdown ID of the option to be set 1
Multiple options ID of options to be selected [1,2,3]
Date YYYY-MM-DD 2020-12-25

 

Example payload:

{
    "name": "Macbook pro v1",
    "display_id": "macbook_pro_v1",
    "contact_ids": ["1"],
    "contacts": [
        {"email": "donald@example.com"}
    ],
    "created_by": 1,
    "custom_fields": {
        "1": "1",
        "2": "Macbook Pro - 2020",
        "3": "This is the most recent version of the available Macbook Pro",
        "4": "C034234ZHY", v// number custom field
        "5": 4, // dropdown custom field
        "6": [3, 4], //multiple option custom field
        "7": 2020-11-15  // date custom field
    }
}

Example Successful Response (status code - 200)


{
    "id": 13,
    "name": "Macbook Pro",
    "display_id": "mac_d11pro",
    "created_by": 1,
    "created_at": "2019-11-15T07:49:40Z",
    "updated_by": null,
    "updated_at": "2019-11-15T07:49:40Z",
    "contacts": [
        {
            "email": "john@example.com",
            "id": 1,
            "name": "John"
        },
        {
            "email": "donald@example.com",
            "id": 2,
            "name": "Donald"
        }
    ],
    "custom_fields": [
        {
            "id": 1,
            "name": "Asset Category",
            "type": "dropdown",
            "value": 1,
            "order": 1
        },
        {
            "id": 2,
            "name": "Description",
            "type": "textarea",
            "value": null,
            "order": 2
        }
    ]
}

 

Example failure response in case of validation errors (status code - 400)
 

{
  "error": {
    "display_id": [
      "This field is required."
    ],
    "contact_ids": "Enter a list of values.",
    "custom_fields": {
      "1": "Provide a valid choice. 5 is not one of the available choices."
    }
  }
}

4. Update asset

 

API Endpoint: /api/1.1/json/asset/<id>/

 

HTTP Method: PUT

 

Payload fields:

 

Field Type Is Required? Description
name String yes Name of the asset
display_id string Yes Display ID of the asset for the UI
contact_ids List No IDs of existing contacts to be linked to this asset. Refer this doc to fetch IDs of contacts
contacts List No This has to be a JSON array with the details of new contacts to be linked, along with asset updating process.
Required fields for each element in the JSON array are name and email/phone number.
For an agent to create contacts when creating or updating an asset, the agent should have Manage all Contacts permission
custom fields JSON No JSON array of custom field and their values for this asset
created_by Integer Yes ID of the agent that who is updating this asset. Refer this article to see agents list in your HappyFox account

 

Example Request

 

{
    "name": "Macbook pro 2019 15' inch Retina",
    "updated_by": 1,
    "contact_ids": [2]
}

Example Successful Response (status code - 200)

 

{
    "id": 2,
    "name": "Macbook pro 2019 15' inch Retina",
    "display_id": "mac_1pro",
    "created_by": 1,
    "created_at": "2019-11-15T06:43:51Z",
    "updated_by": 1,
    "updated_at": "2019-11-15T08:00:14Z",
    "contacts": [
        {
            "email": "john@example.com",
            "id": 2,
            "name": "John"
        }
    ],

   "asset_type":

                   { "id": 1, "name": "General" },
    "custom_fields": [
        {
            "id": 1,
            "name": "Asset Category",
            "type": "dropdown",
            "value": 1,
            "order": 1
        },
        {
            "id": 2,
            "name": "Description",
            "type": "textarea",
            "value": null,
            "order": 2
        }
    ]
}

 

5. Delete asset

API Endpoint: /api/1.1/json/asset/<asset id>/?deleted_by=<staff id>

 

HTTP Method: DELETE

 

Request Query Parameters:

 

Parameter Is Required? Description
deleted_by Yes ID of the agent who is making the request

 

Only an active agent who has Manage Assets permission can delete an asset

 

 

6. Read all asset custom fields

 

API Endpoint: /api/1.1/json/asset_custom_fields/?asset_type=<asset_type_ID>&size=<page_size>&page=<page_no>

 

HTTP Method: GET

 

Request Query Parameters:

 

Parameter Is Required? Description
size No Number of assets to return per page
Default page size is 10.
Maximum allowed page size is 50
page No Page Number
asset_type Yes ID of the asset type. If this query parameter is not passed, custom fields belonging to the first asset type will be returned

 

Example Response (status code - 200)

 

{
    "page_info": {
        "count": 5,
        "last_index": 5,
        "page_count": 1,
        "start_index": 1,
        "end_index": 5
    },
    "data": [
        {
            "id": 45,
            "type": "text",
            "asset_type": {
                "id": 1,
                "name": "General"
            },
            "name": "Serial Number",
            "choices": null
        },
        {
            "id": 46,
            "type": "text",
            "asset_type": {
                "id": 1,
                "name": "General"
            },
            "name": "Manufacturer",
            "choices": null
        },
        {
            "id": 47,
            "type": "text",
            "asset_type": {
                "id": 1,
                "name": "General"
            },
            "name": "Model",
            "choices": null
        },
        {
            "id": 56,
            "type": "number",
            "asset_type": {
                "id": 1,
                "name": "General"
            },
            "name": "Numbers acquired",
            "choices": null
        },
        {
            "id": 57,
            "type": "date",
            "asset_type": {
                "id": 1,
                "name": "General"
            },
            "name": "Warranty Date",
            "choices": null
        }
    ]
}

 

7. Read one asset custom field by id

 

API Endpoint: /api/1.1/json/asset_custom_fields/<id>/

 

HTTP Method: GET

 

Example Response (status code - 200)

 

{
    "id": 45,
    "type": "text",
    "asset_type": {
        "id": 1,
        "name": "General"
    },
    "name": "Serial Number",
    "choices": null
}

 

8. Read all asset types

 

API Endpoint: /api/1.1/json/asset_types/

 

HTTP Method: GET

 

Sample response:

{

    "page_info": {

        "count": 2,

        "page_count": 1,

        "last_index": 2,

        "start_index": 1,

        "end_index": 2

    },

    "data": [

        {

            "description": null,

            "id": 1,

            "name": "General",

            "settings": {

                "enable_ticket_association": true,

                "enable_contact_association": true,

                "enable_asset_quantity_for_ticket": true

            }

        },

        {

            "description": "",

            "id": 2,

            "name": "Device",

            "settings": {

                "enable_ticket_association": true,

                "enable_contact_association": false,

                "enable_asset_quantity_for_ticket": false

            }

        }

    ]

}

 

9. Asset type details

 

API Endpoint: /api/1.1/json/asset_type/<asset type id>/

 

HTTP Method: GET

 

Example response:

 

{
    "description": null,
    "id": 1,
    "name": "General",
    "settings": {
        "enable_ticket_association": true,
        "enable_contact_association": true,
        "enable_asset_quantity_for_ticket": true
    }
}
 

Feedback
0 out of 0 found this helpful

scroll to top icon