Custom Fields API
Create a custom field
Update a custom field
Get custom fields details by field ID
Get custom field details by entity type
Get custom field details by entity type and project
Delete a custom field
Enable or disable a custom field for a project
Create a custom field
This API creates a Zephyr custom field.
Request
POST https://<client server base URL>/rest/zapi/latest/customfield/create
Content-Type: application/json
Authentication type: Basic
Request Body
{
"name": "first CF",
"description": "My custom field",
"defaultValue": "",
"isActive": true,
"fieldType": "TEXT",
"aliasName": "",
"projectId": "",
"displayName": "",
"displayFieldType": "Text Field (single line)",
"entityType": "EXECUTION"
}name: the name of the custom field.
description: the description of the custom field.
defaultValue: the default value of the custom field.
isActive: indicates whether the custom field is active (at the project level).
fieldType: the type of the custom field.
aliasName: the short name of the custom field.
projectId: the project ID.
displayName: the displayed name of the custom field.
displayFieldType: the type of the displayed field.
entityType: the entity type. Either EXECUTION or TESTSTEP.
Allowed field types:
TEXT, LARGE_TEXT, NUMBER, RADIO_BUTTON, SINGLE_SELECT, MULTI_SELECT, DATE, DATE_TIME
Response
Response Body
{
"name": "",
"description": "",
"defaultValue": null,
"isActive": false,
"fieldType": "",
"aliasName": "",
"projectId": null,
"displayName": null,
"createdOn": "",
"createdBy": "",
"entityType": "",
"fieldOptions": null,
"displayFieldType": null,
"id": "",
"responseMessage": "",
"customFieldOptionValues": null,
"modifiedBy": "",
"active": false
}id: the ID of the field that has just been created.
name: the name of the custom field.
description: the description of the custom field.
defaultValue: the default value of the custom field.
isActive: indicates whether the custom field is active (at the project level).
fieldType: the type of the custom field.
aliasName: the short name of the custom field.
projectId: the project ID.
displayName: the displayed name of the custom field.
displayFieldType: the type of the displayed field.
entityType: the entity type. Either EXECUTION or TESTSTEP.
createdOn: the date the custom field was created.
createdBy: the user who created the custom field.
fieldOptions: the options of the custom field.
responseMessage: the response message of the created custom field.
customFieldOptionValues: the option values of the custom field.
modifiedBy: the user who modified the custom field.
active:the status of the custom field.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request or it is not configured properly. See the error message in the response body.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
Update a custom field
This API updates an existing custom field.
Request
PUT https://<client server base URL>/rest/zapi/latest/customfield/{customfieldId}Content-Type: application/json
Authentication type: Basic
Parameters:
customfieldId: the ID of the custom field to be updated.
POST Body
{ "key1": "value1",
"key2": "value2",
...
"keyN": "valueN"
}The fields the user can change:
Name: the name of the custom field to be updated.
Description: the description of the custom field to be updated.
Response
Response Body
{
"name": "",
"description": "",
"defaultValue": null,
"isActive": false,
"fieldType": "",
"aliasName": "",
"projectId": null,
"displayName": null,
"createdOn": "",
"createdBy": "",
"entityType": "",
"fieldOptions": null,
"displayFieldType": null,
"id": "",
"responseMessage": "",
"customFieldOptionValues": null,
"modifiedBy": "",
"modifiedDate": "",
"active": false
}id: the ID of the custom field.
name: the name of the custom field.
description: the description of the custom field.
defaultValue: the default value of the custom field.
isActive: indicates whether the custom field is active (at the project level).
fieldType: the type of the custom field.
aliasName: the short name of the custom field.
projectId: the project ID.
displayName: the displayed name of the custom field.
displayFieldType: the type of the displayed text field.
entityType: the entity type. Either EXECUTION or TESTSTEP.
createdOn: the date the custom field was created.
createdBy: the user who created the custom field.
fieldOptions: the options of the custom field.
responseMessage: the response massage of the created custom field.
customFieldOptionValues: the option values of the custom field.
modifiedBy: the user who modified the custom field.
modifedDate: the date the custom field was modified.
active: the status of the custom field.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request or it is not configured properly. See the error message in the response body.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
Get custom fields details by field ID
This API retrieves information about a Zephyr custom field by its ID.
Request
GET https://<client server base URL>/rest/zapi/latest/customfield/{id}
Authentication type:Basic
Parameters:
id: the ID of the custom field, information about which will be retrieved.
Response
Response Body
{
"name": "",
"description": "",
"defaultValue": null,
"isActive": false,
"fieldType": "",
"aliasName": "",
"projectId": null,
"displayName": null,
"createdOn": "",
"createdBy": "",
"entityType": "",
"fieldOptions": null,
"displayFieldType": null,
"id": "",
"customFieldOptionValues": null,
"active": false
}id: the ID of the custom field.
name: the name of the custom field.
description: the description of the custom field.
defaultValue: the default value of the custom field.
isActive: indicates whether the custom field is active (at the project level).
fieldType: the type of the custom field.
aliasName: the short name of the custom field.
projectId: the project ID.
displayName: the displayed name of the custom field.
displayFieldType: the type of the displayed field.
entityType: the entity type. Either EXECUTION or TESTSTEP.
createdOn: the date the custom field was created.
createdBy: the user who created the custom field.
fieldOptions: the options of the custom field.
customFieldOptionValues: the option values of the custom field.
active: the status of the custom field.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request. No custom field with the specified ID was found.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
Get custom field details by entity type
This API retrieves all custom fields of the specified entity type.
Request
GET https://<client server base URL>/rest/zapi/latest/customfield/entity?entityType=
Authentication type: Basic
Note: Query parameters are mandatory.
Query Parameters:
entityType: the entity type of the custom field. Possible values: EXECUTION, TESTSTEP.
Response
Response Body
[
{
Zephyr custom field information in the JSON format
},
{
Zephyr custom field information in the JSON format
},
...
{
Zephyr custom field information in the JSON format
}
]Zephyr custom field information
{
"name": "",
"description": "",
"defaultValue": null,
"isActive": false,
"fieldType": "",
"aliasName": "",
"projectId": null,
"displayName": null,
"createdOn": "",
"createdBy": "",
"entityType": "",
"fieldOptions": null,
"displayFieldType": null,
"id": "",
"customFieldOptionValues": null,
"active": false
}id: the ID of the custom field.
name: the name of the custom field.
description: the description of the custom field.
defaultValue: the default value of the custom field.
isActive: indicates whether the custom field is active (at the project level).
fieldType: the type of the custom field.
aliasName: the short name of the custom field.
projectId: the project ID.
displayName: the displayed name of the custom field.
displayFieldType: the type of the displayed field.
entityType: the entity type. Either EXECUTION or TESTSTEP.
createdOn: the date the custom field was created.
createdBy: the user who created the custom field.
fieldOptions: the options of the custom field.
customFieldOptionValues: the option values of the custom field.
active: the status of the custom field.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request. No entity type with the specified ID was found.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
Get custom field details by entity type and project
This API retrieves all custom fields that have a specific entity type and that are used in a specific project.
Request
GET https://<client server base URL>/rest/zapi/latest/customfield/byEntityTypeAndProject?entityType=&projectId=
Authentication type: Basic
Note:Both query parameters are mandatory.
Query Parameters:
entityType: the entity type of the custom field. Possible values: EXECUTION, TESTSTEP.projectId: The project ID.
Response
Response Body
[
{
Zephyr custom field information in the JSON format
},
{
Zephyr custom field information in the JSON format
},
...
{
Zephyr custom field information in the JSON format
}
]Zephyr custom field information
{
"name": "",
"description": "",
"defaultValue": null,
"isActive": false,
"fieldType": "",
"aliasName": "",
"projectId": null,
"displayName": null,
"createdOn": "",
"createdBy": "",
"entityType": "",
"fieldOptions": null,
"displayFieldType": null,
"id": "",
"customFieldOptionValues": null,
"active": false
}id: the ID of the custom field.
name: the name of the custom field.
description: the description of the custom field.
defaultValue: the default value of the custom field.
isActive: indicates whether the custom field is active (at the project level).
fieldType: the type of the custom field.
aliasName: the short name of the custom field.
projectId: the project ID.
displayName: the displayed name of the custom field.
displayFieldType: the type of the displayed text field.
entityType: the entity type. Either EXECUTION or TESTSTEP.
createdOn: the date the custom field was created.
createdBy: the user who created the custom field.
fieldOptions: the options of the custom field.
customFieldOptionValues: the option values of the custom field.
active: the status of the custom field.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request. No entity type with the specified ID was found.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
Delete a custom field
This API deletes a custom field by its ID.
Request
DELETE https://<client server base URL>/rest/zapi/latest/customfield/{customfieldId}
Authentication type: Basic
Parameters:
customfieldId: the ID of the custom field to be deleted.
Response
Response Body
{
"message": ""
}message: the message to be sent if the field cannot be deleted or if it has been deleted successfully.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request. No custom field with the specified ID was found.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
Delete several custom fields
This API deletes several custom fields by their IDs.
Request
DELETE https://<client server base URL>/rest/zapi/latest/customfield/delete-customfields
Authentication type: Basic
Parameters:
customfieldIds: the IDs of the custom fields to be deleted.
Sample payload:
{
"customfields":["3","14"]
}3 and 14 - the IDs of the fields to be deleted.
Response
Response Body
{
"message": ""
}message: the message to be sent if the field cannot be deleted or if it has been deleted successfully.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request. No custom field with the specified ID was found.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.
Enable or disable a custom field for a project
This API enables or disables a custom field for a project.
Request
DELETE https://<client server base URL>/rest/zapi/latest/customfield/{customFieldId}/{projectId}?enable
Authentication type: Basic
Path parameters:
customFieldId: the ID of the custom field.
projectId: the project ID.
Note:The query parameter enable is mandatory.
Query parameters:
enable: false or true. If false, the custom field will be disabled for the project. Else, the custom field will be enabled.
Response
Response Body
{
"message": ""
}message: the details based on the input value.
Response Codes
200: The request has been accepted and processed successfully.
400: Bad request. Either the custom field or the project with the specified ID was not found.
401: Unauthorized. Make sure you have specified the correct username and password.
403: Forbidden. Make sure you have the required permissions to perform this action.
404: Not found. The API URL was not found or it was not configured properly.
500: Make sure the server is up and running and Zephyr is configured properly before using the API.