Custom Fields API

Custom Field Attributes

mailing_list_id

integer

The mailing list this custom field is tied to, or null if this custom field is global.
name

string

The name of this custom field.
field_type

string

The type of this custom field. See the “Custom Field Types” table for valid values.
required

boolean

This custom field is required to be filled out for all subscribers.

Checkboxes - This attribute has no effect on select_multiple_checkboxes fields. If a value for required is provided, it will be saved to the database; it will not, however, actually cause the custom field to be required on subscribers.
instructions

string

Instructions on how this field should be used.

The response will have extra attributes in it that are used based upon the field type. See the tables below for details on these fields.

Extra Attributes in Responses

The following keys are included when the custom field is sent back in a JSON response. These keys are not valid input values:

id

integer

The id of this custom field.
is_global

boolean

Whether this custom field is global to the organization

Extra Attributes for text Fields

default_string

string

The default value for this custom field
minimum_length

integer

The minimum length for this string (Note that if the field is not “Required”, then it can be blank regardless of this value)
maximum_length

integer

The maximum length for this string
interpolation_html_encode

boolean

This value will be encoded when inserted into HTML content (default: true).
interpolation_url_encode

boolean

This value will be encoded when inserted into URLs upon click redirection (default: true).

Extra Attributes for text_multiline Fields

default_string

string

The default value for this custom field
minimum_length

integer

The minimum length for this string (Note that if the field is not “Required”, then it can be blank regardless of this value)
maximum_length

integer

The maximum length for this string
number_of_rows

integer

The number of rows that should be displayed when rendering this input field
interpolation_html_encode

boolean

This value will be encoded when inserted into HTML content (default: true).
interpolation_html_newlines

boolean

This value will have its newlines replaced with <BR/> tags when inserted into HTML content (default: true).
interpolation_url_encode

boolean

This value will be encoded when inserted into URLs upon click redirection (default: true).

Extra Attributes for number Fields

default_integer

integer

The default value for this custom field
minimum_value

integer

The minimum value for this custom field (Note that if the field is not “Required”, then it can be blank regardless of this value)
maximum_value

integer

The maximum value for this custom field

Extra Attributes for date and day_of_year Fields

There are no extra attributes for these fields.

Extra Attributes for select_single_dropdown, select_single_radio, and select_multiple_checkboxes Fields

options

array of hashes

An options array composed of the elements described below

name

string

The name of this option. This is the value presented in dropdowns, radios, and checkboxes.
id

integer

The id of this option.
index

integer

The position in the list of options.

Extra Attributes for boolean Fields

default_boolean

boolean

This boolean custom field should / should not be selected by default

Get Custom Field Details

URL

To get the custom fields that apply to a mailing list (this includes both custom fields that are attached to this mailing list and global custom fields):

GET https://app.kasplo.com/ga/api/v2/mailing_lists/:mailing_list_id/custom_fields

To get the custom fields that are global to the API key’s organization:

GET https://app.kasplo.com/ga/api/v2/custom_fields

Request Parameters

The following parameters may be included as part of the query string:

name

string

Get a list of custom fields with this exact, case-insensitive name.
name_contains

string

Get a list of all custom fields whose name contains this case-insensitive string.
order_by

string

Specify a custom field attribute to sort the results by. Can be name or id.

Defaults to id.

For example to search for the custom field named birthday:

GET https://app.kasplo.com/ga/api/v2/custom_fields?name=birthday

Response

The response will be an array of custom field objects, as defined in the Attributes section above.

This endpoint returns paginated records with a default page size of 2000.

Example

GET https://app.kasplo.com/ga/api/v2/custom_fields
                            

HTTP/1.1 200 OK
                            

{
                              "success": true,
                              "data": [
                                {
                                  "is_global": true,
                                  "id": 153,
                                  "name": "City",
                                  "mailing_list_id": null,
                                  "field_type": "text",
                                  "required": false,
                                  "instructions": null,
                                  "default_string": null,
                                  "minimum_length": null,
                                  "maximum_length": null,
                                  "interpolation_html_encode": true,
                                  "interpolation_url_encode": true
                                }
                              ],
                              "error_code": null,
                              "error_message": null,
                              "page": 0,
                              "per_page": 2000,
                              "num_records": 1,
                              "num_pages": 1
                            }

Get a Custom Field

Get all the basic details of a single custom field.

URL

GET https://app.kasplo.com/ga/api/v2/custom_fields/:id

Request Parameters

id

integer

The id of the custom field to get

Response

A successful response will return the custom field record, including any applicable “Extra Parameters” as listed above.

Example

Note that the JSON response will not be “pretty formatted” as it is below.

GET https://app.kasplo.com/ga/api/v2/custom_fields/161
                            

HTTP/1.1 200 OK
                            

{
                              "success": true,
                              "data": {
                                "is_global": true,
                                "id": 161,
                                "name": "City",
                                "mailing_list_id": null,
                                "field_type": "text",
                                "required": false,
                                "instructions": null,
                                "default_string": null,
                                "minimum_length": null,
                                "maximum_length": null,
                                "interpolation_html_encode": true,
                                "interpolation_url_encode": true
                              },
                              "error_code": null,
                              "error_message": null
                            }

Create a Custom Field

URL

To create a new custom field on a mailing list:

POST https://app.kasplo.com/ga/api/v2/mailing_lists/:mailing_list_id/custom_fields

To create a new custom field that is global to the organization:

POST https://app.kasplo.com/ga/api/v2/custom_fields

Request Parameters

mailing_list_id

integer

The id of the mailing list for this custom field

Request Payload

See the Attributes section above for an explanation of the custom field fields. The JSON object should be a child of the custom_field key.

Response

A successful response will return the custom field record as described above, in addition to the “Extra Parameters” listed above.

A failure will return a standard error response with an explanation of what went wrong.

Example

POST https://app.kasplo.com/ga/api/v2/custom_fields
                            

{
                              "custom_field": {
                                "name": "My Custom Field",
                                "field_type": "text",
                                "required": false
                              }
                            }
                            

HTTP/1.1 200 OK
                            

{
                              "success": true,
                              "data": {
                                "is_global": true,
                                "id": 170,
                                "name": "My Custom Field",
                                "mailing_list_id": null,
                                "field_type": "text",
                                "required": false,
                                "instructions": null,
                                "default_string": null,
                                "minimum_length": null,
                                "maximum_length": null,
                                "interpolation_html_encode": true,
                                "interpolation_url_encode": true
                              },
                              "error_code": null,
                              "error_message": null
                            }

Update a Custom Field

URL

Update a custom field that is associated with a single mailing list:

PUT https://app.kasplo.com/ga/api/v2/mailing_lists/:mailing_list_id/custom_fields/:id

Update a custom field that is global to the organization:

PUT https://app.kasplo.com/ga/api/v2/custom_fields/:id

Request Parameters

id

integer

The id of the custom field
mailing_list_id

integer

The id of the mailing list for this custom field

Request Payload

The PUT request should have a JSON document in its payload in the same format as when creating a new custom field. Some or all of the parameters may be omitted when updating an existing record.

Response

A successful response will return the custom field record described in the “Create a new custom field” section above.

A failure will return a standard error response with an explanation of what went wrong.

Example

PUT https://app.kasplo.com/ga/api/v2/custom_fields/178
                            

{
                              "custom_field": {
                                "name": "Updated Name"
                              }
                            }
                            

HTTP/1.1 200 OK
                            

{
                              "success": true,
                              "data": {
                                "is_global": true,
                                "id": 178,
                                "name": "Updated Name",
                                "mailing_list_id": null,
                                "field_type": "text",
                                "required": false,
                                "instructions": null,
                                "default_string": null,
                                "minimum_length": null,
                                "maximum_length": null,
                                "interpolation_html_encode": true,
                                "interpolation_url_encode": true
                              },
                              "error_code": null,
                              "error_message": null
                            }

Delete a Custom Field

URL

Delete a custom field that is associated with a single mailing list:

DELETE https://app.kasplo.com/ga/api/v2/mailing_lists/:mailing_list_id/custom_fields/:id

Delete a custom field that is global to the organization:

DELETE https://app.kasplo.com/ga/api/v2/custom_fields/:id

Request Parameters

id

integer

The id of the custom field
mailing_list_id

integer

The id of the mailing list for this custom field

Request Payload

This request has no payload.

Example

A successful response will include a true success value:

DELETE https://app.kasplo.com/ga/api/v2/custom_fields/186
                            

HTTP/1.1 200 OK
                            

{
                              "success": true,
                              "data": null,
                              "error_code": null,
                              "error_message": null
                            }

Example of Failure

A failure response will include a false success value and a standard error response with an explanation of what went wrong.

If the failure is due to other objects depending on this custom field to exist, the response data will contain a dependencies key:

DELETE https://app.kasplo.com/ga/api/v2/custom_fields/202
                            

HTTP/1.1 200 OK
                            

{
                              "success": false,
                              "data": {
                                "dependencies": [
                                  {
                                    "type": "segmentation_criteria",
                                    "id": 1
                                  }
                                ]
                              },
                              "error_code": "validation_failed",
                              "error_message": "Cannot delete custom field because it is currently being used by the following records."
                            }

Promote a Custom Field

URL

Promote a custom field to be a global custom field:

POST https://app.kasplo.com/ga/api/v2/custom_fields/promote

Custom fields that are associated with a single mailing list may be promoted to be global to the organization. Custom fields must have a unique name across the organization in order to be promoted to be a global custom field.

Request Payload

promote

hash
custom_field_id

integer

id of the custom field to promote

Response

A successful response will return the same output as Create a new custom field.

A failure will return a standard error response with an explanation of what went wrong.

Example

POST https://app.kasplo.com/ga/api/v2/custom_fields/promote
                            

{
                              "promote": {
                                "custom_field_id": 187
                              }
                            }
                            

HTTP/1.1 200 OK
                            

{
                              "success": true,
                              "data": {
                                "default_boolean": false,
                                "field_type": "boolean",
                                "id": 187,
                                "instructions": null,
                                "mailing_list_id": null,
                                "name": "Has Children",
                                "required": false,
                                "is_global": true
                              },
                              "error_code": null,
                              "error_message": null
                            }

List Deleted Custom Fields

When a custom field is deleted, it is not actually removed from the database. Instead, it is marked as deleted and is no longer used.

This endpoint will return the list of deleted custom fields that were associated with the specified mailing list or organization.

URL

GET https://app.kasplo.com/ga/api/v2/mailing_lists/:mailing_list_id/custom_fields/deleted
                            
                            GET https://app.kasplo.com/ga/api/v2/custom_fields/deleted

Response

The response will contain the same fields as listed in the Attributes section above – but with one additional field ( deleted_at). This value will be the time at which the custom field was deleted.

Example

GET https://app.kasplo.com/ga/api/v2/mailing_lists/50/custom_fields/deleted
                            

HTTP/1.1 200 OK
                            

{
                              "success": true,
                              "data": [
                                {
                                  "default_string": null,
                                  "deleted_at": "2017-04-21T16:48:40Z",
                                  "field_type": "text",
                                  "id": 211,
                                  "instructions": null,
                                  "interpolation_html_encode": true,
                                  "interpolation_url_encode": true,
                                  "mailing_list_id": 50,
                                  "maximum_length": null,
                                  "minimum_length": null,
                                  "name": "Preferred Name",
                                  "required": false,
                                  "is_global": false
                                }
                              ],
                              "error_code": null,
                              "error_message": null
                            }