Emma API Documentation

Fields

These endpoints let you create, edit, update and delete all of the custom fields in your account. Of particular interest is the /#account_id/fields/#field_id/clear endpoint which lets you clear out all the data in a single field for all members in your account. This makes it easy to re-initialize a dataset if you’re looking to correct an import error or syncing issue.

GET /#account_id/fields

Gets a list of this account’s defined fields.

Parameters:
  • deleted (boolean) – Accepts True or 1. Optional flag to include deleted fields.
Returns :

An array of fields.

Sample Response [showhide]
GET /100/fields

[
  {
    "shortcut_name": "first_name",
    "display_name": "First Name",
    "account_id": 100,
    "field_type": "text",
    "required": false,
    "field_id": 200,
    "widget_type": "text",
    "short_display_name": null,
    "column_order": 1,
    "deleted_at": null,
    "options": null
  },
  {
    "shortcut_name": "last_name",
    "display_name": "Last Name",
    "account_id": 100,
    "field_type": "text",
    "required": false,
    "field_id": 201,
    "widget_type": "text",
    "short_display_name": null,
    "column_order": 2,
    "deleted_at": null,
    "options": null
  },
  {
    "shortcut_name": "favorite_food",
    "display_name": "Favorite Food",
    "account_id": 100,
    "field_type": "text",
    "required": false,
    "field_id": 202,
    "widget_type": "text",
    "short_display_name": null,
    "column_order": 3,
    "deleted_at": null,
    "options": null
  },
  {
    "shortcut_name": "birthday",
    "display_name": "Birthday",
    "account_id": 100,
    "field_type": "date",
    "required": false,
    "field_id": 203,
    "widget_type": "date",
    "short_display_name": null,
    "column_order": 4,
    "deleted_at": null,
    "options": null
  }
]

GET /#account_id/fields/#field_id

Gets the detailed information about a particular field.

Parameters:
  • deleted (boolean) – Accepts True or 1. Optionally show a field even if it has been deleted.
Returns :

A field.

Raises :

Http404 if the field does not exist.

Sample Response [showhide]
GET /100/fields/200

{
  "shortcut_name": "first_name",
  "display_name": "First Name",
  "account_id": 100,
  "field_type": "text",
  "required": false,
  "field_id": 200,
  "widget_type": "text",
  "short_display_name": null,
  "column_order": 1,
  "deleted_at": null,
  "options": null
}

POST /#account_id/fields

Create a new field field.

There must not already be a field with this name.

Parameters:
  • shortcut_name (string) – The internal name for this field.
  • display_name (string) – Display name, used for forms and reports.
  • field_type (string) – The type of value this field will contain. Accepts one of text, text[], numeric, boolean, date, timestamp.
  • widget_type (string) – The widget used to accept field input. Valid values are based on field_type.
    text => text, long, radio, select one.
    text[] => select multiple, check_multiple.
    numeric => number.
    boolean => checkbox.
    date and timestamp => date.
  • options (array) – Options for a check_multiple, select multiple, select one, or radio widget.
  • column_order (integer) – Order of this column in lists.
Returns :

A reference to the new field.

Sample Response [showhide]
POST /100/fields
{
  "shortcut_name": "new_dropdown",
  "column_order": 3,
  "display_name": "A New Select Box Field",
  "field_type": "text",
  "widget_type": "select one",
  "options": ["first", "second", "third"]
}

1024

DELETE /#account_id/fields/#field_id

Deletes a field.

Returns :True if the field is deleted.
Raises :Http404 if the field does not exist.

Sample Response [showhide]
DELETE /100/fields/200

true

POST /#account_id/fields/#field_id/clear

Clear the member data for the specified field.

Returns :True if all of the member field data is deleted

Sample Response [showhide]
POST /100/fields/200/clear
{}

true

PUT /#account_id/fields/#field_id

Updates an existing field.

Returns :A reference to the updated field.

Sample Response [showhide]
PUT /100/fields/202
{
  "display_name": "Your Birthday"
}

202

Related Topics

Interested in Emma?

Emma's email marketing makes communicating simple and stylish. Get started today.