{"_id":"543498ae5b10711400c6c4f6","is_link":false,"project":"543469460ef9c00800164f0e","user":"543469060ef9c00800164f01","version":{"_id":"54346a2a0ef9c00800164f28","forked_from":"543469460ef9c00800164f11","project":"543469460ef9c00800164f0e","__v":7,"createdAt":"2014-10-07T22:33:14.982Z","releaseDate":"2014-10-07T22:33:14.982Z","categories":["54346a2b0ef9c00800164f29","543473445b10711400c6c21a","543473500ef9c00800164fde","54347c625b10711400c6c301","5434918d0ef9c008001651ff","5434b72c008ec22200d86ae7","5435990c495d5d0800f3a510"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"2.0.0","version":"2.0"},"parentDoc":null,"__v":2,"editedParams2":true,"editedParams":true,"category":{"_id":"5434918d0ef9c008001651ff","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"],"version":"54346a2a0ef9c00800164f28","__v":30,"project":"543469460ef9c00800164f0e","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-08T01:21:17.804Z","from_sync":false,"order":1,"slug":"rest-api","title":"REST API"},"updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-10-08T01:51:42.580Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"results":{"codes":[{"language":"json","code":"{\n  \"id\" : \"12345\"\n}","name":"Success","status":201},{"name":"Form ID not specified","code":"{\n  \"status\": \"error\",\n  \"error\": \"A form id was not supplied\"\n}","language":"json","status":400},{"status":404,"name":"Form not found","code":"{\n  \"status\": \"error\",\n  \"error\": \"A valid form id was not supplied\"\n}","language":"json"},{"language":"json","status":403,"name":"Forbidden action","code":"{\n  \"status\": \"error\",\n  \"error\": \"The action was forbidden by form permissions\"\n}"},{"name":"Error creating submission","code":"{\n  \"status\": \"error\",\n  \"error\": \"Could not create the submission: Error specific message\"\n}","language":"json","status":500},{"code":"{\n  \"status\": \"error\",\n  \"error\": \"An error occurred while encrypting the submission.\"\n}","language":"json","status":500,"name":"Encryption error"},{"status":400,"name":"File storage limit reached","code":"{\n  \"status\": \"error\",\n  \"error\": \"This account has reached the storage limit for file uploads\"\n}","language":"json"},{"language":"json","status":500,"name":"Error updating submission data","code":"{\n  \"status\": \"error\",\n  \"error\": \"Could not update the submission data: Error specific message\"\n}"},{"name":"Error updating account limits","code":"{\n  \"status\": \"error\",\n  \"error\": \"Could not update the account upload limits: Error specific message\"\n}","language":"json","status":500},{"status":500,"name":"Error updating submission data","code":"{\n  \"status\": \"error\",\n  \"error\": \"Could not update the form submission data: Error specific message\"\n}","language":"json"}]},"settings":"","basic_auth":false,"method":"post","try":false,"auth":"required","params":[{"_id":"543498ae5b10711400c6c4fd","ref":"","in":"path","required":true,"desc":"Form ID","default":"","type":"int","name":"id"},{"_id":"543498ae5b10711400c6c4fb","ref":"","in":"body","required":false,"desc":"Browser user agent value that should be recorded for the submission","default":"User Agent Header","type":"string","name":"user_agent"},{"_id":"543498ae5b10711400c6c4fa","ref":"","in":"body","required":false,"desc":"IP address that should be recorded for the submission","default":"Client IP","type":"string","name":"remote_addr"},{"_id":"543498ae5b10711400c6c4f9","ref":"","in":"body","required":false,"desc":"Status of a payment integration","default":"","type":"string","name":"payment_status"},{"_id":"543498ae5b10711400c6c4f8","ref":"","in":"body","required":false,"desc":"Flag to mark the submission as read","default":"0","type":"boolean","name":"read"},{"_id":"543498ae5b10711400c6c4f7","ref":"","in":"body","required":true,"desc":"Value that should be stored for a specific field on the form. See notes below","default":"","type":"string","name":"field_x"},{"_id":"56a69880ef5b2f0d00404351","ref":"","in":"body","required":false,"desc":"The password used to decrypt your submissions. Without this value, you will only receive the submission ID and the success message when submitting encrypted forms.","default":"","type":"string","name":"encryption_password"}],"url":"/v2/form/:id/submission.json"},"isReference":false,"order":27,"body":"Create a new submission for the specified form\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"POST /api/v2/form/12345/submission.json HTTP/1.1\\nHost: www.formstack.com\\nAuthorization: Bearer [[app:oauth_token]]\\nAccept: application/json\\nContent-Type: application/json\\n\\nfield_12345=Example&field_12346=Answer\",\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_12345=Example&field_12346=Answer\\\" https://www.formstack.com/api/v2/form/12345/submission.json\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"field_x\"\n}\n[/block]\nFor this parameter, x must contain the id of the field whose value should be set. For fields with subfields (name, address, etc), use array notation with each item being the subfield and each key being the name of that subfield.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"var fields = {\\n\\tfield_12345: {\\n  \\tfirst: 'John',\\n    last: 'Smith'\\n  }\\n};\\n\\nvar query = \\\"field_12345%5Bfirst%5D=John&field_12345%5Blast%5D=Smith\\\";\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"File Uploads and Signatures\"\n}\n[/block]\nFile uploads can be performed by simply base64 encoding the file data and sending that along as the value in the field_<field id> POST field.\n\nSignature are handled just like file uploads and are saved in our system as PNG files.","excerpt":"Create a new submission for the specified form","slug":"form-id-submission-post","type":"endpoint","title":"/form/:id/submission"}

post/form/:id/submission

Create a new submission for the specified form

Definition

{{ api_url }}{{ page_api_url }}

Parameters

Path Params

id:
required
integer
Form ID

Body Params

user_agent:
stringUser Agent Header
Browser user agent value that should be recorded for the submission
remote_addr:
stringClient IP
IP address that should be recorded for the submission
payment_status:
string
Status of a payment integration
read:
boolean0
Flag to mark the submission as read
field_x:
required
string
Value that should be stored for a specific field on the form. See notes below
encryption_password:
string
The password used to decrypt your submissions. Without this value, you will only receive the submission ID and the success message when submitting encrypted forms.

Result Format


Documentation

Create a new submission for the specified form [block:code] { "codes": [ { "code": "POST /api/v2/form/12345/submission.json HTTP/1.1\nHost: www.formstack.com\nAuthorization: Bearer [[app:oauth_token]]\nAccept: application/json\nContent-Type: application/json\n\nfield_12345=Example&field_12346=Answer", "language": "http" }, { "code": "curl -X POST -i -H \"Accept: application/json\" -H \"Content-Type: application/json\" -H \"Authorization: Bearer [[app:oauth_token]]\" -d \"field_12345=Example&field_12346=Answer\" https://www.formstack.com/api/v2/form/12345/submission.json", "language": "shell" } ] } [/block] [block:api-header] { "type": "basic", "title": "field_x" } [/block] For this parameter, x must contain the id of the field whose value should be set. For fields with subfields (name, address, etc), use array notation with each item being the subfield and each key being the name of that subfield. [block:code] { "codes": [ { "code": "var fields = {\n\tfield_12345: {\n \tfirst: 'John',\n last: 'Smith'\n }\n};\n\nvar query = \"field_12345%5Bfirst%5D=John&field_12345%5Blast%5D=Smith\";", "language": "javascript" } ] } [/block] [block:api-header] { "type": "basic", "title": "File Uploads and Signatures" } [/block] File uploads can be performed by simply base64 encoding the file data and sending that along as the value in the field_<field id> POST field. Signature are handled just like file uploads and are saved in our system as PNG files.

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