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.