{"_id":"5435626c5ff8a51a006e4110","parentDoc":null,"user":"543469060ef9c00800164f01","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"},"project":"543469460ef9c00800164f0e","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"},"is_link":false,"__v":10,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2014-10-08T16:12:28.197Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"try":true,"basic_auth":false,"results":{"codes":[]},"auth":"never","params":[],"url":""},"isReference":false,"order":0,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API Methods\"\n}\n[/block]\nA list of all api methods (exposed as REST resources) can be found here:\n[Formstack API REST Resources](doc:resources)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Request Formats\"\n}\n[/block]\nThe Formstack API accepts two request data types: HTTP url encoded query parameters and JSON. By default, we expect HTTP url encoded query parameters. To use JSON, simply change the **Content-Type** header in your request to be **\"Content-Type: application/json\"** and put the JSON in the body of the request.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response Formats\"\n}\n[/block]\nThe Formstack API offers two response types: JSON (default) and XML. To indicate which response type you would like to receive, simply add .xml or .json to the end of any resource URIs. If an extension is not present, we will respond with JSON.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://www.formstack.com/api/v2/form.json\\nhttps://www.formstack.com/api/v2/form/12334/submission.xml\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Obtaining an API key (OAuth2 Access Token)\"\n}\n[/block]\nAll of our API calls require authentication. The REST API uses OAuth2 access tokens for this purpose. [Creating an application](https://www.formstack.com/admin/apiKey/main) record will also create an access token. Access tokens are tied to a Formstack user and follow Formstack (in-app) user permissions. Additional access tokens can be generated by the OAuth2 [authorization](doc:authorization) process.\n\nTo request an OAuth2 token to use with the Formstack API explorer, visit [here](https://www.formstack.com/readme_auth.php).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Authentication\"\n}\n[/block]\nOnce you have an access token, you can make authenticated api calls. To do this, include the access token in the HTTP Authorization header:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Authorization: Bearer <access-token>\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\nOn any GET api calls, you can set the access token as a part of the query string:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"https://www.formstack.com/api/v2/form.json?oauth_token=abcdefg123456\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Rate Limits\"\n}\n[/block]\nTo prevent abuse, the Formstack API is rate limited to **14,400** calls per access token per day.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Status Codes\"\n}\n[/block]\nThe Formstack API uses standard HTTP status codes.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Code\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"200\",\n    \"0-1\": \"OK - The request was handled without any errors\",\n    \"1-0\": \"201\",\n    \"1-1\": \"Created - A new resource was created\",\n    \"2-0\": \"400\",\n    \"2-1\": \"Bad Request - The request URI was invalid\",\n    \"3-0\": \"401\",\n    \"3-1\": \"Unauthorized - Valid OAuth2 credentials were not supplied\",\n    \"4-0\": \"403\",\n    \"4-1\": \"Forbidden - The current user does not have access to this method\",\n    \"5-0\": \"404\",\n    \"5-1\": \"Not Found - The resource requested could not be found\",\n    \"6-0\": \"405\",\n    \"6-1\": \"Method Not Allowed - The requested method does not exist\",\n    \"7-0\": \"415\",\n    \"7-1\": \"Unsupported Media Type - A valid media type (JSON, XML, HTTP URL encoded) was not used\",\n    \"9-0\": \"500\",\n    \"9-1\": \"Internal Server Error - An error occurred while processing the request\",\n    \"8-0\": \"429\",\n    \"8-1\": \"Too Many Requests - The current user has hit the daily rate limit\"\n  },\n  \"cols\": 2,\n  \"rows\": 10\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API Wrappers\"\n}\n[/block]\nWe have Wrapper Libraries for the V2 API [available in our GitHub account](https://github.com/formstack/formstack-api).","excerpt":"The Formstack API allows users and 3rd party application to access resources programmatically. This API tries to conform to REST principals.","slug":"api-overview","type":"basic","title":"Overview"}

Overview

The Formstack API allows users and 3rd party application to access resources programmatically. This API tries to conform to REST principals.

[block:api-header] { "type": "basic", "title": "API Methods" } [/block] A list of all api methods (exposed as REST resources) can be found here: [Formstack API REST Resources](doc:resources) [block:api-header] { "type": "basic", "title": "Request Formats" } [/block] The Formstack API accepts two request data types: HTTP url encoded query parameters and JSON. By default, we expect HTTP url encoded query parameters. To use JSON, simply change the **Content-Type** header in your request to be **"Content-Type: application/json"** and put the JSON in the body of the request. [block:api-header] { "type": "basic", "title": "Response Formats" } [/block] The Formstack API offers two response types: JSON (default) and XML. To indicate which response type you would like to receive, simply add .xml or .json to the end of any resource URIs. If an extension is not present, we will respond with JSON. [block:code] { "codes": [ { "code": "https://www.formstack.com/api/v2/form.json\nhttps://www.formstack.com/api/v2/form/12334/submission.xml", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Obtaining an API key (OAuth2 Access Token)" } [/block] All of our API calls require authentication. The REST API uses OAuth2 access tokens for this purpose. [Creating an application](https://www.formstack.com/admin/apiKey/main) record will also create an access token. Access tokens are tied to a Formstack user and follow Formstack (in-app) user permissions. Additional access tokens can be generated by the OAuth2 [authorization](doc:authorization) process. To request an OAuth2 token to use with the Formstack API explorer, visit [here](https://www.formstack.com/readme_auth.php). [block:api-header] { "type": "basic", "title": "Authentication" } [/block] Once you have an access token, you can make authenticated api calls. To do this, include the access token in the HTTP Authorization header: [block:code] { "codes": [ { "code": "Authorization: Bearer <access-token>", "language": "http" } ] } [/block] On any GET api calls, you can set the access token as a part of the query string: [block:code] { "codes": [ { "code": "https://www.formstack.com/api/v2/form.json?oauth_token=abcdefg123456", "language": "text" } ] } [/block] [block:api-header] { "type": "basic", "title": "Rate Limits" } [/block] To prevent abuse, the Formstack API is rate limited to **14,400** calls per access token per day. [block:api-header] { "type": "basic", "title": "Status Codes" } [/block] The Formstack API uses standard HTTP status codes. [block:parameters] { "data": { "h-0": "Code", "h-1": "Description", "0-0": "200", "0-1": "OK - The request was handled without any errors", "1-0": "201", "1-1": "Created - A new resource was created", "2-0": "400", "2-1": "Bad Request - The request URI was invalid", "3-0": "401", "3-1": "Unauthorized - Valid OAuth2 credentials were not supplied", "4-0": "403", "4-1": "Forbidden - The current user does not have access to this method", "5-0": "404", "5-1": "Not Found - The resource requested could not be found", "6-0": "405", "6-1": "Method Not Allowed - The requested method does not exist", "7-0": "415", "7-1": "Unsupported Media Type - A valid media type (JSON, XML, HTTP URL encoded) was not used", "9-0": "500", "9-1": "Internal Server Error - An error occurred while processing the request", "8-0": "429", "8-1": "Too Many Requests - The current user has hit the daily rate limit" }, "cols": 2, "rows": 10 } [/block] [block:api-header] { "type": "basic", "title": "API Wrappers" } [/block] We have Wrapper Libraries for the V2 API [available in our GitHub account](https://github.com/formstack/formstack-api).