Custom Fields API

• Table of Contents
• Custom Field Attributes
  • Extra Attributes in Responses
  • Extra Attributes for text Fields
  • Extra Attributes for text_multiline Fields
  • Extra Attributes for number Fields
  • Extra Attributes for date and day_of_year Fields
  • Extra Attributes for select_single_dropdown, select_single_radio, and select_multiple_checkboxes Fields
  • Extra Attributes for boolean Fields
• Get Custom Field Details
  • URL
  • Request Parameters
  • Response
  • Example
• Get a Custom Field
  • URL
  • Request Parameters
  • Response
  • Example
• Create a Custom Field
  • URL
  • Request Parameters
  • Request Payload
  • Response
  • Example
• Update a Custom Field
  • URL
  • Request Parameters
  • Request Payload
  • Response
  • Example
• Delete a Custom Field
  • URL
  • Request Parameters
  • Request Payload
  • Example
  • Example of Failure
• Promote a Custom Field
  • URL
  • Request Payload
  • Response
  • Example
• List Deleted Custom Fields
  • URL
  • Response
  • Example

Custom Field Attributes

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:

Extra Attributes for text Fields

Extra Attributes for text_multiline Fields

Extra Attributes for number Fields

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

Extra Attributes for boolean Fields

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 /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 /ga/api/v2/custom_fields

Request Parameters

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

For example to search for the custom field named birthday:

GET /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 /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 /ga/api/v2/custom_fields/:id

Request Parameters

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 /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 /ga/api/v2/mailing_lists/:mailing_list_id/custom_fields

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

POST /ga/api/v2/custom_fields

Request Parameters

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 /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 /ga/api/v2/mailing_lists/:mailing_list_id/custom_fields/:id

Update a custom field that is global to the organization:

PUT /ga/api/v2/custom_fields/:id

Request Parameters

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 /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 /ga/api/v2/mailing_lists/:mailing_list_id/custom_fields/:id

Delete a custom field that is global to the organization:

DELETE /ga/api/v2/custom_fields/:id

Request Parameters

Request Payload

This request has no payload.

Example

A successful response will include a true success value:

DELETE /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 /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 /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

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 /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 /ga/api/v2/mailing_lists/:mailing_list_id/custom_fields/deleted

GET /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 /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
}