{"metadata":{"image":[],"title":"","description":""},"api":{"url":"/v2/form/:id/field.json","auth":"required","settings":"5e2b1ec0f26a2c00510363e5","try":false,"basic_auth":false,"examples":{"codes":[]},"method":"post","params":[{"name":"id","type":"int","default":"","desc":"Form ID","required":true,"in":"path","ref":"","_id":"543484820ef9c00800165142"},{"name":"field_type","type":"string","default":"","desc":"Field type","required":true,"in":"body","ref":"","_id":"543484820ef9c00800165141"},{"name":"label","type":"string","default":"","desc":"Field label. This is not required for Description Area or Embed Code fields.","required":true,"in":"body","ref":"","_id":"543484820ef9c00800165140"},{"name":"hide_label","type":"boolean","default":"0","desc":"Flag to show or hide the label","required":false,"in":"body","ref":"","_id":"543484820ef9c0080016513f"},{"name":"description","type":"string","default":"","desc":"Field description (shown below field)","required":false,"in":"body","ref":"","_id":"543484820ef9c0080016513e"},{"name":"description_callout","type":"boolean","default":"0","desc":"Flag to show the description in a callout box","required":false,"in":"body","ref":"","_id":"543484820ef9c0080016513d"},{"name":"default_value","type":"string","default":"","desc":"Initial value for the field","required":false,"in":"body","ref":"","_id":"543484820ef9c0080016513c"},{"name":"options","type":"array_mixed","default":"","desc":"Array of option labels","required":false,"in":"body","ref":"","_id":"543484820ef9c0080016513b"},{"name":"options_values","type":"array_mixed","default":"","desc":"Array of option values","required":false,"in":"body","ref":"","_id":"543487ab0ef9c00800165177"},{"name":"required","type":"boolean","default":"0","desc":"Flag to mark field as required","required":false,"in":"body","ref":"","_id":"543487ab0ef9c00800165176"},{"name":"readonly","type":"boolean","default":"0","desc":"Flag to not allow the field to be changed","required":false,"in":"body","ref":"","_id":"543487ab0ef9c00800165175"},{"name":"hidden","type":"boolean","default":"0","desc":"Flag to hide the field","required":false,"in":"body","ref":"","_id":"543487ab0ef9c00800165174"},{"name":"uniq","type":"boolean","default":"0","desc":"Flag to mark field as requiring a unique value","required":false,"in":"body","ref":"","_id":"543487ab0ef9c00800165173"},{"name":"colspan","type":"int","default":"1","desc":"Number of columns this field should span","required":false,"in":"body","ref":"","_id":"543487ab0ef9c00800165172"},{"name":"sort","type":"int","default":"Last field sort index","desc":"Sort index for the field (Starts at 0)","required":false,"in":"body","ref":"","_id":"543487ab0ef9c00800165171"},{"name":"attributes","type":"object","default":"","desc":"Field attributes. See [Field Attributes](#field-attributes) section.","required":false,"in":"body","ref":"","_id":"543487ab0ef9c00800165170"},{"name":"logic","type":"object","default":"","desc":"Field logic. See [Field Logic](#field-logic) section below.","required":false,"in":"body","ref":"","_id":"582df3d9e046d30f00d6b4b2"},{"name":"calculation","type":"string","default":"","desc":"Default value calculation. See [Field Calculation](#field-calculation) section below.","required":false,"in":"body","ref":"","_id":"582df9e436ad1c0f00d4fdcc"}],"results":{"codes":[{"status":201,"language":"json","code":"{\n  \"id\" : \"12345\",\n}","name":"Success"},{"name":"Form ID not specified","status":400,"language":"json","code":"{\n  \"status\": \"error\",\n  \"error\": \"A form id was not supplied\"\n}"},{"name":"Form not found","status":404,"language":"json","code":"{\n  \"status\": \"error\",\n  \"error\": \"A valid form id was not supplied\"\n}"},{"name":"Forbidden action","status":403,"language":"json","code":"{\n  \"status\": \"error\",\n  \"error\": \"The action was forbidden by form permissions\"\n}"},{"name":"Invalid field type argument","status":400,"language":"json","code":"{\n  \"status\": \"error\",\n  \"error\": \"A valid field type was not supplied\"\n}"},{"name":"Maximum field limit reached","status":400,"language":"json","code":"{\n  \"status\": \"error\",\n  \"error\": \"Sorry, your account only allows you a maxiumum of <max fields> fields per form. Please upgrade your account if you want to create more fields for the form, or delete one of the existing fields.\"\n}"},{"name":"Error updating field","status":500,"language":"json","code":"{\n  \"status\": \"error\",\n  \"error\": \"Could not update the field order: Error specific message\"\n}"},{"status":500,"language":"json","code":"{\n  \"status\": \"error\",\n  \"error\": \"Could not save the field: Error specific message\"\n}","name":"Error saving field"},{"name":"Error updating form","status":500,"language":"json","code":"{\n  \"status\": \"error\",\n  \"error\": \"Could not update the form: Error specific message\"\n}"}]}},"next":{"description":"","pages":[]},"title":"/form/:id/field","type":"endpoint","slug":"form-id-field-post","excerpt":"Create a new field for the specified form","body":"Create a new field for the specified form\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /api/v2/form/12345/field.json HTTP/1.1\\nHost: www.formstack.com\\nAuthorization: Bearer [[app:oauth_token]]\\nAccept: application/json\\nContent-Type: application/json\\n\\n{\\\"field_type\\\":\\\"name\\\",\\\"label\\\":\\\"Name\\\",\\\"attributes\\\":{\\\"show_prefix\\\":\\\"1\\\",\\\"show_middle\\\":\\\"1\\\"}}\",\n      \"language\": \"http\"\n    },\n    {\n      \"code\": \"curl -X POST -i -H \\\"Accept: application/json\\\" -H \\\"Content-Type: application/json\\\" -H \\\"Authorization: Bearer [[app:oauth_token]]\\\" -d '{\\\"field_type\\\":\\\"name\\\",\\\"label\\\":\\\"Name\\\",\\\"attributes\\\":{\\\"show_prefix\\\":\\\"1\\\",\\\"show_middle\\\":\\\"1\\\"}}' https://formstack.com/api/v2/form/12345/field.json\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"Field Attributes\"\n}\n[/block]\nSee [Field Types](doc:field-types) for more information about the attributes available to set in the `attributes` property.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Field Logic\"\n}\n[/block]\nSee [Field Logic](doc:field-logic) for more information about the `logic` property.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Field Calculation\"\n}\n[/block]\nSee [Field Calculations](doc:field-calculations) for more information about the `calculation` property.","updates":[],"order":17,"isReference":false,"hidden":false,"sync_unique":"","link_url":"","link_external":false,"_id":"543484820ef9c0080016513a","editedParams":true,"githubsync":"","is_link":false,"parentDoc":null,"category":{"sync":{"isSync":false,"url":""},"pages":["5435626c5ff8a51a006e4110","543553953513400800a14736","543555cc3513400800a14752","54355bcc35740020002a1b3b","5434928b0ef9c0080016520e","54347c8e5b10711400c6c30a","54346f750ef9c00800164fa0","543470f45b10711400c6c1e5","543477b70ef9c0080016505b","543478fb5b10711400c6c29f","54347d105b10711400c6c318","54347df00ef9c008001650d2","54347edf5b10711400c6c336","54357a175e1b2020004380dc","543483520ef9c0080016512a","543484820ef9c0080016513a","5434887e5b10711400c6c3cd","543488c05b10711400c6c3d2","54348ac85b10711400c6c401","5434959c0ef9c0080016522d","543497030ef9c00800165244","543498ae5b10711400c6c4f6","54349b7f0ef9c00800165293","54349c070ef9c00800165298","54349dbf0ef9c008001652ad","5434ab8e0ef9c00800165384","5434abbb0ef9c0080016538f","5434ac495b10711400c6c626","5434ada40ef9c008001653a8","5434af0a0ef9c008001653bc","5434af5f0ef9c008001653c8","5434b00a5b10711400c6c66b","5434b0d15b10711400c6c68c","5434b1ee0ef9c00800165406","5434b26d0ef9c0080016541c","5434b3560ef9c00800165427","5434b3b40ef9c0080016545a","5434b49f008ec22200d86ab9","5434b51f008ec22200d86aca","5434b5a80ef9c0080016546f","5434b5f4008ec22200d86ad8","5434b676008ec22200d86add","5434b6e6008ec22200d86ae5"],"title":"REST API","slug":"rest-api","order":1,"from_sync":false,"reference":false,"_id":"5434918d0ef9c008001651ff","version":"54346a2a0ef9c00800164f28","__v":30,"project":"543469460ef9c00800164f0e","createdAt":"2014-10-08T01:21:17.804Z"},"project":"543469460ef9c00800164f0e","version":{"version":"2.0","version_clean":"2.0.0","codename":"","is_stable":true,"is_beta":false,"is_hidden":false,"is_deprecated":false,"categories":["54346a2b0ef9c00800164f29","543473445b10711400c6c21a","543473500ef9c00800164fde","54347c625b10711400c6c301","5434918d0ef9c008001651ff","5434b72c008ec22200d86ae7","5435990c495d5d0800f3a510","5b6af3dffc81e4000383db74"],"_id":"54346a2a0ef9c00800164f28","releaseDate":"2014-10-07T22:33:14.982Z","createdAt":"2014-10-07T22:33:14.982Z","forked_from":"543469460ef9c00800164f11","project":"543469460ef9c00800164f0e","__v":8},"editedParams2":true,"user":"543469060ef9c00800164f01","__v":4,"createdAt":"2014-10-08T00:25:38.586Z"}

post/form/:id/field

Create a new field for the specified form

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

id:
required
integer
Form ID

Body Params

field_type:
required
string
Field type
label:
required
string
Field label. This is not required for Description Area or Embed Code fields.
hide_label:
boolean0
Flag to show or hide the label
description:
string
Field description (shown below field)
description_callout:
boolean0
Flag to show the description in a callout box
default_value:
string
Initial value for the field
options:
array of mixed
Array of option labels
options_values:
array of mixed
Array of option values
required:
boolean0
Flag to mark field as required
readonly:
boolean0
Flag to not allow the field to be changed
hidden:
boolean0
Flag to hide the field
uniq:
boolean0
Flag to mark field as requiring a unique value
colspan:
integer1
Number of columns this field should span
sort:
integerLast field sort index
Sort index for the field (Starts at 0)
attributes:
object
Field attributes. See [Field Attributes](#field-attributes) section.
logic:
object
Field logic. See [Field Logic](#field-logic) section below.
calculation:
string
Default value calculation. See [Field Calculation](#field-calculation) section below.

Result Format


Documentation

Create a new field for the specified form [block:code] { "codes": [ { "code": "POST /api/v2/form/12345/field.json HTTP/1.1\nHost: www.formstack.com\nAuthorization: Bearer [[app:oauth_token]]\nAccept: application/json\nContent-Type: application/json\n\n{\"field_type\":\"name\",\"label\":\"Name\",\"attributes\":{\"show_prefix\":\"1\",\"show_middle\":\"1\"}}", "language": "http" }, { "code": "curl -X POST -i -H \"Accept: application/json\" -H \"Content-Type: application/json\" -H \"Authorization: Bearer [[app:oauth_token]]\" -d '{\"field_type\":\"name\",\"label\":\"Name\",\"attributes\":{\"show_prefix\":\"1\",\"show_middle\":\"1\"}}' https://formstack.com/api/v2/form/12345/field.json", "language": "shell" } ] } [/block] [block:api-header] { "title": "Field Attributes" } [/block] See [Field Types](doc:field-types) for more information about the attributes available to set in the `attributes` property. [block:api-header] { "type": "basic", "title": "Field Logic" } [/block] See [Field Logic](doc:field-logic) for more information about the `logic` property. [block:api-header] { "type": "basic", "title": "Field Calculation" } [/block] See [Field Calculations](doc:field-calculations) for more information about the `calculation` property.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}