API Endpoint	{account_url}/api/v2/public/requesters/
Method	POST
Request Data	create or update requester(s)

 

Create or Update Requester

• This endpoint allows you to create or update single requester(s) in Service Desk.

• If a requester already exists, it will be updated with the new details.
• If a requester does not exist, a new requester will be created.

Bulk Create or Update Requester

• This endpoint also allows you to bulk create or update requester(s) in Service Desk.
• For bulk create/update, the payload should be a list of requester objects following the same format as the single create/update.
• For bulk create/update, you will be able to create or update a maximum number of 300 requester objects per API request.

Parameters

Parameter	Required	Description
email	*Yes	Email address of the requester
name	*Yes	Name of the requester
phones	*Yes	List of phone numbers of the requester
custom_fields	No	Custom fields of the requester
skip_mandatory_requester_custom_fields_check	No	Skip mandatory check for requester cfs. Defaults to false

 

Note:

Case 1: If email is present

• name is not mandatory. Name will be constructed from the email if not passed.
• phones list is not mandatory.

Case 2: If email is not present

• name is mandatory.
• phones list is mandatory. Minimum one object with is_primary = true should be present in the list.
• If no object is marked as primary, the first object in the list will be considered as primary.

Criteria to decide whether a requester already exists or not:

1. If email is present, we will check if a requester with the same email exists.
2. If email is not present, we will check if a requester with the same name and primary phone number exists.
3. If more than one requester with the same name and phone number exists, we will return an error.
4. If skip_mandatory_requester_custom_fields_check is not passed or passed as false, we will check if all the mandatory custom fields are present in the payload. If any mandatory custom field is missing, we will return an error.

Authorization

Basic Auth

Authorization: Basic <auth_token>

Sample Request for single create or update Requester

{
    "email": "lisa.taylors@happyfox.com",
    "name": "Lisa Taylor",
    "custom_fields": {
        "1": "Test", // Text type custom field
        "2": 1, // Dropdown type custom field. Value is id of the option.
        "3": [1, 2], // Multi select type custom field. Value is list of ids of the options.
        "4": "2021-05-08", // Date type custom field. Value is in yyyy-mm-dd.
        "5": 100 // Number type custom field
    }
}

{
    "name": "Lisa Taylor",
    "phones": [
        {
            "type": "main",
            "number": "7887679890",
            "is_primary": true
        },
        {
            "type": "mobile",
            "number": "5213456745"
        }
    ],
    "custom_fields": {
        "1": "Sample", // Text type custom field
        "2": 1, // Dropdown type custom field. Value is id of the option.
        "3": [1, 2], // Multi select type custom field. Value is list of ids of the options.
        "4": "2021-05-08", // Date type custom field. Value is in yyyy-mm-dd.
        "5": 100 // Number type custom field
    }
}

 

Sample Response

Success Response: Status code 200

{
    "id": 17,
    "name": "Lisa Taylor",
    "email": "lisa.taylors@happyfox.com",
    "phones": [
        {
            "id": 2,
            "type": "main",
            "number": "823548723"
        }
    ],
    "primary_phone": {
        "id": 2,
        "type": "main",
        "number": "823548723"
    }, 
    "custom_fields": [
        {
            "id": 8,
            "name": "Department",
            "type": "d",
            "value": 1
        }
    ],
    "created_at": "2024-01-10T13:05:05Z",
    "updated_at": "2024-01-10T13:05:05Z",
}

 

Error Response for Invalid Data

Error Response: Status code 422

{
    "non_field_errors": [
        "Email or phones is required"
    ]
}
{
    "field": "name",
    "message": "Name is required when only phones is passed in the request payload."
}

 

Sample Request for bulk create or update Requester(s)

[
    {
        "email": "lisa.taylors@happyfox.com",
        "name": "Lisa Taylor",
        "custom_fields": {
            "1": "Sample", // Text type custom field
            "2": 1, // Dropdown type custom field. Value is id of the option.
            "3": [1, 2], // Multi select type custom field. Value is list of ids of the options.
            "4": "2021-05-08", // Date type custom field. Value is in yyyy-mm-dd.
            "5": 100 // Number type custom field
        }
    },
    {
        "name": "Lisa Taylor",
        "phones": [
            {
                "type": "main",
                "number": "3414567890",
                "is_primary": true
            },
            {
                "type": "mobile",
                "number": "9234567345"
            }
        ],
        "custom_fields": {
            "1": "Sample", // Text type custom field
            "2": 1, // Dropdown type custom field. Value is id of the option.
            "3": [1, 2], // Multi select type custom field. Value is list of ids of the options.
            "4": "2021-05-08", // Date type custom field. Value is in yyyy-mm-dd.
            "5": 100 // Number type custom field
        } 
    }
]

 

Sample Response for bulk create or update Requester(s)

Success Response: Status code 200

[
    {
        "id": 31,
        "success": true,
        "name": "Lisa Taylor",
        "email": "lisa.taylors@happyfox.com"
    },
    {
        "id": 32,
        "success": true,
        "name": "Lisa Taylor",
        "primary_phone": {
            "id": 42,
            "type": "main",
            "number": "1234567876"
        }
    }
]

 

Error Response for Invalid Data

Error Response: Status code 422

[
    {
        "errors": {
            "field": "name",
            "message": "Name is required when only phones is passed in the request payload."
        },
        "success": false
    },
    {
        "errors": {
            "non_field_errors": [
                "Email or phones is required"
            ]
        },
        "success": false,
        "name": "Test 1"
    }
]