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.