Custom Field
A custom field is an attribute (key-value pair) that may be attached to almost any resource.
This section provides APIs to list all custom fields, search for a specific custom field, and retrieve custom field audit logs. Searching may be based on the custom field id or on its name, value, or resource type. In addition, each resource provides APIs for the applicable CRUD operations: creation, retrieval, updating, and deletion.
Custom Field Resource
The Custom Field
resource is associated with a key-value pair and has the following attributes:
Name | Type | Generated by | Description |
---|---|---|---|
customFieldId | string | system | UUID for this custom field |
objectType | string | user | Type of the object this tag is attached to (e.g. "ACCOUNT") |
objectID | string | system | UUID for the object |
name | string | user | name of the custom field |
value | string | user | value of the custom field |
auditLogs | array | system | array of audit log records for this custom field |
List all custom fields
Retrieves a list of all custom fields (name and value) with their associated resources and optional audit logs
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/customFields/pagination
Query Parameters
Name | Type | Required | Default | Description |
---|---|---|---|---|
offset | integer | false | 0 | starting item in the list |
limit | integer | false | 100 | number of items to return |
audit | string | false | "NONE" | "NONE", "MINIMAL", or "FULL" |
Returns
Returns a list of records for all custom fields
Example Request:
curl \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/customFields/pagination"
Example Response:
[
{
"customFieldId": "13fe6f2c-91af-4635-aa9c-52e04d99b5ec",
"objectType": "ACCOUNT",
"objectId": "212211f8-a264-4ddf-b609-709ae652aec4",
"name": "importance",
"value": "high",
"auditLogs": []
}
]
Search custom fields by ID
Searches for a specific custom field by its ID
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/customField/search/{customFieldId}
Query Parameters
Name | Type | Required | Default | Description |
---|---|---|---|---|
offset | integer | false | 0 | starting item in the list |
limit | integer | false | 100 | number of items to return |
audit | string | false | "NONE" | "NONE", "MINIMAL", or "FULL" |
Returns
Returns the record for the specified custom field, if it exists
Example Request:
curl \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/customFields/search/13fe6f2c-91af-4635-aa9c-52e04d99b5ec"
Example Response:
[
{
"customFieldId": "13fe6f2c-91af-4635-aa9c-52e04d99b5ec",
"objectType": "ACCOUNT",
"objectId": "212211f8-a264-4ddf-b609-709ae652aec4",
"name": "importance",
"value": "high",
"auditLogs": []
}
]
Search custom fields by resource type, name, and optional value
Searches for a specific custom field by its resource type, name, and optional value
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/customField/search
Query Parameters
Name | Type | Required | Default | Description |
---|---|---|---|---|
objectType | string | true | none | type of resource to search (e.g., "ACCOUNT") |
fieldName | string | true | none | name of the custom field to search for |
fieldValue | string | false | any value | value of the custom field to search for |
offset | integer | false | 0 | starting item in the list |
limit | integer | false | 100 | number of items to return |
audit | string | false | "NONE" | "NONE", "MINIMAL", or "FULL" |
Returns
Returns the record for the specified custom field, if it exists
Example Request:
curl \
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://127.0.0.1:8080/1.0/kb/customFields/search?objectType=ACCOUNT&fieldName=importance"
Example Response:
[
{
"customFieldId": "13fe6f2c-91af-4635-aa9c-52e04d99b5ec",
"objectType": "ACCOUNT",
"objectId": "212211f8-a264-4ddf-b609-709ae652aec4",
"name": "importance",
"value": "high",
"auditLogs": []
}
]
Audit Logs
Retrieve custom field audit logs with history by custom field id
HTTP Request
GET http://127.0.0.1:8080/1.0/kb/customFields/{customFieldId}/auditLogsWithHistory
Example Request:
-u admin:password \
-H "X-Killbill-ApiKey: bob" \
-H "X-Killbill-ApiSecret: lazar" \
-H "Accept: application/json" \
"http://localhost:8080/1.0/kb/customFields/4b498210-b177-4aae-a539-cf594adaa221/auditLogsWithHistory"
Example Response:
[
{
"changeType": "INSERT",
"changeDate": "2013-08-01T06:00:00.000Z",
"objectType": "CUSTOM_FIELD",
"objectId": "4b498210-b177-4aae-a539-cf594adaa221",
"changedBy": "test_custom_fields",
"reasonCode": null,
"comments": null,
"userToken": "2b3920ae-6b8c-4deb-9ed9-132ff632e692",
"history": {
"id": null,
"createdDate": "2013-08-01T06:00:00.000Z",
"updatedDate": "2013-08-01T06:00:00.000Z",
"recordId": 1,
"accountRecordId": 17,
"tenantRecordId": 12,
"fieldName": "Test Custom Field",
"fieldValue": "test_value",
"objectId": "01968143-c64b-41d4-94cb-d65748b0f5b6",
"objectType": "ACCOUNT",
"isActive": true,
"tableName": "CUSTOM_FIELD",
"historyTableName": "CUSTOM_FIELD_HISTORY"
}
},
{
"changeType": "UPDATE",
"changeDate": "2013-08-01T06:00:01.000Z",
"objectType": "CUSTOM_FIELD",
"objectId": "4b498210-b177-4aae-a539-cf594adaa221",
"changedBy": "test_custom_fields",
"reasonCode": null,
"comments": null,
"userToken": "6343d19f-cef0-486a-8114-85c7573639a0",
"history": {
"id": null,
"createdDate": "2013-08-01T06:00:01.000Z",
"updatedDate": "2013-08-01T06:00:01.000Z",
"recordId": 1,
"accountRecordId": 17,
"tenantRecordId": 12,
"fieldName": "Test Custom Field",
"fieldValue": "another_test_value",
"objectId": "01968143-c64b-41d4-94cb-d65748b0f5b6",
"objectType": "ACCOUNT",
"isActive": true,
"tableName": "CUSTOM_FIELD",
"historyTableName": "CUSTOM_FIELD_HISTORY"
}
},
{
"changeType": "DELETE",
"changeDate": "2013-08-01T06:00:01.000Z",
"objectType": "CUSTOM_FIELD",
"objectId": "4b498210-b177-4aae-a539-cf594adaa221",
"changedBy": "test_custom_fields",
"reasonCode": null,
"comments": null,
"userToken": "9a9343bd-9cba-417b-be17-713ff456b5f7",
"history": {
"id": null,
"createdDate": "2013-08-01T06:00:01.000Z",
"updatedDate": "2013-08-01T06:00:01.000Z",
"recordId": 1,
"accountRecordId": 17,
"tenantRecordId": 12,
"fieldName": "Test Custom Field",
"fieldValue": "another_test_value",
"objectId": "01968143-c64b-41d4-94cb-d65748b0f5b6",
"objectType": "ACCOUNT",
"isActive": true,
"tableName": "CUSTOM_FIELD",
"historyTableName": "CUSTOM_FIELD_HISTORY"
}
}
]
Query Parameters
None.
Returns
Returns a list of custom field logs with history.