{"_id":"5a0487bf1058cd003cfb7aaf","category":"5a0487bf1058cd003cfb7a9c","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":["5835c945524e752500ba93bc"],"next":{"pages":[],"description":""},"createdAt":"2015-09-27T18:57:20.311Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"The PlanGrid API is hosted at [io.plangrid.com](https://io.plangrid.com).\n\nThis documentation describes PlanGrid’s API standards, data model, and endpoints. We strive for documentation that is understandable, detailed, and comprehensive. Please suggest edits when you feel we’re not accomplishing these goals (or forget commas).\n\nEvery endpoint in the PlanGrid API has a dedicated section and can be tested using the API Explorer (accessed via a button at the end of the section). The API Explorer may require you to enter your API key.","excerpt":"Our promise.","slug":"introduction","type":"basic","title":"Introduction","__v":0,"childrenPages":[]}
Introduction
The PlanGrid API is hosted at io.plangrid.com.
This documentation describes PlanGrid’s API standards, data model, and endpoints. We strive for documentation that is understandable, detailed, and comprehensive. Please suggest edits when you feel we’re not accomplishing these goals (or forget commas).
Every endpoint in the PlanGrid API has a dedicated section and can be tested using the API Explorer (accessed via a button at the end of the section). The API Explorer may require you to enter your API key.
{"_id":"5a0487bf1058cd003cfb7ab0","category":"5a0487bf1058cd003cfb7a9c","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-10-20T20:41:42.171Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"Our team is happy to answer any questions, address any frustrations, or consider any requests. You can communicate with us in the following ways:\n\n- [Request an invite](mailto:developers@plangrid.com?subject=PlanGrid API Slack channel invite request) to our Slack channel to chat with us and other PlanGrid API experts.\n- Post a question in [Stack Overflow](http://stackoverflow.com/questions/tagged/plangrid-api) and tag it with [`plangrid-api`](http://stackoverflow.com/questions/tagged/plangrid-api).\n- Contact support directly by emailing [developers@plangrid.com](mailto:developers@plangrid.com).\n\nWe'll do our best to accommodate you.","excerpt":"Did you try turning it off and on again?","slug":"support","type":"basic","title":"Support","__v":0,"childrenPages":[]}
Support
Our team is happy to answer any questions, address any frustrations, or consider any requests. You can communicate with us in the following ways:
- Request an invite to our Slack channel to chat with us and other PlanGrid API experts.
- Post a question in Stack Overflow and tag it with
plangrid-api
. - Contact support directly by emailing developers@plangrid.com.
We'll do our best to accommodate you.
{"_id":"5a0487bf1058cd003cfb7ab1","category":"5a0487bf1058cd003cfb7a9c","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":["5ab2b8b309e3140073269e96"],"next":{"pages":[],"description":""},"createdAt":"2016-10-20T20:55:50.291Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"status":400,"language":"json","code":"{}","name":""}]},"auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"We use conventions in our documentation to help you navigate and understand it.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Nomenclature\"\n}\n[/block]\nWe use consistent naming to describe concepts and features of an API:\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"*Record*\",\n \"0-1\": \"A single, implicitly structured data item. 99% of the time they have a unique identifier.\",\n \"0-2\": \"Each project in PlanGrid is considered a record\",\n \"1-0\": \"*Attribute* \",\n \"1-1\": \"A named value inside a record.\",\n \"1-2\": \"`project.name`\",\n \"2-0\": \"*Object* \",\n \"2-1\": \"Represents and defines a common record.\",\n \"2-2\": \"[The Project object](doc:the-project-object)\",\n \"4-0\": \"*Endpoint* \",\n \"4-1\": \"An API method\",\n \"5-0\": \"*Parameter* \",\n \"5-1\": \"A variable value passed to an endpoint\",\n \"4-2\": \"GET `/projects`\",\n \"5-2\": \"POST `/projects` needs a `name` parameter\",\n \"6-0\": \"*Request* \",\n \"6-1\": \"Calling an endpoint via an HTTP request\",\n \"6-2\": \"-\",\n \"h-0\": \"Word\",\n \"h-1\": \"Meaning\",\n \"h-2\": \"Example\",\n \"3-2\": \"[The RFI object](doc:the-rfi-object) contains an attribute that is a reference to its comments `rfi.comments`\",\n \"3-1\": \"A pointer or foreign key to a record\",\n \"3-0\": \"*Reference*\",\n \"7-0\": \"*Response*\",\n \"7-1\": \"The result of an HTTP request to an endpoint\",\n \"7-2\": \"-\"\n },\n \"cols\": 3,\n \"rows\": 8\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Organization\"\n}\n[/block]\nOur documentation is structured into categories in the following order:\n\n- *Introduction* - Introduces you to the API, our documentation, and how to start using it.\n- *Standards* - Describes our API standards and conventions.\n- *Common Objects* - Describes common objects used across multiple endpoints. Pages are ordered alphabetically.\n- *[Resource]* - Resource accessed via a URL pattern of `/[resource]` or `/projects/:project_uid/[resource]`. Ordered alphabetically.\n\n### Resources\n\nTo make the table of contents easily skimmable, documentation pages in Resource categories order by [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete):\n\n- Object definitions and background information on the resource\n- Endpoints and associated documentation to create a record\n- Endpoints and associated documentation to list records\n- Endpoints and associated documentation to retrieve single records\n- Endpoints and associated documentation to update a record\n- Endpoints and associated documentation to remove a record\n- Miscellanious endpoints and associated documentation related to the resource","excerpt":"","slug":"documentation-conventions","type":"basic","title":"Conventions","__v":1,"childrenPages":[]}
Conventions
We use conventions in our documentation to help you navigate and understand it.
We use consistent naming to describe concepts and features of an API:
Record
A single, implicitly structured data item. 99% of the time they have a unique identifier.
Each project in PlanGrid is considered a record
Attribute
A named value inside a record.
project.name
Reference
A pointer or foreign key to a record
The RFI object contains an attribute that is a reference to its comments rfi.comments
Endpoint
An API method
GET /projects
Parameter
A variable value passed to an endpoint
POST /projects
needs a name
parameter
Request
Calling an endpoint via an HTTP request
-
Response
The result of an HTTP request to an endpoint
-
Our documentation is structured into categories in the following order:
- Introduction - Introduces you to the API, our documentation, and how to start using it.
- Standards - Describes our API standards and conventions.
- Common Objects - Describes common objects used across multiple endpoints. Pages are ordered alphabetically.
- [Resource] - Resource accessed via a URL pattern of
/[resource]
or/projects/:project_uid/[resource]
. Ordered alphabetically.
Resources
To make the table of contents easily skimmable, documentation pages in Resource categories order by CRUD:
- Object definitions and background information on the resource
- Endpoints and associated documentation to create a record
- Endpoints and associated documentation to list records
- Endpoints and associated documentation to retrieve single records
- Endpoints and associated documentation to update a record
- Endpoints and associated documentation to remove a record
- Miscellanious endpoints and associated documentation related to the resource
{"_id":"5a0487bf1058cd003cfb7ab2","category":"5a0487bf1058cd003cfb7a9c","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-08-04T17:56:01.191Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"language":"json","code":"{}","name":"","status":200},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"To make it even easier to get started with the PlanGrid API, we provide libraries for the following languages and frameworks:\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Language/Framework\",\n \"h-1\": \"Source/Download\",\n \"0-1\": \"[plangrid-api-net](https://github.com/plangrid/plangrid-api-net)\",\n \"0-0\": \".NET\"\n },\n \"cols\": 2,\n \"rows\": 1\n}\n[/block]\nIf you've built a library for the PlanGrid API and would like it listed, please [contact support](mailto:developers@plangrid.com).","excerpt":"Oh my!","slug":"libraries-and-sdks","type":"basic","title":"Libraries, SDKs, and Packages","__v":0,"childrenPages":[]}
Libraries, SDKs, and Packages
To make it even easier to get started with the PlanGrid API, we provide libraries for the following languages and frameworks:
.NET
If you've built a library for the PlanGrid API and would like it listed, please contact support.
{"_id":"5a0487bf1058cd003cfb7ab3","category":"5a0487bf1058cd003cfb7a9c","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-07-26T21:58:12.172Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"code":"{}","name":"","status":200,"language":"json"},{"language":"json","code":"{}","name":"","status":400}]},"auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"We provide API access to PlanGrid customers and partners. If you're a customer, [please contact sales](https://www.plangrid.com/contact/) to purchase API access. If you're a software vendor interested in partnering, [please contact our partnerships team](mailto:partners@plangrid.com).","excerpt":"Tickets?","slug":"access","type":"basic","title":"Access","__v":0,"childrenPages":[]}
Access
We provide API access to PlanGrid customers and partners. If you're a customer, please contact sales to purchase API access. If you're a software vendor interested in partnering, please contact our partnerships team.
{"_id":"5a0487bf1058cd003cfb7ab4","category":"5a0487bf1058cd003cfb7a9c","user":"55d201fe945e481700afbb19","parentDoc":null,"project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-04T23:55:39.000Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"We don’t expect you to read our documentation like a book (you’ll get a little bored). Instead, we’d like to get you started right away and help you find the documentation you need. If that sounds appealing, keep reading. Otherwise, jump to [Standards](doc:getting-started).\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Get a List of Your Projects\"\n}\n[/block]\nWith 5 seconds of effort, you’ll grab a list of PlanGrid projects. We'll send HTTP requests to the PlanGrid API via the `curl` command. On Windows, you’ll need to install `curl` by downloading and running the “#.#.# - SSL enabled SSH enabled” installer [here](http://curl.haxx.se/dlwiz/?type=bin&os=Win32&flav=-&ver=*).\n\nOpen up a Terminal (OS X) or Command Prompt (Windows) and run the following command:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl -i https://io.plangrid.com/projects -u [[app:key]]: -H \\\"Accept: application/vnd.plangrid+json; version=1\\\"\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]\nBelow your command a list of projects should have been returned.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"data\\\": [\\n {\\n \\\"uid\\\": \\\"bafce976-8f33-437f-9c52-fb274456940f\\\",\\n \\\"name\\\": \\\"LA Natural History Museum\\\"\\n },\\n {\\n \\\"uid\\\": \\\"327e8c64-a70d-433c-b4ac-d077415a5547\\\",\\n \\\"name\\\": \\\"3265 17th Street\\\"\\n }\\n ],\\n \\\"total_count\\\": 2,\\n \\\"next_page_url\\\": null\\n}\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]\nCongratulations, you’ve successfully used the PlanGrid API! You may have noticed that you only received fifty projects; the reason is we paginate our results. You can learn more in [Pagination](doc:pagination).","excerpt":"Get your first data out of PlanGrid faster than a Camaro can do 0-60.","slug":"getting-started-1","type":"basic","title":"Quick Start","__v":0,"childrenPages":[]}
Quick Start
We don’t expect you to read our documentation like a book (you’ll get a little bored). Instead, we’d like to get you started right away and help you find the documentation you need. If that sounds appealing, keep reading. Otherwise, jump to Standards.
With 5 seconds of effort, you’ll grab a list of PlanGrid projects. We'll send HTTP requests to the PlanGrid API via the curl
command. On Windows, you’ll need to install curl
by downloading and running the “#.#.# - SSL enabled SSH enabled” installer here.
Open up a Terminal (OS X) or Command Prompt (Windows) and run the following command:
curl -i https://io.plangrid.com/projects -u [[app:key]]: -H "Accept: application/vnd.plangrid+json; version=1"
Below your command a list of projects should have been returned.
Congratulations, you’ve successfully used the PlanGrid API! You may have noticed that you only received fifty projects; the reason is we paginate our results. You can learn more in Pagination.
{
"data": [
{
"uid": "bafce976-8f33-437f-9c52-fb274456940f",
"name": "LA Natural History Museum"
},
{
"uid": "327e8c64-a70d-433c-b4ac-d077415a5547",
"name": "3265 17th Street"
}
],
"total_count": 2,
"next_page_url": null
}
{"_id":"5a0487c01058cd003cfb7acc","category":"5a0487bf1058cd003cfb7a9d","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":["5ab2c376b9178a0020a3316e"],"next":{"pages":[],"description":""},"createdAt":"2015-08-17T15:48:13.217Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"The PlanGrid API is a [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) API that uses predictable, resource-oriented URLs and standard [HTTP response codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). It uses built-in HTTP features, such as HTTP authentication and HTTP verbs, so it can be understood by off-the-shelf HTTP clients.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Security\"\n}\n[/block]\nPlanGrid [values](https://help.plangrid.com/customer/portal/articles/1253410-how-secure-is-plangrid-) the security of your data, and all API requests must be made over [HTTPS](https://en.wikipedia.org/wiki/HTTPS). \n\nWe strongly recommend you keep your API key as secure as possible:\n\n- Don't store it in publicly accessible code (e.g. Javascript for a public website).\n- Avoid checking it into source control. Use configuration files that can be loaded into your code.\n\nIf you think your API key is compromised, don't hesitate to [contact support](mailto:developers@plangrid.com). We will deactivate your API key and issue a new one.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"HTTP Verbs\"\n}\n[/block]\nPlanGrid’s API follows IETF standards ([RFC 5789](http://tools.ietf.org/html/rfc5789) & [RFC 7231](https://tools.ietf.org/html/rfc7231#section-4.3)) when using HTTP methods. A summary is provided below:\n\n| Verb | Used for... |\n|------|-------------|\n| GET | Retrieving records |\n| POST | Creating records |\n| PUT | Replacing records |\n| PATCH | Updating records |\n| DELETE | Deleting records |\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Responses\"\n}\n[/block]\nAll responses return [JSON](http://www.json.org/), including errors.\n\n### Blank Attributes\n\nBlank attributes are included as null instead of being omitted. The example below illustrates how the API would return an issue where `assignee`, `room`, and `current_annotation` are blank:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"uid\\\": \\\"22f3530a-a00b-42f9-8139-3a7554c77c27\\\",\\n \\\"number\\\": 1,\\n \\\"current_annotation\\\": null,\\n \\\"title\\\": \\\"Electrical\\\",\\n \\\"description\\\": \\\"Missing wall outlets.\\\",\\n \\\"assigned_to\\\": null,\\n \\\"status\\\": \\\"open\\\",\\n \\\"created_at\\\": \\\"2015-06-08T18:04:02+00:00\\\",\\n \\\"created_by\\\": {\\n \\\"email\\\": \\\"alfred@architect.com\\\"\\n },\\n \\\"updated_at\\\": \\\"2013-05-23T19:22:56+00:00\\\",\\n \\\"room\\\": null,\\n \\\"updated_by\\\": {\\n \\\"email\\\": \\\"betty@construction.com\\\"\\n }\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n### Errors\n\nErrors return a JSON object with a human readable message:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"message\\\": \\\"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\\\"\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nThe value of `message` may be updated in minor and patch versions; don’t write conditions that depend on it.\n\n### HTTP Compression\n\nThe API supports compression and clients can utilize this by requesting an encoding in the `Accept-Encoding` header:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"Accepted-Encoding: gzip, deflate\",\n \"language\": \"http\",\n \"name\": \"\"\n }\n ]\n}\n[/block]\n\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Requests\"\n}\n[/block]\nMany API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path (prefixed by `:` in our documentation) can be passed as an HTTP query string parameter (prefixed by `?` in our documentation).\n\nIn the example below, the `:project_uid` parameter is passed in as a segment of the URL path while pagination parameters (`?page` and `?per_page`) are passed in as HTTP query string parameters:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl https://io.plangrid.com/projects/bafce976-8f33-437f-9c58-fb274456940f/issues?page=2&per_page=10 -u [[app:key]]: -H \\\"Accept: application/vnd.plangrid+json; version=1\\\"\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]\nFor POST and PUT requests, parameters not included in the URL are passed in the request body. All request bodies must be encoded as JSON with a Content-Type of `‘application/json’`.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Unique Identifiers\"\n}\n[/block]\nEvery record\\* stored in PlanGrid is assigned a *universally* unique identifier (`uid`) that will not change. UIDs are strings with four dashes between thirty-two alphanumeric characters: `“cce19790-2f7b-46fc-ade0-c932181c35d9”`. You can safely use the PlanGrid `uid` when mapping PlanGrid records with another system’s records.\n\n<sub>* The two exceptions are the [RFI status record](doc:the-rfi-status-object) and [permission role record](doc:the-role-object). For RFI status records, the unique identifiers are strings with 8 alphanumeric characters (`'4898bfd4'`). The unique identifiers for permission role records are strings with four dashes between thirty-two alphanumeric characters (`'17dce2c5-4931-47e7-8c98-84b35f00ba03'`) but are _not_ universally unique.</sub>","excerpt":"Some basic conventions we've established.","slug":"getting-started","type":"basic","title":"Basics","__v":1,"childrenPages":[]}
Basics
The PlanGrid API is a REST API that uses predictable, resource-oriented URLs and standard HTTP response codes. It uses built-in HTTP features, such as HTTP authentication and HTTP verbs, so it can be understood by off-the-shelf HTTP clients.
PlanGrid values the security of your data, and all API requests must be made over HTTPS.
We strongly recommend you keep your API key as secure as possible:
- Don't store it in publicly accessible code (e.g. Javascript for a public website).
- Avoid checking it into source control. Use configuration files that can be loaded into your code.
If you think your API key is compromised, don't hesitate to contact support. We will deactivate your API key and issue a new one.
All responses return JSON, including errors.
Blank Attributes
Blank attributes are included as null instead of being omitted. The example below illustrates how the API would return an issue where assignee
, room
, and current_annotation
are blank:
{
"uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
"number": 1,
"current_annotation": null,
"title": "Electrical",
"description": "Missing wall outlets.",
"assigned_to": null,
"status": "open",
"created_at": "2015-06-08T18:04:02+00:00",
"created_by": {
"email": "alfred@architect.com"
},
"updated_at": "2013-05-23T19:22:56+00:00",
"room": null,
"updated_by": {
"email": "betty@construction.com"
}
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
Accepted-Encoding: gzip, deflate
Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path (prefixed by :
in our documentation) can be passed as an HTTP query string parameter (prefixed by ?
in our documentation).
In the example below, the :project_uid
parameter is passed in as a segment of the URL path while pagination parameters (?page
and ?per_page
) are passed in as HTTP query string parameters:
curl https://io.plangrid.com/projects/bafce976-8f33-437f-9c58-fb274456940f/issues?page=2&per_page=10 -u [[app:key]]: -H "Accept: application/vnd.plangrid+json; version=1"
For POST and PUT requests, parameters not included in the URL are passed in the request body. All request bodies must be encoded as JSON with a Content-Type of ‘application/json’
.
Every record* stored in PlanGrid is assigned a universally unique identifier (uid
) that will not change. UIDs are strings with four dashes between thirty-two alphanumeric characters: “cce19790-2f7b-46fc-ade0-c932181c35d9”
. You can safely use the PlanGrid uid
when mapping PlanGrid records with another system’s records.
* The two exceptions are the RFI status record and permission role record. For RFI status records, the unique identifiers are strings with 8 alphanumeric characters ('4898bfd4'
). The unique identifiers for permission role records are strings with four dashes between thirty-two alphanumeric characters ('17dce2c5-4931-47e7-8c98-84b35f00ba03'
) but are not universally unique.
{"_id":"5a0487c01058cd003cfb7acd","category":"5a0487bf1058cd003cfb7a9d","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-02T23:46:36.592Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","status":200,"language":"json","code":"{}"},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"We provide you two methods to authenticate with our API: [OAuth 2.0](https://oauth.net/2/) and [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). Depending on the use case and requirements, either method can be used to request PlanGrid data. For most applications we recommend using OAuth 2.0.\n[block:api-header]\n{\n \"title\": \"OAuth\"\n}\n[/block]\nOur API provides OAuth 2.0 as a protocol for authenticating and authorizing PlanGrid users. When using OAuth, a PlanGrid user will be required to log into their PlanGrid account and authorize your application access to their PlanGrid data. \n\nIf you are a developer looking to get started with OAuth, please [contact us](mailto:developers@plangrid.com) to register your application and obtain your credentials. Once you have received your credentials, you can jump to [Getting Started with OAuth](doc:getting-started-with-oauth).\n[block:callout]\n{\n \"type\": \"info\",\n \"title\": \"Registering your application\",\n \"body\": \"The following will be required when providing information about your application: application name, logo, and a list of redirect URIs.\"\n}\n[/block]\n\n[block:api-header]\n{\n \"title\": \"HTTP Basic Auth\"\n}\n[/block]\nTo use HTTP Basic Auth, you must send your API key with every request to the PlanGrid API. Put your API key as the basic auth username and leave the password blank:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl https://io.plangrid.com/projects -u [[app:key]]: -H \\\"Accept: application/vnd.plangrid+json; version=1\\\"\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]\nIf your API key is missing, the API will respond with a 401 status code. When the provided key is wrong or deactivated, the API will respond with a 403 status code. All three situations return a human-readable response specific to the situation.","excerpt":"Don’t trust strangers.","slug":"authentication","type":"basic","title":"Authentication","__v":0,"childrenPages":[]}
Authentication
We provide you two methods to authenticate with our API: OAuth 2.0 and HTTP Basic Auth. Depending on the use case and requirements, either method can be used to request PlanGrid data. For most applications we recommend using OAuth 2.0.
Our API provides OAuth 2.0 as a protocol for authenticating and authorizing PlanGrid users. When using OAuth, a PlanGrid user will be required to log into their PlanGrid account and authorize your application access to their PlanGrid data.
If you are a developer looking to get started with OAuth, please contact us to register your application and obtain your credentials. Once you have received your credentials, you can jump to Getting Started with OAuth.
Registering your application
The following will be required when providing information about your application: application name, logo, and a list of redirect URIs.
To use HTTP Basic Auth, you must send your API key with every request to the PlanGrid API. Put your API key as the basic auth username and leave the password blank:
curl https://io.plangrid.com/projects -u [[app:key]]: -H "Accept: application/vnd.plangrid+json; version=1"
If your API key is missing, the API will respond with a 401 status code. When the provided key is wrong or deactivated, the API will respond with a 403 status code. All three situations return a human-readable response specific to the situation.
{"_id":"5a0487c01058cd003cfb7ace","category":"5a0487bf1058cd003cfb7a9d","user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":["5ab2b98be0830400af92425f"],"next":{"pages":[],"description":""},"createdAt":"2015-09-10T23:44:47.701Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"language":"json","code":"{}","name":"","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"PlanGrid API versioning follows [semantic versioning](http://semver.org/). Any PlanGrid API version will be of the form `MAJOR.MINOR.PATCH`. Given a version number `MAJOR.MINOR.PATCH`, we increment the:\n\n- `MAJOR` version when we make incompatible API changes,\n- `MINOR` version when we add functionality in a backwards-compatible manner, and\n- `PATCH` version when we make backwards-compatible bug fixes.\n\nYou can use any `MINOR` and `PATCH` versions without fear of breaking changes.\n\nYou must explicitely specify the `MAJOR` version of the PlanGrid API via the `Accept` header:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"Accept: application/vnd.plangrid+json; version=[:MAJOR]\",\n \"language\": \"text\"\n }\n ]\n}\n[/block]\nFor instance, with `curl`:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl https://io.plangrid.com/... -H \\\"Accept: application/vnd.plangrid+json; version=1\\\"\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Version Support\"\n}\n[/block]\n`MAJOR` versions will be deprecated over time and you will have a 6 month grace period to migrate to a new `MAJOR` version. You will receive a notification via the account email when a `MAJOR` version is deprecated and each subsequent month you continue to use it. After the grace period, you will no longer have access to the deprecated version. \n\nWe will consider longer migration times for future `MAJOR` versions. Please [contact support](mailto:developers@plangrid.com) immediately if you cannot migrate to a newer `MAJOR` version in 6 months.","excerpt":"How we version the API.","slug":"api-versioning","type":"basic","title":"API Versioning","__v":1,"childrenPages":[]}
API Versioning
PlanGrid API versioning follows semantic versioning. Any PlanGrid API version will be of the form MAJOR.MINOR.PATCH
. Given a version number MAJOR.MINOR.PATCH
, we increment the:
MAJOR
version when we make incompatible API changes,MINOR
version when we add functionality in a backwards-compatible manner, andPATCH
version when we make backwards-compatible bug fixes.
You can use any MINOR
and PATCH
versions without fear of breaking changes.
You must explicitely specify the MAJOR
version of the PlanGrid API via the Accept
header:
Accept: application/vnd.plangrid+json; version=[:MAJOR]
For instance, with curl
:
curl https://io.plangrid.com/... -H "Accept: application/vnd.plangrid+json; version=1"
MAJOR
versions will be deprecated over time and you will have a 6 month grace period to migrate to a new MAJOR
version. You will receive a notification via the account email when a MAJOR
version is deprecated and each subsequent month you continue to use it. After the grace period, you will no longer have access to the deprecated version.
We will consider longer migration times for future MAJOR
versions. Please contact support immediately if you cannot migrate to a newer MAJOR
version in 6 months.
{"_id":"5a0487c01058cd003cfb7acf","category":"5a0487bf1058cd003cfb7a9d","user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-20T21:53:30.633Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"When deleting records through the PlanGrid app or API, they are removed from the app interface but not from our database. This allows references to deleted records to persist (e.g. a deleted photo still shows up on an RFI that references it) and data recovery to be possible (e.g. a project team member accidentally deletes some sheets).\n\nBy default, deleted records are returned through the API and can be identified when their `deleted` attribute is `true`.","excerpt":"\"Dawn of the Deleted\"","slug":"deleted-records","type":"basic","title":"Deleted Records","__v":0,"childrenPages":[]}
Deleted Records
When deleting records through the PlanGrid app or API, they are removed from the app interface but not from our database. This allows references to deleted records to persist (e.g. a deleted photo still shows up on an RFI that references it) and data recovery to be possible (e.g. a project team member accidentally deletes some sheets).
By default, deleted records are returned through the API and can be identified when their deleted
attribute is true
.
{"_id":"5a0487c01058cd003cfb7ad0","category":"5a0487bf1058cd003cfb7a9d","user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-12-21T01:31:58.176Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"When adding records such as photos or documents, you'll need to upload the record's file to PlanGrid. This is a two to three step process with the PlanGrid API:\n\n1. First, POST the record's attribute data and content type of its file to the PlanGrid API. PlanGrid creates a temporary record and sends back a [File Upload object](doc:the-file-upload-object) that contains information to upload the file and finalize the record (step two and three, respectively).\n2. Use the `aws_post_form_arguments` attribute in the [File Upload object](doc:the-file-upload-object) to securely POST the record's file to a private location in Amazon S3.\n - `aws_post_form_arguments.action` is the POST URL\n - `aws_post_form_arguments.fields` are the key-value pairs for the POST form fields.\n3. Once the upload is complete, tell the PlanGrid API it's complete via a GET to `webhook_url` provided in the [File Upload object](doc:the-file-upload-object) from step one. This makes the temporary record created in step one permanent. \n\nIf you configure your HTTP client to follow redirects (e.g. with `curl` use the `-L` flag), step three will be handled for you by Amazon S3. \n\nHere is an example in python that uploads a submittal PDF as a document to the first project listed via the API:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"import requests\\nfrom collections import OrderedDict\\n\\napi_prefix = 'https://io.plangrid.com'\\napi_key = '[[app:key]]'\\nversion_headers = {'Accept': 'application/vnd.plangrid+json; version=1'}\\n\\ndef get_first_project_uid():\\n # Get the UID of the first project returned from the API\\n projects_url = '{}/projects'.format(api_prefix)\\n response = requests.get(projects_url, auth=(api_key, None), headers=version_headers)\\n projects = response.json()['data']\\n first_project_uid = projects[0]['uid']\\n return first_project_uid\\n\\ndef request_attachment_upload(project_uid):\\n attachment_upload_url = '{}/projects/{}/attachments/uploads'.format(api_prefix, project_uid)\\n headers = {'content-type': 'application/json'}\\n headers.update(version_headers)\\n data = {'content_type': 'application/pdf', 'name': '0001-060000-1.pdf', 'folder': 'Submittals'}\\n response = requests.post(attachment_upload_url, json=data, headers=headers,\\n auth=(api_key, None))\\n file_upload_info = response.json()\\n return file_upload_info\\n\\ndef upload_file(file_upload_info):\\n url = file_upload_info['aws_post_form_arguments']['action']\\n fields = file_upload_info['aws_post_form_arguments']['fields']\\n fields = OrderedDict([(kv['name'], kv['value']) for kv in fields])\\n files = OrderedDict([('file', open('Submittal_0001-060000-1.pdf'))])\\n response = requests.post(url, files=files, data=fields)\\n return response.text\\n\\n# Example\\nproject_uid = get_first_project_uid()\\n\\n# Step 1\\nfile_upload_info = request_attachment_upload(project_uid=project_uid)\\n\\n# Step 2 (3 is handled automatically)\\nprint upload_file(file_upload_info=file_upload_info)\",\n \"language\": \"python\"\n }\n ]\n}\n[/block]\nWhen run, the script prints the new document record:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"deleted\\\": false,\\n \\\"created_at\\\": \\\"2015-12-22T06:11:56.849904+00:00\\\",\\n \\\"name\\\": \\\"0001-060000-1.pdf\\\",\\n \\\"uid\\\": \\\"ba65bfcf-a1fe-4dd4-9ef6-b381ac877174\\\",\\n \\\"url\\\": \\\"https://attachments.s3.amazonaws.com/da48fcc3-7af1-4fd6-a083-70195468718a/ba65bfcf-a1fe-4dd4-9ef6-b381ac877174_0001-060000-1.pdf?Signature=xc10DykUH8z4rcYMo8x%2F4PiH294%3D&Expires=1450782716&AWSAccessKeyId=AKIAIWKPH7OCNIEE5GGQ&response-content-disposition=attachment%3B%20filename%3D%220001-060000-1.pdf%22\\\",\\n \\\"created_by\\\": {\\n \\\"email\\\": \\\"abhik@plangrid.com\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/da48fcc3-7af1-4fd6-a083-70195468718a/users/54ab24c10d1c74ff22ae4874\\\",\\n \\\"uid\\\": \\\"54ab24c10d1c74ff22ae4874\\\"\\n },\\n \\\"folder\\\": \\\"Submittals\\\"\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]","excerpt":"Give us your PDFs, your GIFs, your JPEGs yearning to be rendered.","slug":"file-uploads","type":"basic","title":"File Uploads","__v":0,"childrenPages":[]}
File Uploads
When adding records such as photos or documents, you'll need to upload the record's file to PlanGrid. This is a two to three step process with the PlanGrid API:
- First, POST the record's attribute data and content type of its file to the PlanGrid API. PlanGrid creates a temporary record and sends back a File Upload object that contains information to upload the file and finalize the record (step two and three, respectively).
- Use the
aws_post_form_arguments
attribute in the File Upload object to securely POST the record's file to a private location in Amazon S3.aws_post_form_arguments.action
is the POST URLaws_post_form_arguments.fields
are the key-value pairs for the POST form fields.
- Once the upload is complete, tell the PlanGrid API it's complete via a GET to
webhook_url
provided in the File Upload object from step one. This makes the temporary record created in step one permanent.
If you configure your HTTP client to follow redirects (e.g. with curl
use the -L
flag), step three will be handled for you by Amazon S3.
Here is an example in python that uploads a submittal PDF as a document to the first project listed via the API:
import requests
from collections import OrderedDict
api_prefix = 'https://io.plangrid.com'
api_key = '[[app:key]]'
version_headers = {'Accept': 'application/vnd.plangrid+json; version=1'}
def get_first_project_uid():
# Get the UID of the first project returned from the API
projects_url = '{}/projects'.format(api_prefix)
response = requests.get(projects_url, auth=(api_key, None), headers=version_headers)
projects = response.json()['data']
first_project_uid = projects[0]['uid']
return first_project_uid
def request_attachment_upload(project_uid):
attachment_upload_url = '{}/projects/{}/attachments/uploads'.format(api_prefix, project_uid)
headers = {'content-type': 'application/json'}
headers.update(version_headers)
data = {'content_type': 'application/pdf', 'name': '0001-060000-1.pdf', 'folder': 'Submittals'}
response = requests.post(attachment_upload_url, json=data, headers=headers,
auth=(api_key, None))
file_upload_info = response.json()
return file_upload_info
def upload_file(file_upload_info):
url = file_upload_info['aws_post_form_arguments']['action']
fields = file_upload_info['aws_post_form_arguments']['fields']
fields = OrderedDict([(kv['name'], kv['value']) for kv in fields])
files = OrderedDict([('file', open('Submittal_0001-060000-1.pdf'))])
response = requests.post(url, files=files, data=fields)
return response.text
# Example
project_uid = get_first_project_uid()
# Step 1
file_upload_info = request_attachment_upload(project_uid=project_uid)
# Step 2 (3 is handled automatically)
print upload_file(file_upload_info=file_upload_info)
When run, the script prints the new document record:
{
"deleted": false,
"created_at": "2015-12-22T06:11:56.849904+00:00",
"name": "0001-060000-1.pdf",
"uid": "ba65bfcf-a1fe-4dd4-9ef6-b381ac877174",
"url": "https://attachments.s3.amazonaws.com/da48fcc3-7af1-4fd6-a083-70195468718a/ba65bfcf-a1fe-4dd4-9ef6-b381ac877174_0001-060000-1.pdf?Signature=xc10DykUH8z4rcYMo8x%2F4PiH294%3D&Expires=1450782716&AWSAccessKeyId=AKIAIWKPH7OCNIEE5GGQ&response-content-disposition=attachment%3B%20filename%3D%220001-060000-1.pdf%22",
"created_by": {
"email": "abhik@plangrid.com",
"url": "https://io.plangrid.com/projects/da48fcc3-7af1-4fd6-a083-70195468718a/users/54ab24c10d1c74ff22ae4874",
"uid": "54ab24c10d1c74ff22ae4874"
},
"folder": "Submittals"
}
{"_id":"5a0487c01058cd003cfb7ad1","category":"5a0487bf1058cd003cfb7a9d","parentDoc":null,"user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-10-23T22:33:46.706Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"language":"json","status":200,"name":"","code":"{}"},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":5,"body":"A record in PlanGrid may reference other records or collections of records. For instance, an issue in PlanGrid references the user who created the issue and a collection of photos. When you retrieve records from the PlanGrid API, it provides a URL to retrieve the references or the denormalized data (typically when the referenced data is small).\n\nAn example where the PlanGrid API denormalizes a reference is with RFIs. Instead of requiring you to retrieve the RFI status record, the API provides the RFI status within the RFI JSON object:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"status\\\": {\\n uid: '4898bfd4',\\n label: 'closed',\\n color: '#000000'\\n }\\n ...\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Reference to a Single Record\"\n}\n[/block]\nWhen a PlanGrid record references a single record, the PlanGrid API returns the `uid` of the referenced record and a URL to retrieve the referenced record's data:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"rfi\\\": {\\n \\\"uid\\\": \\\"437f7130-8ab3-4905-814a-f61fc8bd305c\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/78128c72-5862-458a-9577-33eaa189a5c1/rfis/437f7130-8ab3-4905-814a-f61fc8bd305c\\\"\\n }\\n ...\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"**uid**\\n`string`\",\n \"1-0\": \"**url**\\n`string`\",\n \"0-1\": \"Never blank.\",\n \"1-1\": \"The URL to retrieve the record's data. Never blank.\",\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\"\n },\n \"cols\": 2,\n \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Reference to a Collection of Records\"\n}\n[/block]\nWhen a PlanGrid record references a collection of records, the PlanGrid API returns the number of records in the collection and a URL to retrieve the referenced records:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n photos: {\\n total_count: 3,\\n url: \\\"https://io.plangrid.com/projects/78128c72-5862-458a-9577-33eaa189a5c1/issues/8510cfc9-2a82-4736-bf37-753c900d1c68/photos\\\"\\n }\\n ...\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"0-0\": \"**total_count**\\n`integer`\",\n \"0-1\": \"Number of records in the collection. Never blank and greater than or equal to zero.\",\n \"1-0\": \"**url**\\n`string`\",\n \"1-1\": \"The URL to retrieve the collection of records. Blank if total_count is zero.\"\n },\n \"cols\": 2,\n \"rows\": 2\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Reference to User(s)\"\n}\n[/block]\nReferences to users are a special case. On certain objects ([issues](doc:the-issue-object), [photos](doc:the-photo-object), [documents](doc:the-attachment-object)), users are referenced by email in PlanGrid's database. The email may not map to a real PlanGrid account, and the PlanGrid API will return a reference with `uid` and `url` set to `null`.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"created_by\\\": {\\n \\\"uid\\\": null,\\n \\\"url\\\": null,\\n \\\"email\\\": \\\"richard@subcontractor.com\\\"\\n }\\n ...\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"**uid**\\n`string`\",\n \"0-1\": \"May be blank.\",\n \"1-0\": \"**url**\\n`string`\",\n \"1-1\": \"The URL to retrieve the user record's data. May be blank.\",\n \"2-0\": \"**email**\\n`string`\",\n \"2-1\": \"User’s account email. May not be a valid email. Never blank.\",\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\"\n },\n \"cols\": 2,\n \"rows\": 3\n}\n[/block]\nWhen a collection of users is referenced, an array of user references is returned:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"assigned_to\\\": [\\n {\\n \\\"uid\\\": null,\\n \\\"url\\\": null,\\n \\\"email\\\": \\\"richard@subcontractor.com\\\"\\n },\\n {\\n \\\"uid\\\": \\\"8510cfc9-2a82-4736-bf37-753c900d1c68\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/78128c72-5862-458a-9577-33eaa189a5c1/users/8510cfc9-2a82-4736-bf37-753c900d1c68\\\",\\n \\\"email\\\": \\\"bob@subcontractor.com\\\"\\n }\\n ]\\n ...\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]","excerpt":"Easier than getting a work visa.","slug":"foreign-keys","type":"basic","title":"Foreign Keys","__v":0,"childrenPages":[]}
Foreign Keys
A record in PlanGrid may reference other records or collections of records. For instance, an issue in PlanGrid references the user who created the issue and a collection of photos. When you retrieve records from the PlanGrid API, it provides a URL to retrieve the references or the denormalized data (typically when the referenced data is small).
An example where the PlanGrid API denormalizes a reference is with RFIs. Instead of requiring you to retrieve the RFI status record, the API provides the RFI status within the RFI JSON object:
{
"status": {
uid: '4898bfd4',
label: 'closed',
color: '#000000'
}
}
When a PlanGrid record references a single record, the PlanGrid API returns the uid
of the referenced record and a URL to retrieve the referenced record's data:
{
"rfi": {
"uid": "437f7130-8ab3-4905-814a-f61fc8bd305c",
"url": "https://io.plangrid.com/projects/78128c72-5862-458a-9577-33eaa189a5c1/rfis/437f7130-8ab3-4905-814a-f61fc8bd305c"
}
}
uidstring
Never blank.
urlstring
The URL to retrieve the record's data. Never blank.
When a PlanGrid record references a collection of records, the PlanGrid API returns the number of records in the collection and a URL to retrieve the referenced records:
{
photos: {
total_count: 3,
url: "https://io.plangrid.com/projects/78128c72-5862-458a-9577-33eaa189a5c1/issues/8510cfc9-2a82-4736-bf37-753c900d1c68/photos"
}
}
total_countinteger
Number of records in the collection. Never blank and greater than or equal to zero.
urlstring
The URL to retrieve the collection of records. Blank if total_count is zero.
{
"created_by": {
"uid": null,
"url": null,
"email": "richard@subcontractor.com"
}
}
uidstring
May be blank.
urlstring
The URL to retrieve the user record's data. May be blank.
emailstring
User’s account email. May not be a valid email. Never blank.
When a collection of users is referenced, an array of user references is returned:
{
"assigned_to": [
{
"uid": null,
"url": null,
"email": "richard@subcontractor.com"
},
{
"uid": "8510cfc9-2a82-4736-bf37-753c900d1c68",
"url": "https://io.plangrid.com/projects/78128c72-5862-458a-9577-33eaa189a5c1/users/8510cfc9-2a82-4736-bf37-753c900d1c68",
"email": "bob@subcontractor.com"
}
]
}
{"_id":"5a0487c01058cd003cfb7ad2","category":"5a0487bf1058cd003cfb7a9d","user":"55d201fe945e481700afbb19","parentDoc":null,"project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-03T00:28:30.618Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"Endpoints that return multiple records use offset based pagination which uses`?limit` and `?skip` query parameters. `?limit` indicates the maximum number of records to return, and `?skip` indicates the number of items to skip in the set of unpaginated records. If an endpoint returned 6 issues, setting `?skip` to 2 and `?limit` to 3 would retrieve the third, fourth, and fifth issue:\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/X9uZVY8SSiSXe9g90tV8_image.png\",\n \"image.png\",\n \"975\",\n \"451\",\n \"#bbbbbb\",\n \"\"\n ]\n }\n ]\n}\n[/block]\nThe default and maximum number for `?limit` is 50, but you can request less. The default `?skip` value starts from the beginning of unpaginated records and is 0.\n\nThe curl command below skips two records and returns a maximum of ten records:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl https://io.plangrid.com/projects?skip=2&limit=10 -u [[app:key]]: -H \\\"Accept: application/vnd.plangrid+json; version=1\\\"\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]\nThe response to a request that returns multiple records is paginated and is always of the form:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"data\\\": [{}, {}, {}, {}, {}, {}, {}, {}, {}, {}],\\n \\\"total_count\\\": 14,\\n \\\"next_page_url\\\": \\\"https://io.plangrid.com/...?skip=12&limit=10\\\",\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n`data` is the array of records matched with `?skip` and `?limit`, `total_count` is the number of unpaginated records, and `next_page_url` is a url to the next page of records -- it will be `null` if you’ve reached the last page.\n\nIf `?limit` or `?skip` are not positive integers or 0, the PlanGrid API will return a 400 with an appropriate message.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Retrieving Records Created/Updated After a Specified Time\"\n}\n[/block]\nIf you're syncing PlanGrid with another system, you probably want to only retrieve records that have changed since your last sync. With the PlanGrid API you can achieve this with the `?updated_after` parameter. When added, the PlanGrid API only retrieves records created or updated after the specified UTC date and time (see [Timestamps and Timezones](doc:timestamps) for accepted date formats). It's supported on endpoints that have the potential to return large numbers of records (e.g. RFIs, issues, comments). For each endpoint you want to use the `?updated_after` parameter, check the endpoint's documentation to determine whether the parameter is supported.\n\nIt's important to note that the updated time of records with references (e.g. RFIs, issues) are updated when references change, but not when comments are added.","excerpt":"Bookmarks sold separately.","slug":"pagination","type":"basic","title":"Pagination","__v":0,"childrenPages":[]}
Pagination
Endpoints that return multiple records use offset based pagination which uses?limit
and ?skip
query parameters. ?limit
indicates the maximum number of records to return, and ?skip
indicates the number of items to skip in the set of unpaginated records. If an endpoint returned 6 issues, setting ?skip
to 2 and ?limit
to 3 would retrieve the third, fourth, and fifth issue:
The default and maximum number for ?limit
is 50, but you can request less. The default ?skip
value starts from the beginning of unpaginated records and is 0.
The curl command below skips two records and returns a maximum of ten records:
curl https://io.plangrid.com/projects?skip=2&limit=10 -u [[app:key]]: -H "Accept: application/vnd.plangrid+json; version=1"
The response to a request that returns multiple records is paginated and is always of the form:
{
"data": [{}, {}, {}, {}, {}, {}, {}, {}, {}, {}],
"total_count": 14,
"next_page_url": "https://io.plangrid.com/...?skip=12&limit=10",
}
data
is the array of records matched with ?skip
and ?limit
, total_count
is the number of unpaginated records, and next_page_url
is a url to the next page of records -- it will be null
if you’ve reached the last page.
If ?limit
or ?skip
are not positive integers or 0, the PlanGrid API will return a 400 with an appropriate message.
If you're syncing PlanGrid with another system, you probably want to only retrieve records that have changed since your last sync. With the PlanGrid API you can achieve this with the ?updated_after
parameter. When added, the PlanGrid API only retrieves records created or updated after the specified UTC date and time (see Timestamps and Timezones for accepted date formats). It's supported on endpoints that have the potential to return large numbers of records (e.g. RFIs, issues, comments). For each endpoint you want to use the ?updated_after
parameter, check the endpoint's documentation to determine whether the parameter is supported.
It's important to note that the updated time of records with references (e.g. RFIs, issues) are updated when references change, but not when comments are added.
{"_id":"5a0487c01058cd003cfb7ad3","category":"5a0487bf1058cd003cfb7a9d","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-03T00:21:02.109Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"PlanGrid API keys are attached to PlanGrid accounts. The API key has the same access privileges as the associated PlanGrid account: it can access all projects where the PlanGrid account is a team member and can perform actions allowed by the account’s project permissions. Access privileges for a PlanGrid account are described in detail in our [Help Center](https://help.plangrid.com/customer/portal/articles/1268049#understanding-permission-levels).\n\nTo use a PlanGrid API Key with all of your organization’s projects, add the PlanGrid account with the API key as a team member to each project. We strongly recommend establishing a policy that requires adding this PlanGrid account to every new project.\n\nIf you attempt an action outside your access privileges, the PlanGrid API will return a 403 with an appropriate message.","excerpt":"No access for you!","slug":"permissions","type":"basic","title":"Permissions","__v":0,"childrenPages":[]}
Permissions
PlanGrid API keys are attached to PlanGrid accounts. The API key has the same access privileges as the associated PlanGrid account: it can access all projects where the PlanGrid account is a team member and can perform actions allowed by the account’s project permissions. Access privileges for a PlanGrid account are described in detail in our Help Center.
To use a PlanGrid API Key with all of your organization’s projects, add the PlanGrid account with the API key as a team member to each project. We strongly recommend establishing a policy that requires adding this PlanGrid account to every new project.
If you attempt an action outside your access privileges, the PlanGrid API will return a 403 with an appropriate message.
{"_id":"5a0487c01058cd003cfb7ad4","category":"5a0487bf1058cd003cfb7a9d","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-03T00:50:00.634Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","status":200,"language":"json","code":"{}"},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":8,"body":"To ensure quality of service, multiple rate limits are applied per API key that affect different time intervals (e.g. per second, per hour) and types of requests (e.g. reads, writes). You can determine the rate limit status of your API key by requesting [Retrieve Rate Limits](doc:retrieve-rate-limits). It returns a paginated list of [Rate Limit Objects](doc:the-rate-limit-object) that describe the different rate limits applied to your API key. Each [object](doc:the-rate-limit-object) contains information about the types of requests it applies to, the length of the interval, how many requests are remaining in the interval, and when the interval resets:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"data\\\": [\\n {\\n \\\"request_type\\\": \\\"all\\\",\\n \\\"interval\\\": 1, \\n \\\"limit\\\": 40,\\n \\\"remaining\\\": 10,\\n \\\"reset\\\": \\\"2013-05-17T02:30:22+00:00\\\"\\n },\\n {\\n \\\"request_type\\\": \\\"all\\\",\\n \\\"interval\\\": 86400, \\n \\\"limit\\\": 10000,\\n \\\"remaining\\\": 2398,\\n \\\"reset\\\": \\\"2013-05-17T02:30:00+00:00\\\"\\n },\\n {\\n \\\"request_type\\\": \\\"write\\\",\\n \\\"interval\\\": 360, \\n \\\"limit\\\": 2000,\\n \\\"remaining\\\": 102,\\n \\\"reset\\\": \\\"2013-05-17T04:30:22+00:00\\\"\\n } \\n ],\\n \\\"next_page_url\\\": null,\\n \\\"total_count\\\": 3\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nCurrently, rate limits can be applied to the following types of requests:\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Request type\",\n \"h-1\": \"Applies to...\",\n \"0-0\": \"`all`\",\n \"1-0\": \"`write`\",\n \"0-1\": \"All requests\",\n \"1-1\": \"POST, PUT, PATCH, and DELETE requests\"\n },\n \"cols\": 2,\n \"rows\": 2\n}\n[/block]\nIf you're rate limited, the PlanGrid API returns a 429 with a JSON body that includes a [Rate Limit Object](doc:the-rate-limit-object) containing information about the rate limit that was hit:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"message\\\": \\\"API rate limit exceeded for developer cffe0ebb-2017-44d6-98d0-ddb0d48a3da8.\\\",\\n \\\"rate_limit\\\": {\\n \\\"request_type\\\": \\\"write\\\",\\n \\\"interval\\\": 360, \\n \\\"limit\\\": 2000,\\n \\\"remaining\\\": 102,\\n \\\"reset\\\": \\\"2013-05-17T04:30:22+00:00\\\"\\n }\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nYou can use the [Rate Limit Object](doc:the-rate-limit-object) to programmatically retry a rate limited request at the exact moment the rate limit resets. The example code below demonstrates this; it gets a list of all accessible projects and retries retrieval of a page of results if the request is rate limited:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"import datetime\\nfrom time import sleep\\n\\nimport dateutil.parser\\nimport pytz\\nimport requests\\n\\napi_prefix = 'https://io.plangrid.com'\\napi_key = '[[app:key]]'\\nversion_headers = {'Accept': 'application/vnd.plangrid+json; version=1'}\\n\\ndef get_projects():\\n # Get all of a user's projects from the API\\n all_projects = []\\n projects_url = '{}/projects'.format(api_prefix)\\n while projects_url is not None:\\n response = requests.get(projects_url, auth=(api_key, None), headers=version_headers)\\n\\n if response.status_code == 200:\\n # Save the projects that were successfully retrieved and go to the next page\\n projects = response.json()['data']\\n all_projects += projects\\n projects_url = response.json()['next_page_url']\\n\\n elif response.status_code == 429:\\n # Sleep until the rate limit has expired, then retry the same request\\n now = datetime.datetime.now(tz=pytz.utc)\\n reset_iso_format = response.json()['rate_limit']['reset']\\n reset = dateutil.parser.parse(reset_iso_format)\\n seconds_to_sleep = (reset - now).total_seconds()\\n sleep(seconds_to_sleep)\\n\\n return all_projects\\n\\n# Example\\nprojects = get_projects()\\n\\nprint projects\",\n \"language\": \"python\"\n }\n ]\n}\n[/block]\nIf you’re consistently rate limited, please [contact support](mailto:developers@plangrid.com) to see if your rate limits can be increased.","excerpt":"Happy responses come from happy servers.","slug":"rate-limiting","type":"basic","title":"Rate Limiting","__v":0,"childrenPages":[]}
Rate Limiting
To ensure quality of service, multiple rate limits are applied per API key that affect different time intervals (e.g. per second, per hour) and types of requests (e.g. reads, writes). You can determine the rate limit status of your API key by requesting Retrieve Rate Limits. It returns a paginated list of Rate Limit Objects that describe the different rate limits applied to your API key. Each object contains information about the types of requests it applies to, the length of the interval, how many requests are remaining in the interval, and when the interval resets:
{
"data": [
{
"request_type": "all",
"interval": 1,
"limit": 40,
"remaining": 10,
"reset": "2013-05-17T02:30:22+00:00"
},
{
"request_type": "all",
"interval": 86400,
"limit": 10000,
"remaining": 2398,
"reset": "2013-05-17T02:30:00+00:00"
},
{
"request_type": "write",
"interval": 360,
"limit": 2000,
"remaining": 102,
"reset": "2013-05-17T04:30:22+00:00"
}
],
"next_page_url": null,
"total_count": 3
}
Currently, rate limits can be applied to the following types of requests:
all
All requests
write
POST, PUT, PATCH, and DELETE requests
If you're rate limited, the PlanGrid API returns a 429 with a JSON body that includes a Rate Limit Object containing information about the rate limit that was hit:
{
"message": "API rate limit exceeded for developer cffe0ebb-2017-44d6-98d0-ddb0d48a3da8.",
"rate_limit": {
"request_type": "write",
"interval": 360,
"limit": 2000,
"remaining": 102,
"reset": "2013-05-17T04:30:22+00:00"
}
}
You can use the Rate Limit Object to programmatically retry a rate limited request at the exact moment the rate limit resets. The example code below demonstrates this; it gets a list of all accessible projects and retries retrieval of a page of results if the request is rate limited:
import datetime
from time import sleep
import dateutil.parser
import pytz
import requests
api_prefix = 'https://io.plangrid.com'
api_key = '[[app:key]]'
version_headers = {'Accept': 'application/vnd.plangrid+json; version=1'}
def get_projects():
# Get all of a user's projects from the API
all_projects = []
projects_url = '{}/projects'.format(api_prefix)
while projects_url is not None:
response = requests.get(projects_url, auth=(api_key, None), headers=version_headers)
if response.status_code == 200:
# Save the projects that were successfully retrieved and go to the next page
projects = response.json()['data']
all_projects += projects
projects_url = response.json()['next_page_url']
elif response.status_code == 429:
# Sleep until the rate limit has expired, then retry the same request
now = datetime.datetime.now(tz=pytz.utc)
reset_iso_format = response.json()['rate_limit']['reset']
reset = dateutil.parser.parse(reset_iso_format)
seconds_to_sleep = (reset - now).total_seconds()
sleep(seconds_to_sleep)
return all_projects
# Example
projects = get_projects()
print projects
If you’re consistently rate limited, please contact support to see if your rate limits can be increased.
{"_id":"5a0487c01058cd003cfb7ad5","category":"5a0487bf1058cd003cfb7a9d","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-09-22T07:02:52.834Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"auth":"required","params":[],"url":""},"isReference":false,"order":9,"body":"Any timestamps contained in the JSON response are represented as strings in [ISO 8601](http://www.w3.org/TR/NOTE-datetime) format with timezone set to [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time):\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"YYYY-MM-DDThh:mm:SS+00:00\",\n \"language\": \"text\"\n }\n ]\n}\n[/block]\nDates are of the form:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"YYYY-MM-DD\",\n \"language\": \"text\"\n }\n ]\n}\n[/block]\nYou will need to perform timezone conversions in your client.","excerpt":"It's always tea-time.","slug":"timestamps-and-timezones","type":"basic","title":"Timestamps and Timezones","__v":0,"childrenPages":[]}
Timestamps and Timezones
{"_id":"5a0487c01058cd003cfb7ad6","category":"5a0487bf1058cd003cfb7a9d","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-11-06T04:05:12.386Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"name":"","status":400,"language":"json","code":"{}"}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":10,"body":"Every record stored in PlanGrid is assigned a *universally*\\* unique identifier (`uid`) that will not change. UIDs are strings with four dashes between thirty-two alphanumeric characters: `“cce19790-2f7b-46fc-ade0-c932181c35d9”`. You can safely use the PlanGrid `uid` when mapping PlanGrid records with another system’s records.\n\n<sub>* The two exceptions are the [RFI status record](doc:the-rfi-status-object) and [permission role record](doc:the-role-object). For RFI status records, the unique identifiers are strings with 8 alphanumeric characters (`'4898bfd4'`). The unique identifiers for permission role records are strings with four dashes between thirty-two alphanumeric characters (`'17dce2c5-4931-47e7-8c98-84b35f00ba03'`) but are _not_ universally unique.</sub>","excerpt":"You're special.","slug":"unique-identifiers","type":"basic","title":"Unique Identifiers","__v":0,"childrenPages":[]}
Unique Identifiers
Every record stored in PlanGrid is assigned a universally* unique identifier (uid
) that will not change. UIDs are strings with four dashes between thirty-two alphanumeric characters: “cce19790-2f7b-46fc-ade0-c932181c35d9”
. You can safely use the PlanGrid uid
when mapping PlanGrid records with another system’s records.
* The two exceptions are the RFI status record and permission role record. For RFI status records, the unique identifiers are strings with 8 alphanumeric characters ('4898bfd4'
). The unique identifiers for permission role records are strings with four dashes between thirty-two alphanumeric characters ('17dce2c5-4931-47e7-8c98-84b35f00ba03'
) but are not universally unique.
{"_id":"5a0487c11058cd003cfb7b10","category":"5a0487bf1058cd003cfb7a9e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-12-21T01:31:10.928Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"language":"json","status":400,"name":"","code":"{}"}]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"When uploading files via PlanGrid's API, this object is returned after the first step and contains information necessary for subsequent steps. See [File Uploads](doc:file-uploads) for details.\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"**uid**\\n`string`\",\n \"4-0\": \"**webhook_url**\\n`string`\",\n \"0-1\": \"The unique identifier that will be assigned to the record associated with the file (e.g. Document, Photo). Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n \"4-1\": \"Once the file is uploaded, the URL to GET to complete creation of the record. Amazon S3 automatically redirects to this URL once the upload is complete.\",\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"1-0\": \"**aws_post_form_arguments**\\n`object`\",\n \"1-1\": \"Necessary information to securely POST file to Amazon S3.\",\n \"2-1\": \"The private URL to POST the file and security fields to.\",\n \"2-0\": \"**aws_post_form_arguments.action**\\n`string`\",\n \"3-0\": \"**aws_post_form_arguments.fields**\\n`array`\",\n \"3-1\": \"An array of ordered key-value pairs for the POST form fields that authenticate you with Amazon S3.\"\n },\n \"cols\": 2,\n \"rows\": 5\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \" {\\n \\\"uid\\\": \\\"022c132d-cdd0-48a1-8874-d4c9fd310ec8\\\",\\n \\\"webhook_url\\\": \\\"https://io.plangrid.com/projects/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7/attachments/uploads/completions/8392cd3fbf2dfbf9fc539c8423a21201\\\",\\n \\\"aws_post_form_arguments\\\": {\\n \\\"action\\\": \\\"https://plangrid-attachments.s3.amazonaws.com/\\\",\\n \\\"fields\\\": [\\n {\\n \\\"name\\\": \\\"key\\\",\\n \\\"value\\\": \\\"4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\\\\/1ab29ace-adfe-4ff0-b4bd-267ca612df9a_ff\\\"\\n },\\n {\\n \\\"name\\\": \\\"AWSAccessKeyId\\\",\\n \\\"value\\\": \\\"AKIAIWKPH7OCNIEE5GGQ\\\"\\n },\\n {\\n \\\"name\\\": \\\"success_action_redirect\\\",\\n \\\"value\\\": \\\"https:\\\\/\\\\/plangrid-c-api-dispatcher-test.herokuapp.com\\\\/projects\\\\/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\\\\/attachments\\\\/uploads\\\\/completions\\\\/1039b3921a93c7e74bdb3352779c2c6e\\\"\\n },\\n {\\n \\\"name\\\": \\\"policy\\\",\\n \\\"value\\\": \\\"eyJleHBpcmF0aW9uIjogIjIwMTUtMTItMjJUMjE6MTU6MTlaIiwKImNvbmRpdGlvbnMiOiBbeyJDb250ZW50LVR5cGUiOiAiYXBwbGljYXRpb24vcGRmIn0seyJidWNrZXQiOiAibG91cGUtdGVzdC1hdHRhY2gifSx7ImtleSI6ICI0ZDBmNGZmNi1iNGU3LWZiNDEtZWRiMi0xMzliMGZmZjllZjcvMWFiMjlhY2UtYWRmZS00ZmYwLWI0YmQtMjY3Y2E2MTJkZjlhX2ZmIn0seyJzdWNjZXNzX2FjdGlvbl9yZWRpcmVjdCI6ICJodHRwczovL3BsYW5ncmlkLWMtYXBpLWRpc3BhdGNoZXItdGVzdC5oZXJva3VhcHAuY29tL3YxL3Byb2plY3RzLzRkMGY0ZmY2LWI0ZTctZmI0MS1lZGIyLTEzOWIwZmZmOWVmNy9hdHRhY2htZW50cy91cGxvYWRzL2NvbXBsZXRpb25zLzEwMzliMzkyMWE5M2M3ZTc0YmRiMzM1Mjc3OWMyYzZlIn0seyJ4LWFtei1zdG9yYWdlLWNsYXNzIjogIlNUQU5EQVJEIn0seyJ4LWFtei1zZXJ2ZXItc2lkZS1lbmNyeXB0aW9uIjogIkFFUzI1NiJ9XX0=\\\"\\n },\\n {\\n \\\"name\\\": \\\"signature\\\",\\n \\\"value\\\": \\\"CztWq\\\\/9IU4hCaEiaw0P5IRYmh0g=\\\"\\n },\\n {\\n \\\"name\\\": \\\"Content-Type\\\",\\n \\\"value\\\": \\\"application\\\\/pdf\\\"\\n },\\n {\\n \\\"name\\\": \\\"x-amz-storage-class\\\",\\n \\\"value\\\": \\\"STANDARD\\\"\\n },\\n {\\n \\\"name\\\": \\\"x-amz-server-side-encryption\\\",\\n \\\"value\\\": \\\"AES256\\\"\\n }\\n ]\\n }\\n }\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-file-upload-object","type":"basic","title":"The File Upload Object","__v":0,"childrenPages":[]}
The File Upload Object
When uploading files via PlanGrid's API, this object is returned after the first step and contains information necessary for subsequent steps. See File Uploads for details.
uidstring
The unique identifier that will be assigned to the record associated with the file (e.g. Document, Photo). Never blank. See Unique Identifiers for details.
aws_post_form_argumentsobject
Necessary information to securely POST file to Amazon S3.
aws_post_form_arguments.actionstring
The private URL to POST the file and security fields to.
aws_post_form_arguments.fieldsarray
An array of ordered key-value pairs for the POST form fields that authenticate you with Amazon S3.
webhook_urlstring
Once the file is uploaded, the URL to GET to complete creation of the record. Amazon S3 automatically redirects to this URL once the upload is complete.
{
"uid": "022c132d-cdd0-48a1-8874-d4c9fd310ec8",
"webhook_url": "https://io.plangrid.com/projects/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7/attachments/uploads/completions/8392cd3fbf2dfbf9fc539c8423a21201",
"aws_post_form_arguments": {
"action": "https://plangrid-attachments.s3.amazonaws.com/",
"fields": [
{
"name": "key",
"value": "4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\/1ab29ace-adfe-4ff0-b4bd-267ca612df9a_ff"
},
{
"name": "AWSAccessKeyId",
"value": "AKIAIWKPH7OCNIEE5GGQ"
},
{
"name": "success_action_redirect",
"value": "https:\/\/plangrid-c-api-dispatcher-test.herokuapp.com\/projects\/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\/attachments\/uploads\/completions\/1039b3921a93c7e74bdb3352779c2c6e"
},
{
"name": "policy",
"value": "eyJleHBpcmF0aW9uIjogIjIwMTUtMTItMjJUMjE6MTU6MTlaIiwKImNvbmRpdGlvbnMiOiBbeyJDb250ZW50LVR5cGUiOiAiYXBwbGljYXRpb24vcGRmIn0seyJidWNrZXQiOiAibG91cGUtdGVzdC1hdHRhY2gifSx7ImtleSI6ICI0ZDBmNGZmNi1iNGU3LWZiNDEtZWRiMi0xMzliMGZmZjllZjcvMWFiMjlhY2UtYWRmZS00ZmYwLWI0YmQtMjY3Y2E2MTJkZjlhX2ZmIn0seyJzdWNjZXNzX2FjdGlvbl9yZWRpcmVjdCI6ICJodHRwczovL3BsYW5ncmlkLWMtYXBpLWRpc3BhdGNoZXItdGVzdC5oZXJva3VhcHAuY29tL3YxL3Byb2plY3RzLzRkMGY0ZmY2LWI0ZTctZmI0MS1lZGIyLTEzOWIwZmZmOWVmNy9hdHRhY2htZW50cy91cGxvYWRzL2NvbXBsZXRpb25zLzEwMzliMzkyMWE5M2M3ZTc0YmRiMzM1Mjc3OWMyYzZlIn0seyJ4LWFtei1zdG9yYWdlLWNsYXNzIjogIlNUQU5EQVJEIn0seyJ4LWFtei1zZXJ2ZXItc2lkZS1lbmNyeXB0aW9uIjogIkFFUzI1NiJ9XX0="
},
{
"name": "signature",
"value": "CztWq\/9IU4hCaEiaw0P5IRYmh0g="
},
{
"name": "Content-Type",
"value": "application\/pdf"
},
{
"name": "x-amz-storage-class",
"value": "STANDARD"
},
{
"name": "x-amz-server-side-encryption",
"value": "AES256"
}
]
}
}
{"_id":"5a0487c11058cd003cfb7b11","category":"5a0487bf1058cd003cfb7a9e","parentDoc":null,"user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","updates":["57b32e995800cc0e00b3c035"],"next":{"pages":[],"description":""},"createdAt":"2016-07-11T21:32:46.872Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"When generating a sheet packet, issue report, or any other shareable file, PlanGrid kicks off an asynchronous process to generate the file. To help you track when the file has been successfully generated, the PlanGrid API returns an object that gives you the current status and relevant URLs.\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"**uid**\\n`string`\",\n \"0-1\": \"The unique identifier assigned to the shareable object. Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"1-0\": \"**file_url**\\n`string`\",\n \"1-1\": \"URL to retrieve the shareable file.\",\n \"3-0\": \"**status**\\n`string`\",\n \"3-1\": \"Status of the shareable. Possible values are: \\\"incomplete\\\", \\\"complete\\\", \\\"errored\\\".\",\n \"2-0\": \"**resource**\\n`object`\",\n \"2-1\": \"Reference to itself (e.g. `this`, `self`). See [Foreign Keys](doc:foreign-keys) for attribute details.\"\n },\n \"cols\": 2,\n \"rows\": 4\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"uid\\\": \\\"92cf7193-af0c-42fc-a3ab-7ef5149da720\\\",\\n \\\"file_url\\\": \\\"https://packet-assets.plangrid.com/92cf7193-af0c-42fc-a3ab-7ef5149da720.pdf\\\",\\n \\\"resource\\\": {\\n \\\"uid\\\": \\\"92cf7193-af0c-42fc-a3ab-7ef5149da720\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/da48fcc3-7af1-4fd6-a083-70195468718a/sheets/packets/92cf7193-af0c-42fc-a3ab-7ef5149da720\\\"\\n },\\n \\\"status\\\": \\\"incomplete\\\"\\n}\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-shareable-object","type":"basic","title":"The Shareable Object","__v":0,"childrenPages":[]}
The Shareable Object
When generating a sheet packet, issue report, or any other shareable file, PlanGrid kicks off an asynchronous process to generate the file. To help you track when the file has been successfully generated, the PlanGrid API returns an object that gives you the current status and relevant URLs.
uidstring
The unique identifier assigned to the shareable object. Never blank. See Unique Identifiers for details.
file_urlstring
URL to retrieve the shareable file.
resourceobject
Reference to itself (e.g. this
, self
). See Foreign Keys for attribute details.
statusstring
Status of the shareable. Possible values are: "incomplete", "complete", "errored".
{
"uid": "92cf7193-af0c-42fc-a3ab-7ef5149da720",
"file_url": "https://packet-assets.plangrid.com/92cf7193-af0c-42fc-a3ab-7ef5149da720.pdf",
"resource": {
"uid": "92cf7193-af0c-42fc-a3ab-7ef5149da720",
"url": "https://io.plangrid.com/projects/da48fcc3-7af1-4fd6-a083-70195468718a/sheets/packets/92cf7193-af0c-42fc-a3ab-7ef5149da720"
},
"status": "incomplete"
}
{"_id":"5a0487bf1058cd003cfb7ac9","category":"5a0487bf1058cd003cfb7a9f","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-01-27T22:11:44.403Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"code":"{}","language":"json","status":200,"name":""},{"status":400,"name":"","code":"{}","language":"json"}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"A batch request allows you to send multiple API requests at a single time. This can help you avoid rate limits for actions that need to be repeated multiple times. Examples of when you might want to use batch requests include: \n* adding multiple users at a time to a project\n* requesting issues from multiple projects\n* requesting records across multiple pages of an endpoint\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Formatting a batch request\"\n}\n[/block]\nTo make a batch request, you must provide an array of requests and `POST` it to the `/batch` endpoint. Each request inside the batch request contains its own `method` and `path`, as well as a JSON-encoded `body` if required. Each request in the batch uses the same `Authorization`, `Content-Type` and `Accept` headers from the batch request but can be overwritten within the headers of that request.\n\nThe example below shows a batched request to retrieve a specific project with UID `43b198bb-d4f9-c302-9173-271050e424b7` and also create a new project named `test_create`.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"[\\n {\\n \\\"method\\\": \\\"GET\\\",\\n \\\"path\\\": \\\"/projects/43b198bb-d4f9-c302-9173-271050e424b7\\\" \\n },\\n {\\n \\\"method\\\": \\\"POST\\\",\\n \\\"path\\\": \\\"/projects\\\",\\n \\\"headers\\\": [\\n {\\n \\\"name\\\": \\\"Content-Type\\\",\\n \\\"value\\\": \\\"application/json\\\"\\n }\\n ],\\n \\\"body\\\": \\\"{\\\\\\\"name\\\\\\\": \\\\\\\"test_create\\\\\\\"}\\\"\\n },\\n {\\n \\\"method\\\": \\\"POST\\\",\\n \\\"path\\\": \\\"/projects\\\",\\n \\\"headers\\\": [\\n {\\n \\\"name\\\": \\\"Content-Type\\\",\\n \\\"value\\\": \\\"application/json\\\"\\n }\\n ],\\n \\\"body\\\": \\\"{}\\\"\\n }\\n]\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Response from a batch request\"\n}\n[/block]\nOnce a batch request is successfully completed, you will receive a single response that contains the results for all requests (in the same order as the original request). Each response contains its own `status_code` and a JSON-encoded `body`. For instance, the example above yields the following response that includes both `200` and `400` responses.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"data\\\": [\\n {\\n \\\"status_code\\\": 200,\\n \\\"headers\\\": [\\n {\\n \\\"name\\\": \\\"connection\\\",\\n \\\"value\\\": \\\"close\\\",\\n },\\n {\\n \\\"name\\\": \\\"content-type\\\",\\n \\\"value\\\": \\\"application/json\\\"\\n }\\n ],\\n \\\"body\\\": \\\"{\\\\\\\"uid\\\\\\\": \\\\\\\"43b198bb-d4f9-c302-9173-271050e424b7\\\\\\\", \\\\\\\"name\\\\\\\": \\\\\\\"1000 Issues\\\\\\\"}\\\"\\n },\\n {\\n \\\"status_code\\\": 200,\\n \\\"headers\\\": [\\n {\\n \\\"name\\\": \\\"connection\\\",\\n \\\"value\\\": \\\"close\\\",\\n },\\n {\\n \\\"name\\\": \\\"content-type\\\",\\n \\\"value\\\": \\\"application/json\\\"\\n }\\n ],\\n \\\"body\\\": \\\"{\\\\\\\"uid\\\\\\\": \\\\\\\"880597f4-c15b-4b95-8c32-0cdefdc1a091\\\\\\\", \\\\\\\"name\\\\\\\": \\\\\\\"test_create\\\\\\\"}\\\"\\n },\\n {\\n \\\"status_code\\\": 400,\\n \\\"headers\\\": [\\n {\\n \\\"name\\\": \\\"connection\\\",\\n \\\"value\\\": \\\"close\\\",\\n },\\n {\\n \\\"name\\\": \\\"content-type\\\",\\n \\\"value\\\": \\\"application/json\\\"\\n }\\n ],\\n \\\"body\\\": \\\"{\\\\\\\"message\\\\\\\": \\\\\\\"Fields must be in JSON body.\\\\\\\"}\\\"\\n }\\n]\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nPlease note that if you provide a malformed array, an array with too many requests, or an array with no requests, you will receive a `400` response for the batch request instead of a response like the one above. See the various errors in the [Send Batch Request](doc:send-batch-request) example.","excerpt":"","slug":"why-batch-requests","type":"basic","title":"Why Batch Requests?","__v":0,"childrenPages":[]}
Why Batch Requests?
A batch request allows you to send multiple API requests at a single time. This can help you avoid rate limits for actions that need to be repeated multiple times. Examples of when you might want to use batch requests include:
- adding multiple users at a time to a project
- requesting issues from multiple projects
- requesting records across multiple pages of an endpoint
To make a batch request, you must provide an array of requests and POST
it to the /batch
endpoint. Each request inside the batch request contains its own method
and path
, as well as a JSON-encoded body
if required. Each request in the batch uses the same Authorization
, Content-Type
and Accept
headers from the batch request but can be overwritten within the headers of that request.
The example below shows a batched request to retrieve a specific project with UID 43b198bb-d4f9-c302-9173-271050e424b7
and also create a new project named test_create
.
[
{
"method": "GET",
"path": "/projects/43b198bb-d4f9-c302-9173-271050e424b7"
},
{
"method": "POST",
"path": "/projects",
"headers": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"body": "{\"name\": \"test_create\"}"
},
{
"method": "POST",
"path": "/projects",
"headers": [
{
"name": "Content-Type",
"value": "application/json"
}
],
"body": "{}"
}
]
Once a batch request is successfully completed, you will receive a single response that contains the results for all requests (in the same order as the original request). Each response contains its own status_code
and a JSON-encoded body
. For instance, the example above yields the following response that includes both 200
and 400
responses.
{
"data": [
{
"status_code": 200,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"uid\": \"43b198bb-d4f9-c302-9173-271050e424b7\", \"name\": \"1000 Issues\"}"
},
{
"status_code": 200,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"uid\": \"880597f4-c15b-4b95-8c32-0cdefdc1a091\", \"name\": \"test_create\"}"
},
{
"status_code": 400,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"message\": \"Fields must be in JSON body.\"}"
}
]
Please note that if you provide a malformed array, an array with too many requests, or an array with no requests, you will receive a 400
response for the batch request instead of a response like the one above. See the various errors in the Send Batch Request example.
{"_id":"5a0487bf1058cd003cfb7aca","category":"5a0487bf1058cd003cfb7a9f","project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-01-25T01:32:45.513Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"name":"","code":"{}","language":"json"},{"language":"json","status":400,"name":"","code":"{}"}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"[block:parameters]\n{\n \"data\": {\n \"0-0\": \"**status_code**\\n`integer`\",\n \"1-0\": \"**headers**\\n`array`\",\n \"4-0\": \"**body**\\n`string`\",\n \"0-1\": \"The HTTP status code for this response.\",\n \"1-1\": \"The headers for this response.\",\n \"4-1\": \"The JSON-encoded body for this response.\",\n \"2-0\": \"**headers.name**\\n`string`\",\n \"2-1\": \"The name of the header.\",\n \"3-0\": \"**headers.value**\\n`string`\",\n \"3-1\": \"The value of the header.\",\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\"\n },\n \"cols\": 2,\n \"rows\": 5\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"status_code\\\": 200,\\n \\\"headers\\\": [\\n {\\n \\\"name\\\": \\\"connection\\\",\\n \\\"value\\\": \\\"close\\\",\\n },\\n {\\n \\\"name\\\": \\\"content-type\\\",\\n \\\"value\\\": \\\"application/json\\\"\\n }\\n ],\\n \\\"body\\\": \\\"{\\\\\\\"uid\\\\\\\": \\\\\\\"43b198bb-d4f9-c302-9173-271050e424b7\\\\\\\", \\\\\\\"name\\\\\\\": \\\\\\\"1000 Issues\\\\\\\"}\\\"\\n}\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-batch-request-object","type":"basic","title":"The Batch Request Object","__v":0,"childrenPages":[]}
The Batch Request Object
status_codeinteger
The HTTP status code for this response.
headersarray
The headers for this response.
headers.namestring
The name of the header.
headers.valuestring
The value of the header.
bodystring
The JSON-encoded body for this response.
{
"status_code": 200,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"uid\": \"43b198bb-d4f9-c302-9173-271050e424b7\", \"name\": \"1000 Issues\"}"
}
{"_id":"5a0487bf1058cd003cfb7acb","category":"5a0487bf1058cd003cfb7a9f","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-01-27T22:45:53.775Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"post","results":{"codes":[{"status":200,"language":"json","code":"{\n \"data\": [\n {\n \"status_code\": 200,\n \"headers\": [\n {\n \"name\": \"connection\",\n \"value\": \"close\",\n },\n {\n \"name\": \"content-type\",\n \"value\": \"application/json\"\n }\n ],\n \"body\": \"{\\\"uid\\\": \\\"43b198bb-d4f9-c302-9173-271050e424b7\\\", \\\"name\\\": \\\"1000 Issues\\\"}\"\n },\n {\n \"status_code\": 400,\n \"headers\": [\n {\n \"name\": \"connection\",\n \"value\": \"close\",\n },\n {\n \"name\": \"content-type\",\n \"value\": \"application/json\"\n }\n ],\n \"body\": \"{\\\"message\\\": \\\"Request body must be a JSON encoded string.\\\"}\"\n },\n {\n \"status_code\": 400,\n \"headers\": [\n {\n \"name\": \"connection\",\n \"value\": \"close\",\n },\n {\n \"name\": \"content-type\",\n \"value\": \"application/json\"\n }\n ],\n \"body\": \"{\\\"message\\\": \\\"Request must contain at least one field.\\\"}\"\n },\n {\n \"status_code\": 400,\n \"headers\": [\n {\n \"name\": \"connection\",\n \"value\": \"close\",\n },\n {\n \"name\": \"content-type\",\n \"value\": \"application/json\"\n }\n ],\n \"body\": \"{\\\"message\\\": \\\"Unsupported fields are not allowed in request.\\\"}\"\n },\n {\n \"status_code\": 400,\n \"headers\": [\n {\n \"name\": \"connection\",\n \"value\": \"close\",\n },\n {\n \"name\": \"content-type\",\n \"value\": \"application/json\"\n }\n ],\n \"body\": \"{\\\"message\\\": \\\"Method required to send batch request.\\\"}\"\n },\n {\n \"status_code\": 400,\n \"headers\": [\n {\n \"name\": \"connection\",\n \"value\": \"close\",\n },\n {\n \"name\": \"content-type\",\n \"value\": \"application/json\"\n }\n ],\n \"body\": \"{\\\"message\\\": \\\"Path required to send batch request.\\\"}\"\n },\n {\n \"status_code\": 400,\n \"headers\": [\n {\n \"name\": \"connection\",\n \"value\": \"close\",\n },\n {\n \"name\": \"content-type\",\n \"value\": \"application/json\"\n }\n ],\n \"body\": \"{\\\"message\\\": \\\"Path must begin with a '/'.\\\"}\"\n },\n {\n \"status_code\": 400,\n \"headers\": [\n {\n \"name\": \"connection\",\n \"value\": \"close\",\n },\n {\n \"name\": \"content-type\",\n \"value\": \"application/json\"\n }\n ],\n \"body\": \"{\\\"message\\\": \\\"Headers must be an array of objects with 'name' and 'value'.\\\"}\"\n },\n {\n \"status_code\": 400,\n \"headers\": [\n {\n \"name\": \"connection\",\n \"value\": \"close\",\n },\n {\n \"name\": \"content-type\",\n \"value\": \"application/json\"\n }\n ],\n \"body\": \"{\\\"message\\\": \\\"Unsupported fields are not allowed in headers.\\\"}\"\n },\n {\n \"status_code\": 500,\n \"headers\": [\n {\n \"name\": \"connection\",\n \"value\": \"close\",\n },\n {\n \"name\": \"content-type\",\n \"value\": \"application/json\"\n }\n ],\n \"body\": \"{\\\"message\\\": \\\"Sorry, PlanGrid's system had an error and the team has been notified. If this happens again, please contact support@plangrid.com.\\\"}\"\n }\n ]\n}","name":""},{"name":"No Requests","status":400,"language":"json","code":"{ \"message\": \"There must be at least one batch request.\" }"},{"name":"Too Many Requests","status":400,"language":"json","code":"{ \"message\": \"The number of batch requests (:number_of_requests) must be less than or equal to 50.\" }"},{"name":"Not An Array","status":400,"language":"json","code":"{ \"message\": \"JSON body must be an array.\" }"}]},"settings":"588bb90f33b1b337002e64e7","auth":"required","params":[],"url":"/batch"},"isReference":false,"order":2,"body":"The following example shows how to retrieve your projects and rate limits in one request.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl -i https://io.plangrid.com/batch -u [[app:key]]: -H \\\"Content-Type: application/json\\\" -H 'Accept: application/vnd.plangrid+json; version=1' -d '[{\\\"method\\\": \\\"GET\\\", \\\"path\\\": \\\"/projects\\\"}, {\\\"method\\\": \\\"GET\\\", \\\"path\\\": \\\"/rate_limits\\\"}]' -v\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]\nThe following example shows how to retrieve project data from multiple endpoints.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"import requests\\n\\napi_prefix = 'https://io.plangrid.com'\\napi_key = '[[app:key]]'\\nversion_headers = {'Accept': 'application/vnd.plangrid+json; version=1'}\\n\\ndef get_first_project_uid():\\n # Get the UID of the first project returned from the API\\n projects_url = '{}/projects'.format(api_prefix)\\n response = requests.get(projects_url, auth=(api_key, None), headers=version_headers)\\n projects = response.json()['data']\\n first_project_uid = projects[0]['uid']\\n return first_project_uid\\n\\ndef get_project_data(project_uid):\\n project_paths = [\\n \\\"/projects/{}\\\".format(project_uid),\\n \\\"/projects/{}/attachments\\\".format(project_uid),\\n \\\"/projects/{}/comments\\\".format(project_uid),\\n \\\"/projects/{}/issues\\\".format(project_uid),\\n \\\"/projects/{}/photos\\\".format(project_uid),\\n \\\"/projects/{}/rfis\\\".format(project_uid),\\n \\\"/projects/{}/roles\\\".format(project_uid),\\n \\\"/projects/{}/sheets\\\".format(project_uid),\\n \\\"/projects/{}/snapshots\\\".format(project_uid),\\n \\\"/projects/{}/users\\\".format(project_uid)\\n ]\\n\\n batch_requests = []\\n for path in project_paths:\\n batch_requests.append({\\n \\\"method\\\": \\\"GET\\\",\\n \\\"path\\\": path\\n })\\n\\n batch_url = '{}/batch'.format(api_prefix)\\n response = requests.post(url=batch_url, auth=(api_key, None), headers=version_headers, json=batch_requests)\\n\\n json_response = response.json()['data']\\n\\n return json_response\\n\\n# Get a project_uid for the batch\\nproject_uid = get_first_project_uid()\\n\\n# Perform a batch request\\nproject_data = get_project_data(project_uid=project_uid)\\n\\nprint project_data\",\n \"language\": \"python\"\n }\n ]\n}\n[/block]","excerpt":"","slug":"send-batch-request","type":"post","title":"Send Batch Request","__v":0,"childrenPages":[]}
postSend Batch Request
The following example shows how to retrieve your projects and rate limits in one request.
curl -i https://io.plangrid.com/batch -u [[app:key]]: -H "Content-Type: application/json" -H 'Accept: application/vnd.plangrid+json; version=1' -d '[{"method": "GET", "path": "/projects"}, {"method": "GET", "path": "/rate_limits"}]' -v
The following example shows how to retrieve project data from multiple endpoints.
import requests
api_prefix = 'https://io.plangrid.com'
api_key = '[[app:key]]'
version_headers = {'Accept': 'application/vnd.plangrid+json; version=1'}
def get_first_project_uid():
# Get the UID of the first project returned from the API
projects_url = '{}/projects'.format(api_prefix)
response = requests.get(projects_url, auth=(api_key, None), headers=version_headers)
projects = response.json()['data']
first_project_uid = projects[0]['uid']
return first_project_uid
def get_project_data(project_uid):
project_paths = [
"/projects/{}".format(project_uid),
"/projects/{}/attachments".format(project_uid),
"/projects/{}/comments".format(project_uid),
"/projects/{}/issues".format(project_uid),
"/projects/{}/photos".format(project_uid),
"/projects/{}/rfis".format(project_uid),
"/projects/{}/roles".format(project_uid),
"/projects/{}/sheets".format(project_uid),
"/projects/{}/snapshots".format(project_uid),
"/projects/{}/users".format(project_uid)
]
batch_requests = []
for path in project_paths:
batch_requests.append({
"method": "GET",
"path": path
})
batch_url = '{}/batch'.format(api_prefix)
response = requests.post(url=batch_url, auth=(api_key, None), headers=version_headers, json=batch_requests)
json_response = response.json()['data']
return json_response
# Get a project_uid for the batch
project_uid = get_first_project_uid()
# Perform a batch request
project_data = get_project_data(project_uid=project_uid)
print project_data
Definition
Result Format
{
"data": [
{
"status_code": 200,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"uid\": \"43b198bb-d4f9-c302-9173-271050e424b7\", \"name\": \"1000 Issues\"}"
},
{
"status_code": 400,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"message\": \"Request body must be a JSON encoded string.\"}"
},
{
"status_code": 400,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"message\": \"Request must contain at least one field.\"}"
},
{
"status_code": 400,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"message\": \"Unsupported fields are not allowed in request.\"}"
},
{
"status_code": 400,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"message\": \"Method required to send batch request.\"}"
},
{
"status_code": 400,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"message\": \"Path required to send batch request.\"}"
},
{
"status_code": 400,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"message\": \"Path must begin with a '/'.\"}"
},
{
"status_code": 400,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"message\": \"Headers must be an array of objects with 'name' and 'value'.\"}"
},
{
"status_code": 400,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"message\": \"Unsupported fields are not allowed in headers.\"}"
},
{
"status_code": 500,
"headers": [
{
"name": "connection",
"value": "close",
},
{
"name": "content-type",
"value": "application/json"
}
],
"body": "{\"message\": \"Sorry, PlanGrid's system had an error and the team has been notified. If this happens again, please contact support@plangrid.com.\"}"
}
]
}
{ "message": "There must be at least one batch request." }
{ "message": "The number of batch requests (:number_of_requests) must be less than or equal to 50." }
{ "message": "JSON body must be an array." }
{"_id":"5a0487c11058cd003cfb7aff","category":"5a0487bf1058cd003cfb7aa0","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"5a0487bf1058cd003cfb7a9b","updates":["5929fc5db1061c1900f8f0b4"],"next":{"pages":[],"description":""},"createdAt":"2017-02-16T21:15:07.278Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"code":"{}","language":"json","status":400,"name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"The PlanGrid API supports [OAuth 2.0](https://oauth.net/2/) as a protocol of authentication and authorization. OAuth 2.0 is an industry-standard protocol that allows third-party applications to obtain authorization to a user's data on their behalf. \n\n[Client libraries](https://oauth.net/code/#client-libraries) are also available to help you quickly develop applications based on the OAuth standards.\n[block:callout]\n{\n \"type\": \"info\",\n \"title\": \"Before you begin\",\n \"body\": \"You must register your application before you can start using OAuth with our API. If you are a developer looking to use OAuth, please [contact us](mailto:developers@plangrid.com) to register your application. You will need to provide the following information: application name, logo, and a list of redirect URIs.\"\n}\n[/block]\nWe support the **authorization code** and **implicit** grant types. You can read more below about each grant type and how to get started with the appropriate OAuth flow in your application.","excerpt":"","slug":"getting-started-with-oauth","type":"basic","title":"Getting Started with OAuth","__v":0,"childrenPages":[]}
Getting Started with OAuth
The PlanGrid API supports OAuth 2.0 as a protocol of authentication and authorization. OAuth 2.0 is an industry-standard protocol that allows third-party applications to obtain authorization to a user's data on their behalf.
Client libraries are also available to help you quickly develop applications based on the OAuth standards.
Before you begin
You must register your application before you can start using OAuth with our API. If you are a developer looking to use OAuth, please contact us to register your application. You will need to provide the following information: application name, logo, and a list of redirect URIs.
We support the authorization code and implicit grant types. You can read more below about each grant type and how to get started with the appropriate OAuth flow in your application.
{"_id":"5a0487c11058cd003cfb7b00","category":"5a0487bf1058cd003cfb7aa0","project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-08-04T19:43:53.454Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"code":"{}","language":"json","status":400,"name":""}]},"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"The **authorization code** grant type is a redirection-based flow most commonly used with server-side applications that can interact with the user-agent. If using this grant type, your application must be able to secure the client secret. This flow will provide both an access token and a refresh token.\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"1. Request user authorization\"\n}\n[/block]\nDirect your users to the `/oauth/authorize` endpoint with the `response_type` set to `code` and following parameters:\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Name\",\n \"h-1\": \"Description\",\n \"h-2\": \"Description\",\n \"0-0\": \"**client_id**\\n`string`\\n*Required* \",\n \"0-1\": \"A unique identifier for your application provided by PlanGrid.\",\n \"2-0\": \"**scope**\\n`string`\",\n \"3-0\": \"**redirect_uri**\\n`string`\",\n \"2-1\": \"Specify a group of resources an application can request access to. See [OAuth Scopes](doc:oauth-scopes) for details.\",\n \"1-0\": \"**state**\\n`string`\\n*Required*\",\n \"1-1\": \"An arbitrary string that will be included in the response. This can be used to confirm that the request originated from your application.\",\n \"3-1\": \"Specify a URL where the response will be redirected. Must match a value in the whitelist for this client.\"\n },\n \"cols\": 2,\n \"rows\": 4\n}\n[/block]\nAn example request would look like the following:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"https://io.plangrid.com/oauth/authorize?response_type=code&client_id=MY_CLIENT_ID&state=SECURITY_TOKEN&scope=write:projects%20read:profile&redirect_uri=https%3A%2F%myapplication.com%2Fcallback\",\n \"language\": \"http\"\n }\n ]\n}\n[/block]\nNote that the `response_type` is set to `code` for the authorization code flow.\n[block:callout]\n{\n \"type\": \"info\",\n \"title\": \"State:\",\n \"body\": \"As a security best practice, we recommend all client applications use a security token as the `state` parameter to prevent cross-site request forgery and other similar attacks on your application and users.\"\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"2. User authorizes your application\"\n}\n[/block]\nThe user will be directed to PlanGrid to authorize your application. Any errors will be displayed to the user.\n\nThe user must authorize your application to access the information defined in the request `scope`.\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/c966013-Screen_Shot_2017-02-17_at_2.59.38_PM.png\",\n \"Screen Shot 2017-02-17 at 2.59.38 PM.png\",\n 1152,\n 1116,\n \"#0c70b4\"\n ]\n }\n ]\n}\n[/block]\nAfter authorizing your application, the user-agent will be redirected to the `redirect_uri` along with an authorization code as a query parameter. For example, if your `redirect_uri` is `https://myapplication.com/callback`, the redirect will look like the following:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"https://myapplication.com/callback?code=AUTHORIZATION_CODE&state=SECURITY_TOKEN\",\n \"language\": \"http\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"3. Request access token\"\n}\n[/block]\nThe authorization code from the previous step can be used to retrieve the access token. To do so, you must `POST` to the `/oauth/token` endpoint with the parameters below. The request must be a URL encoded body with the header `Content-Type: application/x-www-form-urlencoded`.\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Name\",\n \"h-1\": \"Description\",\n \"0-0\": \"**client_id**\\n`string`\\n*Required*\",\n \"1-0\": \"**client_secret**\\n`string`\\n*Required*\",\n \"3-0\": \"**code**\\n`string`\",\n \"1-1\": \"A unique string for your application provided by PlanGrid.\",\n \"0-1\": \"A unique identifier for your application provided by PlanGrid.\",\n \"2-0\": \"**grant_type**\\n`string`\\n*Required*\",\n \"5-0\": \"**redirect_uri**\\n`string`\",\n \"2-1\": \"Type of request. Can be either `authorization_code` or `refresh_token`.\",\n \"3-1\": \"Required if `grant_type` is set to `authorization_code`. Must be the authorization code acquired from the `/oauth/authorize` endpoint.\",\n \"5-1\": \"If a `redirect_uri` was provided when requesting user authorization, this must match that value.\",\n \"4-0\": \"**refresh_token**\\n`string`\",\n \"4-1\": \"Required if `grant_type` is set to `refresh_token`. Must be the `refresh_token` provided with access token.\"\n },\n \"cols\": 2,\n \"rows\": 6\n}\n[/block]\nBelow is an example of a response from a successful request:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"refresh_token\\\": \\\"1d6f8598-f55e-11e6-bc64-92361f002671\\\",\\n \\\"access_token\\\": \\\"bb4e2271-e99c-4f66-bc1e-698ffd744f33\\\",\\n \\\"token_type\\\": \\\"bearer\\\",\\n \\\"expires_in\\\": 604800\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"4. Using access token\"\n}\n[/block]\nNow that you have an access token, your application can perform API requests on behalf of the user. Your header must include `Authorization: Bearer access_token` with the `access_token` from the previous steps.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"curl https://io.plangrid.com/projects -H \\\"Authorization: Bearer access_token\\\"\",\n \"language\": \"curl\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"title\": \"5. Refreshing accessing tokens\"\n}\n[/block]\nAccess tokens will periodically expire. You can use the `refresh_token` to request a new access token when that happens. This avoids forcing your user to re-authorize your application.\n\nTo request a new access token, you must `POST` to the `/oauth/token` endpoint with the `grant_type` parameter set to `refresh_token` and pass in the `refresh_token` as the value for the `refresh_token` parameter. If successful, you will receive a new `access_token`.","excerpt":"","slug":"authorization-code-grant-type","type":"basic","title":"Grant Type: Authorization Code","__v":0,"childrenPages":[]}
Grant Type: Authorization Code
The authorization code grant type is a redirection-based flow most commonly used with server-side applications that can interact with the user-agent. If using this grant type, your application must be able to secure the client secret. This flow will provide both an access token and a refresh token.
Direct your users to the /oauth/authorize
endpoint with the response_type
set to code
and following parameters:
client_idstring
Required
A unique identifier for your application provided by PlanGrid.
statestring
Required
An arbitrary string that will be included in the response. This can be used to confirm that the request originated from your application.
scopestring
Specify a group of resources an application can request access to. See OAuth Scopes for details.
redirect_uristring
Specify a URL where the response will be redirected. Must match a value in the whitelist for this client.
An example request would look like the following:
https://io.plangrid.com/oauth/authorize?response_type=code&client_id=MY_CLIENT_ID&state=SECURITY_TOKEN&scope=write:projects%20read:profile&redirect_uri=https%3A%2F%myapplication.com%2Fcallback
Note that the response_type
is set to code
for the authorization code flow.
State:
As a security best practice, we recommend all client applications use a security token as the state
parameter to prevent cross-site request forgery and other similar attacks on your application and users.
The user will be directed to PlanGrid to authorize your application. Any errors will be displayed to the user.
The user must authorize your application to access the information defined in the request scope
.
After authorizing your application, the user-agent will be redirected to the redirect_uri
along with an authorization code as a query parameter. For example, if your redirect_uri
is https://myapplication.com/callback
, the redirect will look like the following:
https://myapplication.com/callback?code=AUTHORIZATION_CODE&state=SECURITY_TOKEN
The authorization code from the previous step can be used to retrieve the access token. To do so, you must POST
to the /oauth/token
endpoint with the parameters below. The request must be a URL encoded body with the header Content-Type: application/x-www-form-urlencoded
.
client_idstring
Required
A unique identifier for your application provided by PlanGrid.
client_secretstring
Required
A unique string for your application provided by PlanGrid.
grant_typestring
Required
Type of request. Can be either authorization_code
or refresh_token
.
codestring
Required if grant_type
is set to authorization_code
. Must be the authorization code acquired from the /oauth/authorize
endpoint.
refresh_tokenstring
Required if grant_type
is set to refresh_token
. Must be the refresh_token
provided with access token.
redirect_uristring
If a redirect_uri
was provided when requesting user authorization, this must match that value.
Below is an example of a response from a successful request:
{
"refresh_token": "1d6f8598-f55e-11e6-bc64-92361f002671",
"access_token": "bb4e2271-e99c-4f66-bc1e-698ffd744f33",
"token_type": "bearer",
"expires_in": 604800
}
Now that you have an access token, your application can perform API requests on behalf of the user. Your header must include Authorization: Bearer access_token
with the access_token
from the previous steps.
curl https://io.plangrid.com/projects -H "Authorization: Bearer access_token"
Access tokens will periodically expire. You can use the refresh_token
to request a new access token when that happens. This avoids forcing your user to re-authorize your application.
To request a new access token, you must POST
to the /oauth/token
endpoint with the grant_type
parameter set to refresh_token
and pass in the refresh_token
as the value for the refresh_token
parameter. If successful, you will receive a new access_token
.
{"_id":"5a0487c11058cd003cfb7b01","category":"5a0487bf1058cd003cfb7aa0","project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-08-03T21:51:03.069Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"The **implicit** grant type is commonly used for applications where the client secret cannot be kept confidential and instead relies on the redirect URI provided for the application. This flow will provide the access token directly to the application during the redirection and does not support refresh tokens. In this flow, once the access tokens have expired, users will need to re-authenticate.\n[block:api-header]\n{\n \"title\": \"1. Request user authorization\"\n}\n[/block]\nDirect users to the `/oauth/authorize` endpoint with the following parameters and the `response_type` set to `token`.\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Name\",\n \"h-1\": \"Description\",\n \"0-0\": \"**client_id**\\n`string`\\n*Required* \",\n \"0-1\": \"A unique identifier for your application provided by PlanGrid.\",\n \"1-0\": \"**state**\\n`string`\\n*Required*\",\n \"1-1\": \"An arbitrary string that will be included in the response. This can be used to confirm that the request originated from your application.\",\n \"2-0\": \"**scope**\\n`string`\",\n \"2-1\": \"Specify a group of resources an application can request access to. See [OAuth Scopes](doc:oauth-scopes) for details.\",\n \"3-0\": \"**redirect_uri**\\n`string`\",\n \"3-1\": \"Specify a URL where the response will be redirected. Must match a value in the whitelist for this client.\"\n },\n \"cols\": 2,\n \"rows\": 4\n}\n[/block]\nAn example request would look like the following:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"https://io.plangrid.com/oauth/authorize?response_type=token&client_id=MY_CLIENT_ID&state=SECURITY_TOKEN&scope=write:projects%20read:profile&redirect_uri=https%3A%2F%myapplication.com%2Fcallback\",\n \"language\": \"http\"\n }\n ]\n}\n[/block]\nNote that the `response_type` is set to `token` for the implicit grant flow.\n[block:api-header]\n{\n \"title\": \"2. User authorizes your application\"\n}\n[/block]\nThe user will be directed to PlanGrid to authorize application access to data as defined in the `scope`.\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/711fc98-oauth-planet-express.png\",\n \"oauth-planet-express.png\",\n 559,\n 531,\n \"#0e72ba\"\n ]\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"title\": \"3. User-agent receives access token\"\n}\n[/block]\nOnce the user authorizes your application, the user-agent will be directed to the redirect URI with the access token included in the URI fragment like so:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"https://myapplication.com/callback#access_token=oauth_23846885sd2d3c83796113f2dbaaf1d9&token_type=Bearer&expires_in=604800&state=SECURITY_TOKEN\",\n \"language\": \"http\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"title\": \"4. Using the access token\"\n}\n[/block]\nNow that your application has the access token, you can perform requests on behalf of the user by including the `Authorization: Bearer access_token` header in your calls to the API.","excerpt":"","slug":"implicit-grant-type","type":"basic","title":"Grant Type: Implicit","__v":0,"childrenPages":[]}
Grant Type: Implicit
The implicit grant type is commonly used for applications where the client secret cannot be kept confidential and instead relies on the redirect URI provided for the application. This flow will provide the access token directly to the application during the redirection and does not support refresh tokens. In this flow, once the access tokens have expired, users will need to re-authenticate.
Direct users to the /oauth/authorize
endpoint with the following parameters and the response_type
set to token
.
client_idstring
Required
A unique identifier for your application provided by PlanGrid.
statestring
Required
An arbitrary string that will be included in the response. This can be used to confirm that the request originated from your application.
scopestring
Specify a group of resources an application can request access to. See OAuth Scopes for details.
redirect_uristring
Specify a URL where the response will be redirected. Must match a value in the whitelist for this client.
An example request would look like the following:
https://io.plangrid.com/oauth/authorize?response_type=token&client_id=MY_CLIENT_ID&state=SECURITY_TOKEN&scope=write:projects%20read:profile&redirect_uri=https%3A%2F%myapplication.com%2Fcallback
Note that the response_type
is set to token
for the implicit grant flow.
The user will be directed to PlanGrid to authorize application access to data as defined in the scope
.
Once the user authorizes your application, the user-agent will be directed to the redirect URI with the access token included in the URI fragment like so:
https://myapplication.com/callback#access_token=oauth_23846885sd2d3c83796113f2dbaaf1d9&token_type=Bearer&expires_in=604800&state=SECURITY_TOKEN
Now that your application has the access token, you can perform requests on behalf of the user by including the Authorization: Bearer access_token
header in your calls to the API.
{"_id":"5a0487c11058cd003cfb7b02","category":"5a0487bf1058cd003cfb7aa0","project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":["59f8feb3ccd5f90010ab1b54"],"next":{"pages":[],"description":""},"createdAt":"2017-08-16T20:06:44.729Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"Clients can specify the scope of access when requesting user authorization. Multiple scopes can be accessed by providing space separated values.\n\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Scope\",\n \"h-1\": \"Description\",\n \"0-0\": \"**write:projects**\",\n \"0-1\": \"Allows the application access to view and manage project data on your behalf. This is the default scope if no `scope` parameter is provided with an authorization request.\",\n \"1-0\": \"**read:profile**\",\n \"1-1\": \"Allows the application access to view the user profile, including UID, first name, last name, and email. This scope is required to access the [User Profile](doc:the-user-profile-object).\"\n },\n \"cols\": 2,\n \"rows\": 2\n}\n[/block]","excerpt":"","slug":"oauth-scopes","type":"basic","title":"OAuth Scopes","__v":0,"childrenPages":[]}
OAuth Scopes
Clients can specify the scope of access when requesting user authorization. Multiple scopes can be accessed by providing space separated values.
write:projects
Allows the application access to view and manage project data on your behalf. This is the default scope if no scope
parameter is provided with an authorization request.
read:profile
Allows the application access to view the user profile, including UID, first name, last name, and email. This scope is required to access the User Profile.
{"_id":"5a0487c11058cd003cfb7b03","category":"5a0487bf1058cd003cfb7aa0","project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-08-16T19:37:29.213Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":4,"body":"[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"0-0\": \"**access_token**\\n`string`\",\n \"1-0\": \"**refresh_token**\\n`string`\",\n \"2-0\": \"**token_type**\\n`string`\",\n \"3-0\": \"**expires_in**\\n`integer`\",\n \"4-0\": \"**scope**\\n`string`\",\n \"0-1\": \"The access token.\",\n \"4-1\": \"The scope of the access token as requested by the client. See [OAuth Scopes](doc:oauth-scopes) for details.\",\n \"3-1\": \"The lifetime in seconds of the access token.\",\n \"2-1\": \"The type of token issued.\",\n \"1-1\": \"The refresh token can be used to obtain a new access token. Only provided with the [authorization code grant type](doc:authorization-code-grant-type).\"\n },\n \"cols\": 2,\n \"rows\": 5\n}\n[/block]","excerpt":"","slug":"the-oauth-token-object","type":"basic","title":"The OAuth Token Object","__v":0,"childrenPages":[]}
The OAuth Token Object
access_tokenstring
The access token.
refresh_tokenstring
The refresh token can be used to obtain a new access token. Only provided with the authorization code grant type.
token_typestring
The type of token issued.
expires_ininteger
The lifetime in seconds of the access token.
scopestring
The scope of the access token as requested by the client. See OAuth Scopes for details.
{"_id":"5a0487c11058cd003cfb7b04","category":"5a0487bf1058cd003cfb7aa0","project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-02-13T19:12:16.646Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"code":"","language":"text"}]},"settings":"588bb90f33b1b337002e64e7","auth":"required","params":[{"_id":"58a4dc2e9b78df19004ab10c","ref":"","in":"query","required":true,"desc":"A unique identifier for your application provided by PlanGrid.","default":"","type":"string","name":"client_id"},{"_id":"58a4dc2e9b78df19004ab10d","ref":"","in":"query","required":true,"desc":"Specify what grant type the endpoint returns. Use `code` for the authorization code flow or `token` for the implicit grant flow.","default":"","type":"string","name":"response_type"},{"_id":"58a4dc2e9b78df19004ab10b","ref":"","in":"query","required":true,"desc":"An arbitrary string that will be included in the response. This can be used to confirm that the request originated from your application.","default":"","type":"string","name":"state"},{"_id":"58a4dc2e9b78df19004ab10a","ref":"","in":"query","required":false,"desc":"Specify a group of resources an application can request access to. See [OAuth Scopes](doc:oauth-scopes) for details.","default":"","type":"string","name":"scope"},{"_id":"58a4dc2e9b78df19004ab109","ref":"","in":"query","required":false,"desc":"Specify a URL where the response will be redirected. Must match a value in the whitelist for this client.","default":"","type":"string","name":"redirect_uri"}],"url":"/oauth/authorize"},"isReference":false,"order":5,"body":"[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Errors\",\n \"sidebar\": true\n}\n[/block]\n\n[block:textarea]\n{\n \"text\": \"If any error occurs during authorization, the user agent will be redirected to the redirect URI with one of the following error codes:\",\n \"sidebar\": true\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"0-0\": \"**invalid_request** \",\n \"0-1\": \"The request is missing a required parameter, includes an invalid parameter, includes a parameter more than once, or is otherwise malformed.\",\n \"1-0\": \"**unsupported_response_type**\",\n \"1-1\": \"An unsupported response type was requested.\",\n \"2-0\": \"**invalid_scope**\",\n \"2-1\": \"An invalid scope was provided.\",\n \"3-0\": \"**server_error**\",\n \"3-1\": \"An uncaught exception occurred during authorization.\"\n },\n \"cols\": 2,\n \"rows\": 4,\n \"sidebar\": true\n}\n[/block]","excerpt":"Redirect the user to PlanGrid to authorize the application. The first of a multi-step process for authenticating with OAuth 2.0. Upon user authorization, an authorization or token code will be provided based on the grant type.","slug":"retrieve-authorization-code","type":"get","title":"Retrieve Authorization Code","__v":0,"childrenPages":[]}
getRetrieve Authorization Code
Query Params
Definition
If any error occurs during authorization, the user agent will be redirected to the redirect URI with one of the following error codes:
invalid_request
The request is missing a required parameter, includes an invalid parameter, includes a parameter more than once, or is otherwise malformed.
unsupported_response_type
An unsupported response type was requested.
invalid_scope
An invalid scope was provided.
server_error
An uncaught exception occurred during authorization.
{"_id":"5a0487c11058cd003cfb7b05","category":"5a0487bf1058cd003cfb7aa0","parentDoc":null,"user":"57db49de0678030e008a76f8","project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-02-17T15:43:19.404Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"post","results":{"codes":[{"name":"","status":200,"language":"json","code":"{\n \"refresh_token\": \"a95b3fadb31941fe9b0a74cb71b721d\",\n \"access_token\": \"oauth_8107f78b473e46dab2406cd4db3bb366\",\n \"token_type\": \"Bearer\",\n \"expires_in\": 604800,\n \"scope\": \"write:projects\"\n}"}]},"settings":"58a619d52cb5710f0070d0de","auth":"required","params":[{"_id":"58a71aa0e29fd525004c9b1a","ref":"","in":"query","required":true,"desc":"A unique identifier for your application provided by PlanGrid.","default":"","type":"string","name":"client_id"},{"_id":"58a71aa0e29fd525004c9b19","ref":"","in":"query","required":true,"desc":"A unique string for your application provided by PlanGrid.","default":"","type":"string","name":"client_secret"},{"_id":"58a71aa0e29fd525004c9b1c","ref":"","in":"query","required":true,"desc":"Type of request. Can be either `authorization_code` or `refresh_token`.","default":"","type":"string","name":"grant_type"},{"_id":"58a71aa0e29fd525004c9b1b","ref":"","in":"query","required":false,"desc":"Required if `grant_type` is set to `authorization_code`. Must be the authorization code acquired from the `/oauth/authorize` endpoint.","default":"","type":"string","name":"code"},{"_id":"58e2e1f690f5250f0081e33d","ref":"","in":"query","required":false,"desc":"Required if `grant_type` is set to `refresh_token`. Must be the `refresh_token` provided with access token.","default":"","type":"string","name":"refresh_token"},{"_id":"58a71aa0e29fd525004c9b18","ref":"","in":"query","required":false,"desc":"If a `redirect_uri` was provided when requesting user authorization, this must match that value.","default":"","type":"string","name":"redirect_uri"}],"url":"/oauth/token"},"isReference":false,"order":6,"body":"","excerpt":"Once you have the `authorization_code` or a `refresh_token`, you can request the access token that will allow your application to perform API requests on behalf of the user.","slug":"retrieve-access-token","type":"post","title":"Retrieve Access Token","__v":0,"childrenPages":[]}
postRetrieve Access Token
Query Params
Definition
Result Format
{
"refresh_token": "a95b3fadb31941fe9b0a74cb71b721d",
"access_token": "oauth_8107f78b473e46dab2406cd4db3bb366",
"token_type": "Bearer",
"expires_in": 604800,
"scope": "write:projects"
}
{"_id":"5a0487c01058cd003cfb7ae5","category":"5a0487bf1058cd003cfb7aa1","user":"55d201fe945e481700afbb19","parentDoc":null,"project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-23T23:56:21.103Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"language":"json","status":200,"name":"","code":"{}"},{"code":"{}","language":"json","status":400,"name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"0-0\": \"**uid**\\n`string`\",\n \"0-1\": \"Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n \"1-0\": \"**name**\\n`string`\",\n \"1-1\": \"Project name.\",\n \"2-0\": \"**custom_id**\\n`string`\",\n \"2-1\": \"Project code.\",\n \"3-0\": \"**type**\\n`string`\",\n \"3-1\": \"Project type with possible values of `general`, `manufacturing`, `power`, `water-sewer-waste`, `industrial-petroleum`, `transportation`, `hazardous-waste`, `telecom`, `education-k-12`, `education-higher`, `gov-federal`, `gov-state-local`, or `other`.\",\n \"4-0\": \"**status**\\n`string`\",\n \"4-1\": \"Project status.\",\n \"5-0\": \"**owner**\\n`string`\",\n \"5-1\": \"Project owner.\",\n \"6-0\": \"**start_date**\\n`string`\",\n \"6-1\": \"Project start date. ISO-8601 date format (YYYY-MM-DD).\",\n \"7-0\": \"**end_date**\\n`string`\",\n \"7-1\": \"Project end date. ISO-8601 date format (YYYY-MM-DD).\",\n \"8-0\": \"**street_1**\\n`string`\",\n \"8-1\": \"Project address, street line 1.\",\n \"9-0\": \"**street_2**\\n`string`\",\n \"9-1\": \"Project address, street line 2.\",\n \"10-0\": \"**city**\\n`string`\",\n \"10-1\": \"Project address town or city.\",\n \"11-0\": \"**region**\\n`string`\",\n \"11-1\": \"Project address state, province, or region.\",\n \"12-0\": \"**postal_code**\\n`string`\",\n \"12-1\": \"Project address zip or postal code.\",\n \"13-0\": \"**country**\\n`string`\",\n \"13-1\": \"Project address country in 2-letter ISO 3166 code.\"\n },\n \"cols\": 2,\n \"rows\": 14\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"uid\\\": \\\"8510cfc9-2a82-4736-bf37-753c900d1c68\\\",\\n \\\"name\\\": \\\"LA Natural History Museum\\\",\\n \\\"custom_id\\\": \\\"5678\\\",\\n \\\"type\\\": \\\"general\\\",\\n \\\"status\\\": \\\"completed\\\",\\n \\\"owner\\\": \\\"ACME\\\",\\n \\\"start_date\\\": \\\"2001-10-01\\\",\\n \\\"end_date\\\": \\\"2050-10-01\\\",\\n \\\"street_1\\\": \\\"900 Exposition Blvd\\\",\\n \\\"street_2\\\": null,\\n \\\"city\\\": \\\"Los Angeles\\\",\\n \\\"region\\\": \\\"California\\\",\\n \\\"postal_code\\\": \\\"90007\\\",\\n \\\"country\\\": \\\"US\\\"\\n}\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-project-object","type":"basic","title":"The Project Object","__v":0,"childrenPages":[]}
The Project Object
uidstring
Never blank. See Unique Identifiers for details.
namestring
Project name.
custom_idstring
Project code.
typestring
Project type with possible values of general
, manufacturing
, power
, water-sewer-waste
, industrial-petroleum
, transportation
, hazardous-waste
, telecom
, education-k-12
, education-higher
, gov-federal
, gov-state-local
, or other
.
statusstring
Project status.
ownerstring
Project owner.
start_datestring
Project start date. ISO-8601 date format (YYYY-MM-DD).
end_datestring
Project end date. ISO-8601 date format (YYYY-MM-DD).
street_1string
Project address, street line 1.
street_2string
Project address, street line 2.
citystring
Project address town or city.
regionstring
Project address state, province, or region.
postal_codestring
Project address zip or postal code.
countrystring
Project address country in 2-letter ISO 3166 code.
{
"uid": "8510cfc9-2a82-4736-bf37-753c900d1c68",
"name": "LA Natural History Museum",
"custom_id": "5678",
"type": "general",
"status": "completed",
"owner": "ACME",
"start_date": "2001-10-01",
"end_date": "2050-10-01",
"street_1": "900 Exposition Blvd",
"street_2": null,
"city": "Los Angeles",
"region": "California",
"postal_code": "90007",
"country": "US"
}
{"_id":"5a0487c01058cd003cfb7ae6","category":"5a0487bf1058cd003cfb7aa1","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T20:14:39.609Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"post","results":{"codes":[{"code":"{\n \"uid\": \"bafce976-8f33-437f-9c52-fb274456940f\",\n \"name\": \"My New Construction Project.\",\n \"custom_id\": \"1234\",\n \"type\": \"general\",\n \"status\": \"bidding\",\n \"owner\": \"ACME\",\n \"start_date\": \"2001-10-01\",\n \"end_date\": \"2050-10-01\",\n \"street_1\": \"350 5th Avenue\",\n \"street_2\": null,\n \"city\": \"New York\",\n \"region\": \"New York\",\n \"postal_code\": \"10118\",\n \"country\": \"US\" \n}\n","language":"json","status":201,"name":"Success"},{"name":"Name Missing","code":"{\n \"message\": \"Project name required to create a project.\"\n}\n","language":"json","status":400},{"status":400,"name":"Name Blank","code":"{\n \"message\": \"Project name must be at least one character long.\"\n}\n","language":"json"},{"name":"Invalid Custom ID","status":400,"language":"json","code":"{\n \"message\": \"Custom ID must be null or a string at least one character long.\"\n}"},{"name":"Invalid Type","status":400,"language":"json","code":"{\n \"message\": \"Type (2) must be a valid project type.\"\n}"},{"name":"Invalid Status","status":400,"language":"json","code":"{\n \"message\": \"Status must be null or a string at least one character long.\"\n}"},{"code":"{\n \"message\": \"Owner must be null or a string at least one character long.\"\n}","name":"Invalid Owner","status":400,"language":"json"},{"name":"Invalid Start Date","status":400,"language":"json","code":"{\n \"message\": \"Start date (1234) must be null or a date string in ISO-8601 format (YYYY-MM-DD).\"\n}"},{"language":"json","code":"{\n \"message\": \"End date (1234) must be null or a date string in ISO-8601 format (YYYY-MM-DD).\"\n}","name":"Invalid End Date","status":400},{"name":"Invalid Street 1","status":400,"language":"json","code":"{\n \"message\": \"Street 1 must be null or a string at least one character long.\"\n}"},{"name":"Invalid Street 2","status":400,"language":"json","code":"{\n \"message\": \"Street 2 must be null or a string at least one character long.\"\n}"},{"code":"{\n \"message\": \"City must be null or a string at least one character long.\"\n}","name":"Invalid City","status":400,"language":"json"},{"name":"Invalid Region","status":400,"language":"json","code":"{\n \"message\": \"Postal code must be null or a string at least one character long.\"\n}"},{"status":400,"name":"Invalid Country","code":"{\n \"message\": \"Country must be an ISO 3166 two letter country code.\"\n}","language":"json"}]},"settings":"","auth":"required","params":[{"_id":"56cf1ed65267d70b00494c04","ref":"","in":"body","required":true,"desc":"Name of the project. Must be at least one character long.","default":"","type":"string","name":"name"},{"_id":"58ee7efdb4f0dd390087363f","ref":"","in":"body","required":false,"desc":"Project code.","default":"null","type":"string","name":"custom_id"},{"_id":"58ee7efdb4f0dd390087363e","ref":"","in":"body","required":false,"desc":"Project type with possible values of `general`, `manufacturing`, `power`, `water-sewer-waste`, `industrial-petroleum`, `transportation`, `hazardous-waste`, `telecom`, `education-k-12`, `education-higher`, `gov-federal`, `gov-state-local`, or `other`.","default":"null","type":"string","name":"type"},{"_id":"58ee7efdb4f0dd390087363d","ref":"","in":"body","required":false,"desc":"Project status.","default":"null","type":"string","name":"status"},{"_id":"58ee7efdb4f0dd390087363c","ref":"","in":"body","required":false,"desc":"Project owner.","default":"null","type":"string","name":"owner"},{"_id":"58ee7efdb4f0dd390087363b","ref":"","in":"body","required":false,"desc":"Project start date. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"null","type":"string","name":"start_date"},{"_id":"58ee7efdb4f0dd390087363a","ref":"","in":"body","required":false,"desc":"Project end date. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"null","type":"string","name":"end_date"},{"_id":"58ee7efdb4f0dd3900873639","ref":"","in":"body","required":false,"desc":"Project address, street line 1.","default":"null","type":"string","name":"street_1"},{"_id":"58ee7efdb4f0dd3900873638","ref":"","in":"body","required":false,"desc":"Project address, street line 2.","default":"null","type":"string","name":"street_2"},{"_id":"58ee7efdb4f0dd3900873637","ref":"","in":"body","required":false,"desc":"Project address town or city.","default":"null","type":"string","name":"city"},{"_id":"58ee7efdb4f0dd3900873636","ref":"","in":"body","required":false,"desc":"Project address state, province, or region.","default":"null","type":"string","name":"region"},{"_id":"58ee7efdb4f0dd3900873635","ref":"","in":"body","required":false,"desc":"Project address zip or postal code.","default":"null","type":"string","name":"postal_code"},{"_id":"58ee7efdb4f0dd3900873634","ref":"","in":"body","required":false,"desc":"Project address country in 2-letter ISO 3166 code.","default":"null","type":"string","name":"country"}],"url":"/projects"},"isReference":false,"order":1,"body":"","excerpt":"Create a new PlanGrid project. The PlanGrid account associated with the API key is added as an admin to the project team.","slug":"create-project","type":"post","title":"Create Project","__v":0,"childrenPages":[]}
postCreate Project
Body Params
Definition
Result Format
{
"uid": "bafce976-8f33-437f-9c52-fb274456940f",
"name": "My New Construction Project.",
"custom_id": "1234",
"type": "general",
"status": "bidding",
"owner": "ACME",
"start_date": "2001-10-01",
"end_date": "2050-10-01",
"street_1": "350 5th Avenue",
"street_2": null,
"city": "New York",
"region": "New York",
"postal_code": "10118",
"country": "US"
}
{
"message": "Project name required to create a project."
}
{
"message": "Project name must be at least one character long."
}
{
"message": "Custom ID must be null or a string at least one character long."
}
{
"message": "Type (2) must be a valid project type."
}
{
"message": "Status must be null or a string at least one character long."
}
{
"message": "Owner must be null or a string at least one character long."
}
{
"message": "Start date (1234) must be null or a date string in ISO-8601 format (YYYY-MM-DD)."
}
{
"message": "End date (1234) must be null or a date string in ISO-8601 format (YYYY-MM-DD)."
}
{
"message": "Street 1 must be null or a string at least one character long."
}
{
"message": "Street 2 must be null or a string at least one character long."
}
{
"message": "City must be null or a string at least one character long."
}
{
"message": "Postal code must be null or a string at least one character long."
}
{
"message": "Country must be an ISO 3166 two letter country code."
}
{"_id":"5a0487c01058cd003cfb7ae7","category":"5a0487bf1058cd003cfb7aa1","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T19:42:29.403Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"status":200,"name":"Success","code":"{\n \"data\": [\n {\n \"uid\": \"bafce976-8f33-437f-9c52-fb274456940f\",\n \"name\": \"LA Natural History Museum\",\n \"custom_id\": \"5678\",\n \"type\": \"general\",\n \"status\": \"completed\",\n \"owner\": \"ACME\",\n \"start_date\": \"2001-10-01\",\n \"end_date\": \"2050-10-01\",\n \"street_1\": \"900 Exposition Blvd\",\n \"street_2\": null,\n \"city\": \"Los Angeles\",\n \"region\": \"California\",\n \"postal_code\": \"90007\",\n \"country\": \"US\"\n },\n {\n \"uid\": \"327e8c64-a70d-433c-b4ac-d077415a5547\",\n \"name\": \"3265 17th Street\",\n \"custom_id\": \"1234\",\n \"type\": \"general\",\n \"status\": \"bidding\",\n \"owner\": \"ACME\",\n \"start_date\": \"2001-10-01\",\n \"end_date\": \"2050-10-01\",\n \"street_1\": \"3265 17th Street\",\n \"street_2\": \"#404\",\n \"city\": \"New York\",\n \"region\": \"New York\",\n \"postal_code\": \"10118\",\n \"country\": \"US\"\n }\n ],\n \"total_count\": 100,\n \"next_page_url\": \"https://io.plangrid.com/projects?skip=2&limit=2\"\n}\n","language":"json"}]},"settings":"","auth":"required","params":[{"_id":"56cf1ed65267d70b00494c03","ref":"","in":"query","required":false,"desc":"Number of projects to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ed65267d70b00494c02","ref":"","in":"query","required":false,"desc":"Number of projects to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"56edae5ffc1410200082dc60","ref":"","in":"query","required":false,"desc":"Only retrieve projects created/updated after specified UTC date and time (does not count changes in records contained in project). See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"datetime","name":"updated_after"}],"url":"/projects"},"isReference":false,"order":2,"body":"","excerpt":"Get a list of projects where the PlanGrid account is a team member. Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"list-all-projects","type":"get","title":"List All Projects","__v":0,"childrenPages":[]}
getList All Projects
Query Params
Definition
Result Format
{
"data": [
{
"uid": "bafce976-8f33-437f-9c52-fb274456940f",
"name": "LA Natural History Museum",
"custom_id": "5678",
"type": "general",
"status": "completed",
"owner": "ACME",
"start_date": "2001-10-01",
"end_date": "2050-10-01",
"street_1": "900 Exposition Blvd",
"street_2": null,
"city": "Los Angeles",
"region": "California",
"postal_code": "90007",
"country": "US"
},
{
"uid": "327e8c64-a70d-433c-b4ac-d077415a5547",
"name": "3265 17th Street",
"custom_id": "1234",
"type": "general",
"status": "bidding",
"owner": "ACME",
"start_date": "2001-10-01",
"end_date": "2050-10-01",
"street_1": "3265 17th Street",
"street_2": "#404",
"city": "New York",
"region": "New York",
"postal_code": "10118",
"country": "US"
}
],
"total_count": 100,
"next_page_url": "https://io.plangrid.com/projects?skip=2&limit=2"
}
{"_id":"5a0487c01058cd003cfb7ae8","category":"5a0487bf1058cd003cfb7aa1","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T19:56:25.570Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"language":"json","status":200,"name":"Success","code":"{\n \"uid\": \"bafce976-8f33-437f-9c52-fb274456940f\",\n \"name\": \"LA Natural History Museum\",\n \"custom_id\": \"5678\",\n \"type\": \"general\",\n \"status\": \"completed\",\n \"owner\": \"ACME\",\n \"start_date\": \"2001-10-01\",\n \"end_date\": \"2050-10-01\",\n \"street_1\": \"900 Exposition Blvd\",\n \"street_2\": null,\n \"city\": \"Los Angeles\",\n \"region\": \"California\",\n \"postal_code\": \"90007\",\n \"country\": \"US\"\n}\n"},{"code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","language":"json","status":404,"name":"Project Missing"},{"status":403,"name":"No Access","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","language":"json"}]},"settings":"","auth":"required","params":[{"_id":"56cf1ed55267d70b00494c01","ref":"","in":"path","required":true,"desc":"Unique identifier of project to retrieve.","default":"","type":"string","name":"project_uid"}],"url":"/projects/:project_uid"},"isReference":false,"order":3,"body":"","excerpt":"Get a specific project by unique identifier.","slug":"retrieve-a-project","type":"get","title":"Retrieve a Project","__v":0,"childrenPages":[]}
getRetrieve a Project
Path Params
Definition
Result Format
{
"uid": "bafce976-8f33-437f-9c52-fb274456940f",
"name": "LA Natural History Museum",
"custom_id": "5678",
"type": "general",
"status": "completed",
"owner": "ACME",
"start_date": "2001-10-01",
"end_date": "2050-10-01",
"street_1": "900 Exposition Blvd",
"street_2": null,
"city": "Los Angeles",
"region": "California",
"postal_code": "90007",
"country": "US"
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{"_id":"5a0487c01058cd003cfb7ae9","category":"5a0487bf1058cd003cfb7aa1","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T19:38:02.478Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","examples":{"codes":[]},"method":"patch","results":{"codes":[{"name":"","code":"{\n \"uid\": \"bafce976-8f33-437f-9c52-fb274456940f\",\n \"name\": \"My New New Construction Project.\",\n \"custom_id\": \"1234\",\n \"type\": \"general\",\n \"status\": \"bidding\",\n \"owner\": \"ACME\",\n \"start_date\": \"2001-10-01\",\n \"end_date\": \"2050-10-01\",\n \"street_1\": \"350 5th Avenue\",\n \"street_2\": null,\n \"city\": \"New York\",\n \"region\": \"New York\",\n \"postal_code\": \"10118\",\n \"country\": \"US\"\n}","language":"json","status":200},{"name":"Invalid Name","code":"{\n \"message\": \"Name (0) must be a string at least one character long.\"\n}","language":"json","status":400},{"status":400,"name":"Invalid Custom ID","code":"{\n \"message\": \"Custom ID must be null or a string at least one character long.\"\n}","language":"json"},{"language":"json","code":"{\n \"message\": \"Type (2) must be a valid project type.\"\n}","name":"Invalid Type","status":400},{"status":400,"language":"json","code":"{\n \"message\": \"Status must be null or a string at least one character long.\"\n}","name":"Invalid Status"},{"code":"{\n \"message\": \"Owner must be null or a string at least one character long.\"\n}","status":400,"name":"Invalid Owner","language":"json"},{"status":400,"name":"Invalid Start Date","language":"json","code":"{\n \"message\": \"Start date (1234) must be null or a date string in ISO-8601 format (YYYY-MM-DD).\"\n}"},{"status":400,"name":"Invalid End Date","language":"json","code":"{\n \"message\": \"End date (1234) must be null or a date string in ISO-8601 format (YYYY-MM-DD).\"\n}"},{"code":"{\n \"message\": \"Street 1 must be null or a string at least one character long.\"\n}","language":"json","name":"Invalid Street 1","status":400},{"name":"Invalid Street 2","status":400,"code":"{\n \"message\": \"Street 2 must be null or a string at least one character long.\"\n}","language":"json"},{"code":"{\n \"message\": \"City must be null or a string at least one character long.\"\n}","language":"json","name":"Invalid City","status":400},{"code":"{\n \"message\": \"Region must be null or a string at least one character long.\"\n}","language":"json","name":"Invalid Region","status":400},{"code":"{\n \"message\": \"Postal code must be null or a string at least one character long.\"\n}","language":"json","name":"Invalid Postal Code","status":400},{"status":400,"name":"Invalid Country","language":"json","code":"{\n \"message\": \"Country must be an ISO 3166 two letter country code.\"\n}"},{"code":"{\n \"message\": \"Insufficient permissions to update project fields (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","name":"Insufficient Permissions","status":403,"language":"json"}]},"auth":"required","params":[{"_id":"56edab5fc3628a170081effb","ref":"","in":"path","required":false,"desc":"Unique identifier of the project.","default":"","type":"string","name":"project_uid"},{"_id":"56edaad7fc1410200082dc5e","ref":"","in":"body","required":false,"desc":"New name of the project. Must be at least one character long.","default":"","type":"string","name":"name"},{"_id":"58ee7cb5bbf1611b00d95c38","ref":"","in":"body","required":false,"desc":"Project code.","default":"","type":"string","name":"custom_id"},{"_id":"58ee7cb5bbf1611b00d95c37","ref":"","in":"body","required":false,"desc":"Project type with possible values of `general`, `manufacturing`, `power`, `water-sewer-waste`, `industrial-petroleum`, `transportation`, `hazardous-waste`, `telecom`, `education-k-12`, `education-higher`, `gov-federal`, `gov-state-local`, or `other`.","default":"","type":"string","name":"type"},{"_id":"58ee7cb5bbf1611b00d95c36","ref":"","in":"body","required":false,"desc":"Project status.","default":"","type":"string","name":"status"},{"_id":"58ee7cb5bbf1611b00d95c35","ref":"","in":"body","required":false,"desc":"Project owner.","default":"","type":"string","name":"owner"},{"_id":"58ee7cb5bbf1611b00d95c34","ref":"","in":"body","required":false,"desc":"Project start date. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"string","name":"start_date"},{"_id":"58ee7cb5bbf1611b00d95c33","ref":"","in":"body","required":false,"desc":"Project end date. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"string","name":"end_date"},{"_id":"58ee7cb5bbf1611b00d95c32","ref":"","in":"body","required":false,"desc":"Project address, street line 1","default":"","type":"string","name":"street_1"},{"_id":"58ee7cb5bbf1611b00d95c31","ref":"","in":"body","required":false,"desc":"Project address, street line 2","default":"","type":"string","name":"street_2"},{"_id":"58ee7cb5bbf1611b00d95c30","ref":"","in":"body","required":false,"desc":"Project address town or city.","default":"","type":"string","name":"city"},{"_id":"58ee7cb5bbf1611b00d95c2f","ref":"","in":"body","required":false,"desc":"Project address state, province, or region.","default":"","type":"string","name":"region"},{"_id":"58ee7cb5bbf1611b00d95c2e","ref":"","in":"body","required":false,"desc":"Project address zip or postal code.","default":"","type":"string","name":"postal_code"},{"_id":"58ee7cb5bbf1611b00d95c2d","ref":"","in":"body","required":false,"desc":"Project address country in 2-letter ISO 3166 code.","default":"","type":"string","name":"country"}],"url":"/projects/:project_uid"},"isReference":false,"order":4,"body":"","excerpt":"Update a PlanGrid project","slug":"update-project","type":"patch","title":"Update Project","__v":0,"childrenPages":[]}
patchUpdate Project
Path Params
Body Params
Definition
Result Format
{
"uid": "bafce976-8f33-437f-9c52-fb274456940f",
"name": "My New New Construction Project.",
"custom_id": "1234",
"type": "general",
"status": "bidding",
"owner": "ACME",
"start_date": "2001-10-01",
"end_date": "2050-10-01",
"street_1": "350 5th Avenue",
"street_2": null,
"city": "New York",
"region": "New York",
"postal_code": "10118",
"country": "US"
}
{
"message": "Name (0) must be a string at least one character long."
}
{
"message": "Custom ID must be null or a string at least one character long."
}
{
"message": "Type (2) must be a valid project type."
}
{
"message": "Status must be null or a string at least one character long."
}
{
"message": "Owner must be null or a string at least one character long."
}
{
"message": "Start date (1234) must be null or a date string in ISO-8601 format (YYYY-MM-DD)."
}
{
"message": "End date (1234) must be null or a date string in ISO-8601 format (YYYY-MM-DD)."
}
{
"message": "Street 1 must be null or a string at least one character long."
}
{
"message": "Street 2 must be null or a string at least one character long."
}
{
"message": "City must be null or a string at least one character long."
}
{
"message": "Region must be null or a string at least one character long."
}
{
"message": "Postal code must be null or a string at least one character long."
}
{
"message": "Country must be an ISO 3166 two letter country code."
}
{
"message": "Insufficient permissions to update project fields (bafce976-8f33-437f-9c58-fb274456940f)."
}
{"_id":"5a0487c01058cd003cfb7ad7","category":"5a0487bf1058cd003cfb7aa2","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-01-12T19:19:52.839Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"language":"json","code":"{}","name":"","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"0-0\": \"**uid**\\n`string`\",\n \"0-1\": \"Unique identifier of the annotation. Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n \"1-0\": \"**color**\\n`string`\",\n \"1-1\": \"Color of the annotation in [hexadecimal format](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet).\",\n \"2-0\": \"**stamp**\\n`string`\",\n \"2-1\": \"One to two character stamp associated with the issue annotation. Usually indicates type of issue or trade associated with issue. May be `null` if the annotation is not associated with an issue.\",\n \"3-0\": \"**visibility**\\n`string`\",\n \"3-1\": \"Visibility level of annotation. Can be either `user` or `master`. `User` indicates a team member (or former team member) has not published the annotation to the project. Never blank.\",\n \"4-0\": \"**deleted**\\n`boolean`\",\n \"4-1\": \"Whether the annotation has been deleted. Never blank.\",\n \"5-0\": \"**sheet**\\n`object`\",\n \"5-1\": \"Reference to sheet the annotation is located on. See [Foreign Keys](doc:foreign-keys) for attribute details.\"\n },\n \"cols\": 2,\n \"rows\": 6\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"uid\\\": \\\"6994b73b-c3b4-4aa3-a985-fd973e599526\\\",\\n \\\"color\\\": \\\"#F38109\\\",\\n \\\"stamp\\\": \\\"CN\\\",\\n \\\"visibility\\\": \\\"master\\\",\\n \\\"deleted\\\": false,\\n \\\"sheet\\\": {\\n \\\"uid\\\": \\\"f3718ded-9919-4667-a746-969fda1cfe26\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26\\\"\\n }\\n}\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-annotation-object","type":"basic","title":"The Annotation Object","__v":0,"childrenPages":[]}
The Annotation Object
uidstring
Unique identifier of the annotation. Never blank. See Unique Identifiers for details.
colorstring
Color of the annotation in hexadecimal format.
stampstring
One to two character stamp associated with the issue annotation. Usually indicates type of issue or trade associated with issue. May be null
if the annotation is not associated with an issue.
visibilitystring
Visibility level of annotation. Can be either user
or master
. User
indicates a team member (or former team member) has not published the annotation to the project. Never blank.
deletedboolean
Whether the annotation has been deleted. Never blank.
sheetobject
Reference to sheet the annotation is located on. See Foreign Keys for attribute details.
{
"uid": "6994b73b-c3b4-4aa3-a985-fd973e599526",
"color": "#F38109",
"stamp": "CN",
"visibility": "master",
"deleted": false,
"sheet": {
"uid": "f3718ded-9919-4667-a746-969fda1cfe26",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26"
}
}
{"_id":"5a0487c01058cd003cfb7ad8","category":"5a0487bf1058cd003cfb7aa2","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-01-12T19:21:28.127Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"status":200,"language":"json","code":"{\n \"data\": [\n {\n \"stamp\": \"AC\",\n \"deleted\": false,\n \"visibility\": \"user\",\n \"sheet\": {\n \"url\": \"https://io.plangrid.com/projects/0d0f2b52-17e4-4a38-8cc4-eb22997e8a36/sheets/7a98fe15-1920-4848-b423-70185411bab8\",\n \"uid\": \"7a98fe15-1920-4848-b423-70185411bab8\"\n },\n \"uid\": \"236d134e-6a47-15c0-6649-b911c4f625d0\",\n \"color\": \"#FF0000\"\n },\n {\n \"stamp\": null,\n \"deleted\": false,\n \"visibility\": \"user\",\n \"sheet\": {\n \"url\": \"https://io.plangrid.com/projects/0d0f2b52-17e4-4a38-8cc4-eb22997e8a36/sheets/7a98fe15-1920-4848-b423-70185411bab8\",\n \"uid\": \"7a98fe15-1920-4848-b423-70185411bab8\"\n },\n \"uid\": \"5f9bec11-3ae9-d629-3afc-80176bfb7d33\",\n \"color\": \"#FF0000\"\n },\n {\n \"stamp\": null,\n \"deleted\": false,\n \"visibility\": \"user\",\n \"sheet\": {\n \"url\": \"https://io.plangrid.com/projects/0d0f2b52-17e4-4a38-8cc4-eb22997e8a36/sheets/7a98fe15-1920-4848-b423-70185411bab8\",\n \"uid\": \"7a98fe15-1920-4848-b423-70185411bab8\"\n },\n \"uid\": \"c2d2c99b-77dc-f26b-5706-4b9dfdc0d82f\",\n \"color\": \"#FF0000\"\n }\n ],\n \"total_count\": 50,\n \"next_page_url\": \"https://io.plangrid.com/projects/0d0f2b52-17e4-4a38-8cc4-eb22997e8a36/annotations?limit=50&skip=50\"\n}","name":""},{"language":"json","status":404,"code":"{ \"message\": \"Project (0d0f2b52-17e4-4a38-8cc4-eb22997e8a36) does not exist.\" }"},{"code":"{ \"message\": \"Project (0d0f2b52-17e4-4a38-8cc4-eb22997e8a36) does not exist.\" }","language":"json","status":403}]},"settings":"","auth":"required","params":[{"_id":"5877d77eb8e8fb1900608fd1","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"5877d8c0204d5439009d9fdc","ref":"","in":"query","required":false,"desc":"Number of annotations to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"5877d8c0204d5439009d9fdb","ref":"","in":"query","required":false,"desc":"Number of annotations to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"5877d8c0204d5439009d9fda","ref":"","in":"query","required":false,"desc":"Only retrieve annotations created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"datetime","name":"updated_after"}],"url":"/projects/:project_uid/annotations"},"isReference":false,"order":1,"body":"","excerpt":"Get a list of all annotations in a project. _All annotations_ inside a project are returned, including deleted, personal, and published annotations. Annotations are sorted by created at, most recent first. Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-annotations-in-a-project","type":"get","title":"Retrieve Annotations in a Project","__v":0,"childrenPages":[]}
getRetrieve Annotations in a Project
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"stamp": "AC",
"deleted": false,
"visibility": "user",
"sheet": {
"url": "https://io.plangrid.com/projects/0d0f2b52-17e4-4a38-8cc4-eb22997e8a36/sheets/7a98fe15-1920-4848-b423-70185411bab8",
"uid": "7a98fe15-1920-4848-b423-70185411bab8"
},
"uid": "236d134e-6a47-15c0-6649-b911c4f625d0",
"color": "#FF0000"
},
{
"stamp": null,
"deleted": false,
"visibility": "user",
"sheet": {
"url": "https://io.plangrid.com/projects/0d0f2b52-17e4-4a38-8cc4-eb22997e8a36/sheets/7a98fe15-1920-4848-b423-70185411bab8",
"uid": "7a98fe15-1920-4848-b423-70185411bab8"
},
"uid": "5f9bec11-3ae9-d629-3afc-80176bfb7d33",
"color": "#FF0000"
},
{
"stamp": null,
"deleted": false,
"visibility": "user",
"sheet": {
"url": "https://io.plangrid.com/projects/0d0f2b52-17e4-4a38-8cc4-eb22997e8a36/sheets/7a98fe15-1920-4848-b423-70185411bab8",
"uid": "7a98fe15-1920-4848-b423-70185411bab8"
},
"uid": "c2d2c99b-77dc-f26b-5706-4b9dfdc0d82f",
"color": "#FF0000"
}
],
"total_count": 50,
"next_page_url": "https://io.plangrid.com/projects/0d0f2b52-17e4-4a38-8cc4-eb22997e8a36/annotations?limit=50&skip=50"
}
{ "message": "Project (0d0f2b52-17e4-4a38-8cc4-eb22997e8a36) does not exist." }
{ "message": "Project (0d0f2b52-17e4-4a38-8cc4-eb22997e8a36) does not exist." }
{"_id":"5a0487c11058cd003cfb7afb","category":"5a0487bf1058cd003cfb7aa3","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-08-14T21:07:05.673Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:parameters]\n{\n \"data\": {\n \"0-0\": \"**uid**\\n`string`\",\n \"3-0\": \"**created_by**\\n`object`\",\n \"0-1\": \"Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n \"3-1\": \"Reference to PlanGrid user that created issue. Will always map to a real user. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"1-0\": \"**text**\\n`string`\",\n \"1-1\": \"-\",\n \"2-1\": \"When the comment was created by a client application. UTC date and time in ISO-8601 format.\",\n \"2-0\": \"**created_at**\\n`string`\",\n \"4-0\": \"**record_type**\\n`string`\",\n \"4-1\": \"Type of record the comment is for. Possible values are `project`, `issue`, `rfi`, and `sheet`.\",\n \"5-0\": \"**record**\\n`object`\",\n \"5-1\": \"Reference to record comment is for. See [Foreign Keys](doc:foreign-keys) for attribute details.\"\n },\n \"cols\": 2,\n \"rows\": 6\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"uid\\\": \\\"8510cfc9-2a82-4736-bf37-753c900d1c68\\\",\\n \\\"text\\\": \\\"You looking at me?\\\",\\n \\\"created_at\\\": \\\"2015-10-12T14:17:27+00:00\\\",\\n \\\"created_by\\\": {\\n \\\"uid\\\": \\\"10dd6d24-cbe2-4639-9647-f9d0cc4aaee8\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/10dd6d24-cbe2-4639-9647-f9d0cc4aaee8\\\",\\n \\\"email\\\": \\\"travis@subcontractor.com\\\" \\n },\\n \\\"record_type\\\": \\\"project\\\",\\n \\\"record\\\": {\\n \\\"uid\\\": \\\"bafce976-8f33-437f-9c52-fb274456940f\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f\\\",\\n }\\n}\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-comment-object","type":"basic","title":"The Comment Object","__v":0,"childrenPages":[]}
The Comment Object
uidstring
Never blank. See Unique Identifiers for details.
textstring
-
created_atstring
When the comment was created by a client application. UTC date and time in ISO-8601 format.
created_byobject
Reference to PlanGrid user that created issue. Will always map to a real user. See Foreign Keys for attribute details.
record_typestring
Type of record the comment is for. Possible values are project
, issue
, rfi
, and sheet
.
recordobject
Reference to record comment is for. See Foreign Keys for attribute details.
{
"uid": "8510cfc9-2a82-4736-bf37-753c900d1c68",
"text": "You looking at me?",
"created_at": "2015-10-12T14:17:27+00:00",
"created_by": {
"uid": "10dd6d24-cbe2-4639-9647-f9d0cc4aaee8",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/10dd6d24-cbe2-4639-9647-f9d0cc4aaee8",
"email": "travis@subcontractor.com"
},
"record_type": "project",
"record": {
"uid": "bafce976-8f33-437f-9c52-fb274456940f",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f",
}
}
{"_id":"5a0487c11058cd003cfb7afc","category":"5a0487bf1058cd003cfb7aa3","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-08-14T21:14:42.692Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"status":200,"language":"json","code":"{\n \"data\": [\n {\n \"uid\": \"87658a3f-8ee0-4188-9c55-b06a203fa9e7\",\n \"text\": \"Great Scott!\",\n \"created_at\": \"2013-05-17t02:30:22z\",\n \"created_by\": {\n \"uid\": \"deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n \"email\": \"doc@subcontractor.com\"\n },\n \"record_type\": \"project\",\n \"record\": {\n \"uid\": \"bafce976-8f33-437f-9c52-fb274456940f\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f\"\n }\n },\n {\n \"uid\": \"465abf98-accb-42cd-bd54-16f29e8447f2\",\n \"text\": \"Jesus, George, it was a wonder I was even born.\",\n \"created_at\": \"2013-05-15t18:54:22z\",\n \"created_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"marty@construction.com\"\n },\n \"record_type\": \"issue\",\n \"record\": {\n \"uid\": \"b9876ac1-369f-401b-8ca0-6f152b533895\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895\"\n }\n },\n {\n \"uid\": \"08ea8b05-a99c-40a7-a312-fee360ad432a\",\n \"text\": \"I'm sure that in 1985, plutonium is available in every corner drugstore, but in 1955, it's a little hard to come by.\",\n \"created_at\": \"2013-05-14t8:30:56z\",\n \"created_by\": {\n \"uid\": \"deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n \"email\": \"doc@subcontractor.com\"\n },\n \"record_type\": \"rfi\",\n \"record\": {\n \"uid\": \"c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\"\n }\n },\n {\n \"uid\": \"68839690-e0aa-4751-aedf-e630b921e91e\",\n \"text\": \"Look, Marvin, you gotta play. See, that's where they kiss for the first time on the dance floor. And if there's no music, they can't dance. If they can't dance, they can't kiss. If they can't kiss they can't fall in love, and I'm history.\",\n \"created_at\": \"2013-05-13t11:22:56z\",\n \"created_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"marty@construction.com\"\n },\n \"record_type\": \"rfi\",\n \"record\": {\n \"uid\": \"c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\"\n }\n }\n ],\n \"total_count\": 6,\n \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/comments?skip=4&limit=4\"\n}","name":"Success"},{"status":404,"language":"json","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}","name":"Project Missing"},{"name":"Invalid Record Type","status":400,"code":"{\n \"message\": \"Record type (1) must be a valid record type.\"\n}","language":"json"},{"code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}","language":"json","status":403,"name":"No Project Access"}]},"settings":"","auth":"required","params":[{"_id":"57b0e1de9ee0960e00440bbe","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"57b0e1de9ee0960e00440bbd","ref":"","in":"query","required":false,"desc":"Number of comments to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"57b0e1de9ee0960e00440bbc","ref":"","in":"query","required":false,"desc":"Number of comments to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"57b0e1de9ee0960e00440bbb","ref":"","in":"query","required":false,"desc":"Only retrieve comments created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"datetime","name":"updated_after"},{"_id":"57b0e2889ee0960e00440bbf","ref":"","in":"query","required":false,"desc":"Comma separate list of record types. Possible values are `project`, `issue`, `rfi`, `sheet`. Case insensitive and removes duplicates.","default":"","type":"string","name":"record_types"}],"url":"/projects/:project_uid/comments"},"isReference":false,"order":1,"body":"","excerpt":"Get a list of comments across all records in a project (most recently created first). Results are paginated and can optionally be filtered by record type, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-comments-in-a-project","type":"get","title":"Retrieve Comments in a Project","__v":0,"childrenPages":[]}
getRetrieve Comments in a Project
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"uid": "87658a3f-8ee0-4188-9c55-b06a203fa9e7",
"text": "Great Scott!",
"created_at": "2013-05-17t02:30:22z",
"created_by": {
"uid": "deae0b56-81c7-4a05-8e8b-410fd17a01f0",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0",
"email": "doc@subcontractor.com"
},
"record_type": "project",
"record": {
"uid": "bafce976-8f33-437f-9c52-fb274456940f",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f"
}
},
{
"uid": "465abf98-accb-42cd-bd54-16f29e8447f2",
"text": "Jesus, George, it was a wonder I was even born.",
"created_at": "2013-05-15t18:54:22z",
"created_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "marty@construction.com"
},
"record_type": "issue",
"record": {
"uid": "b9876ac1-369f-401b-8ca0-6f152b533895",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895"
}
},
{
"uid": "08ea8b05-a99c-40a7-a312-fee360ad432a",
"text": "I'm sure that in 1985, plutonium is available in every corner drugstore, but in 1955, it's a little hard to come by.",
"created_at": "2013-05-14t8:30:56z",
"created_by": {
"uid": "deae0b56-81c7-4a05-8e8b-410fd17a01f0",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0",
"email": "doc@subcontractor.com"
},
"record_type": "rfi",
"record": {
"uid": "c62d6a09-1e7c-4aa0-b60b-86249eba7e5b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b"
}
},
{
"uid": "68839690-e0aa-4751-aedf-e630b921e91e",
"text": "Look, Marvin, you gotta play. See, that's where they kiss for the first time on the dance floor. And if there's no music, they can't dance. If they can't dance, they can't kiss. If they can't kiss they can't fall in love, and I'm history.",
"created_at": "2013-05-13t11:22:56z",
"created_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "marty@construction.com"
},
"record_type": "rfi",
"record": {
"uid": "c62d6a09-1e7c-4aa0-b60b-86249eba7e5b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b"
}
}
],
"total_count": 6,
"next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/comments?skip=4&limit=4"
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Record type (1) must be a valid record type."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}
{"_id":"5a0487c01058cd003cfb7af3","category":"5a0487bf1058cd003cfb7aa4","parentDoc":null,"user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-10-23T22:54:15.916Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"language":"json","status":200,"name":"","code":"{}"},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:parameters]\n{\n \"data\": {\n \"0-0\": \"**uid**\\n`string`\",\n \"5-0\": \"**created_by**\\n`object`\",\n \"0-1\": \"Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n \"5-1\": \"Reference to PlanGrid user that created the document. In rare cases, this may not map to a real user. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"1-0\": \"**name**\\n`string`\",\n \"1-1\": \"-\",\n \"4-1\": \"When the document was created by a client application. UTC date and time in ISO-8601 format.\",\n \"4-0\": \"**created_at**\\n`string`\",\n \"6-0\": \"**deleted**\\n`boolean`\",\n \"6-1\": \"Whether the document has been deleted. Never blank.\",\n \"3-0\": \"**url**\\n`string`\",\n \"3-1\": \"URL to retrieve document file.\",\n \"2-0\": \"**folder**\\n`string`\",\n \"2-1\": \"Case-sensitive.\"\n },\n \"cols\": 2,\n \"rows\": 7\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"uid\\\": \\\"78128c72-5862-458a-9577-33eaa189a5c1\\\",\\n \\\"name\\\": \\\"Submittal.4.2.pdf\\\",\\n \\\"folder\\\": \\\"Submittals\\\",\\n \\\"url\\\": \\\"https://attachment-assets.plangrid.com/78128c72-5862-458a-9577-33eaa189a5c1.pdf\\\",\\n \\\"created_at\\\": \\\"2015-10-12T16:22:54+00:00\\\",\\n \\\"created_by\\\": {\\n \\\"uid\\\": \\\"d3bade89-01bf-4ea0-889e-d5dad2f56e7e\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d3bade89-01bf-4ea0-889e-d5dad2f56e7e\\\",\\n \\\"email\\\": \\\"patrick.peterson@subcontractor.com\\\" \\n },\\n \\\"deleted\\\": false\\n}\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-attachment-object","type":"basic","title":"The Document Object","__v":0,"childrenPages":[]}
The Document Object
uidstring
Never blank. See Unique Identifiers for details.
namestring
-
folderstring
Case-sensitive.
urlstring
URL to retrieve document file.
created_atstring
When the document was created by a client application. UTC date and time in ISO-8601 format.
created_byobject
Reference to PlanGrid user that created the document. In rare cases, this may not map to a real user. See Foreign Keys for attribute details.
deletedboolean
Whether the document has been deleted. Never blank.
{
"uid": "78128c72-5862-458a-9577-33eaa189a5c1",
"name": "Submittal.4.2.pdf",
"folder": "Submittals",
"url": "https://attachment-assets.plangrid.com/78128c72-5862-458a-9577-33eaa189a5c1.pdf",
"created_at": "2015-10-12T16:22:54+00:00",
"created_by": {
"uid": "d3bade89-01bf-4ea0-889e-d5dad2f56e7e",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d3bade89-01bf-4ea0-889e-d5dad2f56e7e",
"email": "patrick.peterson@subcontractor.com"
},
"deleted": false
}
{"_id":"5a0487c01058cd003cfb7af4","category":"5a0487bf1058cd003cfb7aa4","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55fc7da63c21291900e7e0a5","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-04-13T20:42:13.382Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"The following table lists supported file types for documents:\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Type of document\",\n \"h-1\": \"File extension\",\n \"0-0\": \"Image\",\n \"0-1\": \".png\\n.jpeg\\n.jpg\\n.gif\\n.bmp\",\n \"1-0\": \"Spreadsheet\",\n \"1-1\": \".xlsx\\n.xls\\n.csv\",\n \"2-0\": \"Open Document\",\n \"2-1\": \".rtf\\n.doc\\n.docx\\n.txt\\n.odf\",\n \"3-0\": \"Video\",\n \"3-1\": \".webm\\n.mpg\\n.mov\\n.f4v\\n.avi\\n.mp4\\n.wmv\",\n \"4-0\": \"Design\",\n \"4-1\": \".rvt\\n.dwg\\n.dxf\\n.dgn\\n.dwf\\n.dwfx\",\n \"5-0\": \"Google Earth\",\n \"5-1\": \".kmz\\n.kml\"\n },\n \"cols\": 2,\n \"rows\": 6\n}\n[/block]","excerpt":"","slug":"supported-file-types","type":"basic","title":"Supported File Types","__v":0,"childrenPages":[]}
Supported File Types
The following table lists supported file types for documents:
Image
.png
.jpeg
.jpg
.gif
.bmp
Spreadsheet
.xlsx
.xls
.csv
Open Document
.rtf
.doc
.docx
.txt
.odf
Video
.webm
.mpg
.mov
.f4v
.avi
.mp4
.wmv
Design
.rvt
.dwg
.dxf
.dgn
.dwf
.dwfx
Google Earth
.kmz
.kml
{"_id":"5a0487c01058cd003cfb7af5","category":"5a0487bf1058cd003cfb7aa4","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T20:45:43.733Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"post","results":{"codes":[{"status":201,"language":"json","code":"{\n \"uid\": \"022c132d-cdd0-48a1-8874-d4c9fd310ec8\",\n \"webhook_url\": \"https://io.plangrid.com/projects/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7/attachments/uploads/completions/8392cd3fbf2dfbf9fc539c8423a21201\",\n \"aws_post_form_arguments\": {\n \"action\": \"https://attachments.s3.amazonaws.com/\",\n \"fields\": [\n {\n \"name\": \"key\",\n \"value\": \"4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\\/1ab29ace-adfe-4ff0-b4bd-267ca612df9a_ff\"\n },\n {\n \"name\": \"AWSAccessKeyId\",\n \"value\": \"AKIAIWKPH7OCNIEE5GGQ\"\n },\n {\n \"name\": \"success_action_redirect\",\n \"value\": \"https:\\/\\/plangrid-c-api-dispatcher-test.herokuapp.com\\/projects\\/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\\/attachments\\/uploads\\/completions\\/1039b3921a93c7e74bdb3352779c2c6e\"\n },\n {\n \"name\": \"policy\",\n \"value\": \"eyJleHBpcmF0aW9uIjogIjIwMTUtMTItMjJUMjE6MTU6MTlaIiwKImNvbmRpdGlvbnMiOiBbeyJDb250ZW50LVR5cGUiOiAiYXBwbGljYXRpb24vcGRmIn0seyJidWNrZXQiOiAibG91cGUtdGVzdC1hdHRhY2gifSx7ImtleSI6ICI0ZDBmNGZmNi1iNGU3LWZiNDEtZWRiMi0xMzliMGZmZjllZjcvMWFiMjlhY2UtYWRmZS00ZmYwLWI0YmQtMjY3Y2E2MTJkZjlhX2ZmIn0seyJzdWNjZXNzX2FjdGlvbl9yZWRpcmVjdCI6ICJodHRwczovL3BsYW5ncmlkLWMtYXBpLWRpc3BhdGNoZXItdGVzdC5oZXJva3VhcHAuY29tL3YxL3Byb2plY3RzLzRkMGY0ZmY2LWI0ZTctZmI0MS1lZGIyLTEzOWIwZmZmOWVmNy9hdHRhY2htZW50cy91cGxvYWRzL2NvbXBsZXRpb25zLzEwMzliMzkyMWE5M2M3ZTc0YmRiMzM1Mjc3OWMyYzZlIn0seyJ4LWFtei1zdG9yYWdlLWNsYXNzIjogIlNUQU5EQVJEIn0seyJ4LWFtei1zZXJ2ZXItc2lkZS1lbmNyeXB0aW9uIjogIkFFUzI1NiJ9XX0=\"\n },\n {\n \"name\": \"signature\",\n \"value\": \"CztWq\\/9IU4hCaEiaw0P5IRYmh0g=\"\n },\n {\n \"name\": \"Content-Type\",\n \"value\": \"application\\/pdf\"\n },\n {\n \"name\": \"x-amz-storage-class\",\n \"value\": \"STANDARD\"\n },\n {\n \"name\": \"x-amz-server-side-encryption\",\n \"value\": \"AES256\"\n }\n ]\n }\n}\n","name":"Success"},{"name":"Unsupported Content Type","status":400,"language":"json","code":"{\n \"message\": \"Content type (application/msword) is not supported.\"\n}\n"},{"code":"{\n \"message\": \"Content type (application/msword) is not supported.\"\n}\n","name":"Content Type Missing","status":400,"language":"json"},{"language":"json","code":"{\n \"message\": \"Name (null) must be a string at least one character long.\"\n}\n","name":"Invalid Name","status":400},{"code":"{\n \"message\": \"Folder (2) must be null or a string at least one character long.\"\n}\n","name":"Invalid Folder","status":400,"language":"json"},{"language":"json","code":"{\n \"message\": \"Insufficient permissions to upload attachments to project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"Insufficient Permissions","status":403},{"code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","name":"No Access","status":403,"language":"json"}]},"settings":"","auth":"required","params":[{"_id":"56cf1ec95267d70b00494b97","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ec95267d70b00494b96","ref":"","in":"body","required":true,"desc":"Content type of the document's file.","default":"","type":"string","name":"content_type"},{"_id":"56cf1ec95267d70b00494b95","ref":"","in":"body","required":true,"desc":"Name of the document.","default":"","type":"string","name":"name"},{"_id":"56cf1ec95267d70b00494b94","ref":"","in":"body","required":false,"desc":"Folder in project to place the document (case-sensitive).","default":"","type":"string","name":"folder"}],"url":"/projects/:project_uid/attachments/uploads"},"isReference":false,"order":2,"body":"","excerpt":"First of three step process for uploading a document to a project. On success, necessary information for step two and three is returned. The document record is not created until all three steps are completed. See [File Uploads](doc:file-uploads) for details.","slug":"upload-attachment-to-project","type":"post","title":"Upload Document to Project","__v":0,"childrenPages":[]}
postUpload Document to Project
Path Params
Body Params
Definition
Result Format
{
"uid": "022c132d-cdd0-48a1-8874-d4c9fd310ec8",
"webhook_url": "https://io.plangrid.com/projects/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7/attachments/uploads/completions/8392cd3fbf2dfbf9fc539c8423a21201",
"aws_post_form_arguments": {
"action": "https://attachments.s3.amazonaws.com/",
"fields": [
{
"name": "key",
"value": "4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\/1ab29ace-adfe-4ff0-b4bd-267ca612df9a_ff"
},
{
"name": "AWSAccessKeyId",
"value": "AKIAIWKPH7OCNIEE5GGQ"
},
{
"name": "success_action_redirect",
"value": "https:\/\/plangrid-c-api-dispatcher-test.herokuapp.com\/projects\/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\/attachments\/uploads\/completions\/1039b3921a93c7e74bdb3352779c2c6e"
},
{
"name": "policy",
"value": "eyJleHBpcmF0aW9uIjogIjIwMTUtMTItMjJUMjE6MTU6MTlaIiwKImNvbmRpdGlvbnMiOiBbeyJDb250ZW50LVR5cGUiOiAiYXBwbGljYXRpb24vcGRmIn0seyJidWNrZXQiOiAibG91cGUtdGVzdC1hdHRhY2gifSx7ImtleSI6ICI0ZDBmNGZmNi1iNGU3LWZiNDEtZWRiMi0xMzliMGZmZjllZjcvMWFiMjlhY2UtYWRmZS00ZmYwLWI0YmQtMjY3Y2E2MTJkZjlhX2ZmIn0seyJzdWNjZXNzX2FjdGlvbl9yZWRpcmVjdCI6ICJodHRwczovL3BsYW5ncmlkLWMtYXBpLWRpc3BhdGNoZXItdGVzdC5oZXJva3VhcHAuY29tL3YxL3Byb2plY3RzLzRkMGY0ZmY2LWI0ZTctZmI0MS1lZGIyLTEzOWIwZmZmOWVmNy9hdHRhY2htZW50cy91cGxvYWRzL2NvbXBsZXRpb25zLzEwMzliMzkyMWE5M2M3ZTc0YmRiMzM1Mjc3OWMyYzZlIn0seyJ4LWFtei1zdG9yYWdlLWNsYXNzIjogIlNUQU5EQVJEIn0seyJ4LWFtei1zZXJ2ZXItc2lkZS1lbmNyeXB0aW9uIjogIkFFUzI1NiJ9XX0="
},
{
"name": "signature",
"value": "CztWq\/9IU4hCaEiaw0P5IRYmh0g="
},
{
"name": "Content-Type",
"value": "application\/pdf"
},
{
"name": "x-amz-storage-class",
"value": "STANDARD"
},
{
"name": "x-amz-server-side-encryption",
"value": "AES256"
}
]
}
}
{
"message": "Content type (application/msword) is not supported."
}
{
"message": "Content type (application/msword) is not supported."
}
{
"message": "Name (null) must be a string at least one character long."
}
{
"message": "Folder (2) must be null or a string at least one character long."
}
{
"message": "Insufficient permissions to upload attachments to project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{"_id":"5a0487c01058cd003cfb7af6","category":"5a0487bf1058cd003cfb7aa4","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:01:57.154Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"language":"json","code":"{\n \"uid\": \"147a420e-a182-4312-8fa5-4d10064d2f1a\",\n \"name\": \"Bender\",\n \"folder\": \"Specifications\",\n \"url\": \"https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf\",\n \"created_at\": \"2013-05-17T02:30:22+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"nick@subcontractor.com\"\n },\n \"deleted\": false\n}\n","name":"Success","status":201},{"language":"json","code":"{\n \"message\": \"File associated with upload token (8392cd3fbf2dfbf9fc539c8423a21201) is missing.\"\n}\n","name":"File Missing","status":400},{"language":"json","code":"{\n \"message\": \"Attachment for upload token (8392cd3fbf2dfbf9fc539c8423a21201) does not exist\"\n}\n","name":"Upload Token Missing","status":404},{"language":"json","code":"{\n \"message\": \"Upload token (8392cd3fbf2dfbf9fc539c8423a21201) expired.\"\n}","name":"Upload Token Expired","status":410},{"language":"json","code":"{\n \"message\": \"Sorry, PlanGrid was unable to complete the upload. Use the url included with this message to try again.\"\n \"url\": \"https://io.plangrid.com/v1/projects/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7/attachments/uploads/completions/8392cd3fbf2dfbf9fc539c8423a21201\"\n}\n","name":"Server Error","status":500},{"status":409,"code":"{\n \"message\": \"Upload token (8392cd3fbf2dfbf9fc539c8423a21201) consumed.\"\n}","language":"json"}]},"settings":"","auth":"required","params":[{"_id":"56cf1ec85267d70b00494b8d","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ec85267d70b00494b8c","ref":"","in":"path","required":true,"desc":"Token that uniquely identifies the upload.","default":"","type":"string","name":"upload_token"}],"url":"/projects/:project_uid/attachments/uploads/completions/:upload_token"},"isReference":false,"order":3,"body":"","excerpt":"Last of three step process for uploading a document to a project. On success, the new document record is created and returned. This step is handled automatically with appropriate configuration. See [File Uploads](doc:file-uploads) for details.","slug":"complete-attachment-upload-to-project","type":"get","title":"Complete Document Upload to Project","__v":0,"childrenPages":[]}
getComplete Document Upload to Project
Path Params
Definition
Result Format
{
"uid": "147a420e-a182-4312-8fa5-4d10064d2f1a",
"name": "Bender",
"folder": "Specifications",
"url": "https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf",
"created_at": "2013-05-17T02:30:22+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "nick@subcontractor.com"
},
"deleted": false
}
{
"message": "File associated with upload token (8392cd3fbf2dfbf9fc539c8423a21201) is missing."
}
{
"message": "Attachment for upload token (8392cd3fbf2dfbf9fc539c8423a21201) does not exist"
}
{
"message": "Upload token (8392cd3fbf2dfbf9fc539c8423a21201) expired."
}
{
"message": "Sorry, PlanGrid was unable to complete the upload. Use the url included with this message to try again."
"url": "https://io.plangrid.com/v1/projects/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7/attachments/uploads/completions/8392cd3fbf2dfbf9fc539c8423a21201"
}
{
"message": "Upload token (8392cd3fbf2dfbf9fc539c8423a21201) consumed."
}
{"_id":"5a0487c01058cd003cfb7af7","category":"5a0487bf1058cd003cfb7aa4","parentDoc":null,"user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T20:43:49.034Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"name":"Success","code":"{\n \"data\": [\n {\n \"uid\": \"147a420e-a182-4312-8fa5-4d10064d2f1a\",\n \"name\": \"Bender\",\n \"folder\": \"Specifications\",\n \"url\": \"https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf\",\n \"created_at\": \"2013-05-17T02:30:22+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"nick@subcontractor.com\"\n },\n \"deleted\": false\n },\n {\n \"uid\": \"40f38b8b-019e-44d8-8cb8-86454c327fb5\",\n \"name\": \"Cement\",\n \"folder\": \"Submittals\",\n \"url\": \"https://attachment-assets.plangrid.com/40f38b8b-019e-44d8-8cb8-86454c327fb5.pdf\",\n \"created_at\": \"2013-05-13T04:30:22+00:00\",\n \"created_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"betty@construction.com\"\n },\n \"deleted\": true\n }\n ],\n \"total_count\": 14,\n \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/attachments?skip=2&limit=2\"\n}\n","language":"json","status":200},{"status":404,"name":"Project Missing","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","language":"json"},{"name":"No Project Access","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","language":"json","status":403}]},"settings":"","auth":"required","params":[{"_id":"56cf1ec95267d70b00494b93","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ec95267d70b00494b92","ref":"","in":"query","required":false,"desc":"Folder to filter results by (case-sensitive). Empty string retrieves all documents where folder is `null` or `\"\"`.","default":"","type":"string","name":"folder"},{"_id":"56cf1ec95267d70b00494b91","ref":"","in":"query","required":false,"desc":"Number of documents to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ec95267d70b00494b90","ref":"","in":"query","required":false,"desc":"Number of documents to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"56edba05949cc2320083727b","ref":"","in":"query","required":false,"desc":"Only retrieve documents created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"datetime","name":"updated_after"}],"url":"/projects/:project_uid/attachments"},"isReference":false,"order":4,"body":"","excerpt":"Get a list of documents in a project optionally filtered by folder. Results return deleted documents and are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-attachments-in-a-project","type":"get","title":"Retrieve Documents in a Project","__v":0,"childrenPages":[]}
getRetrieve Documents in a Project
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"uid": "147a420e-a182-4312-8fa5-4d10064d2f1a",
"name": "Bender",
"folder": "Specifications",
"url": "https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf",
"created_at": "2013-05-17T02:30:22+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "nick@subcontractor.com"
},
"deleted": false
},
{
"uid": "40f38b8b-019e-44d8-8cb8-86454c327fb5",
"name": "Cement",
"folder": "Submittals",
"url": "https://attachment-assets.plangrid.com/40f38b8b-019e-44d8-8cb8-86454c327fb5.pdf",
"created_at": "2013-05-13T04:30:22+00:00",
"created_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "betty@construction.com"
},
"deleted": true
}
],
"total_count": 14,
"next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/attachments?skip=2&limit=2"
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{"_id":"5a0487c01058cd003cfb7af8","category":"5a0487bf1058cd003cfb7aa4","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T20:44:42.129Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"code":"{\n \"uid\": \"147a420e-a182-4312-8fa5-4d10064d2f1a\",\n \"name\": \"Bender\",\n \"folder\": \"Specifications\",\n \"url\": \"https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf\",\n \"created_at\": \"2013-05-17T02:30:22+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"nick@subcontractor.com\"\n },\n \"deleted\": false\n}\n","language":"json","status":200,"name":"Success"},{"status":404,"name":"Project Missing","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","language":"json"},{"status":404,"name":"Document Missing","code":"{\n \"message\": \"Attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","language":"json"},{"status":403,"name":"No Project Access","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","language":"json"}]},"settings":"","auth":"required","params":[{"_id":"56cf1ec85267d70b00494b8f","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ec85267d70b00494b8e","ref":"","in":"path","required":true,"desc":"Unique identifier of document.","default":"","type":"string","name":"attachment_uid"}],"url":"/projects/:project_uid/attachments/:attachment_uid"},"isReference":false,"order":5,"body":"","excerpt":"Get a document in a project.","slug":"retrieve-attachment-in-a-project","type":"get","title":"Retrieve Document in a Project","__v":0,"childrenPages":[]}
getRetrieve Document in a Project
Path Params
Definition
Result Format
{
"uid": "147a420e-a182-4312-8fa5-4d10064d2f1a",
"name": "Bender",
"folder": "Specifications",
"url": "https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf",
"created_at": "2013-05-17T02:30:22+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "nick@subcontractor.com"
},
"deleted": false
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{"_id":"5a0487c01058cd003cfb7af9","category":"5a0487bf1058cd003cfb7aa4","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-20T22:42:40.912Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"name":"Success","code":"{\n \"uid\": \"147a420e-a182-4312-8fa5-4d10064d2f1a\",\n \"name\": \"Bender\",\n \"folder\": \"Specifications\",\n \"url\": \"https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf\",\n \"created_at\": \"2013-05-17T02:30:22+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"nick@subcontractor.com\"\n },\n \"deleted\": false\n}\n","language":"json"},{"language":"json","status":400,"name":"Invalid Name","code":"{\n \"message\": \"Name (null) must be a string at least one character long.\"\n}"},{"status":400,"name":"Invalid Folder","code":"{\n \"message\": \"Folder (2) must be null or a string at least one character long.\"\n}","language":"json"},{"code":"{\n \"message\": \"Insufficient permissions to update attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) in project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","language":"json","status":403,"name":"Insufficient Permissions"},{"name":"No Access","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}","language":"json","status":403},{"code":"{\n \"message\": \"Attachment (baa813cf-fd44-4a9c-be2b-62669958cc9a) is deleted and cannot be updated.\"\n}","language":"json","status":400},{"code":"{\n \"message\": \"Attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) was not found in project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","language":"json","status":404,"name":"Document Missing"},{"status":404,"name":"Project Missing","language":"json","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}"}]},"settings":"","examples":{"codes":[]},"method":"patch","auth":"required","params":[{"_id":"56cf1ec95267d70b00494b97","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ec95267d70b00494b96","ref":"","in":"body","required":true,"desc":"Unique identifier of document.","default":"","type":"string","name":"attachmend_uid"},{"_id":"56cf1ec95267d70b00494b95","ref":"","in":"body","required":false,"desc":"New name of the document.","default":"","type":"string","name":"name"},{"_id":"56cf1ec95267d70b00494b94","ref":"","in":"body","required":false,"desc":"New folder in project to place the document (case-sensitive).","default":"","type":"string","name":"folder"}],"url":"/projects/:project_uid/attachments/:attachment_uid"},"isReference":false,"order":6,"body":"","excerpt":"Update a document's metadata. If you want to change the document's file, you'll need to delete the document and upload a new one.","slug":"update-attachment-in-a-project","type":"patch","title":"Update Document in a Project","__v":0,"childrenPages":[]}
patchUpdate Document in a Project
Path Params
Body Params
Definition
Result Format
{
"uid": "147a420e-a182-4312-8fa5-4d10064d2f1a",
"name": "Bender",
"folder": "Specifications",
"url": "https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf",
"created_at": "2013-05-17T02:30:22+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "nick@subcontractor.com"
},
"deleted": false
}
{
"message": "Name (null) must be a string at least one character long."
}
{
"message": "Folder (2) must be null or a string at least one character long."
}
{
"message": "Insufficient permissions to update attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) in project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{
"message": "Attachment (baa813cf-fd44-4a9c-be2b-62669958cc9a) is deleted and cannot be updated."
}
{
"message": "Attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) was not found in project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{"_id":"5a0487c01058cd003cfb7afa","category":"5a0487bf1058cd003cfb7aa4","user":"55d201fe945e481700afbb19","parentDoc":null,"project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-20T22:27:21.230Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"delete","results":{"codes":[{"language":"json","status":204,"name":"","code":" "},{"code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}","language":"json","status":404,"name":"Project Missing"},{"name":"Attachment Missing","status":404,"code":"{\n \"message\": \"Attachment (87658a3f-8ee0-4188-9c55-b06a203fa9e7) was not found in project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","language":"json"},{"language":"json","status":403,"name":"No Project Access","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}"}]},"settings":"","auth":"required","params":[{"_id":"56ef222ba5bcfd0e00951766","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56ef2236aff1620e00a32356","ref":"","in":"path","required":true,"desc":"Unique identifier of document.","default":"","type":"string","name":"attachment_uid"}],"url":"/projects/:project_uid/attachments/:attachment_uid"},"isReference":false,"order":7,"body":"","excerpt":"Removes a document from a project. If document has already been removed, a `204` is still returned. See [Deleted Records](doc:deleted-records) for details on deleted records.","slug":"remove-attachment-from-project","type":"delete","title":"Remove Document from Project","__v":1,"childrenPages":[]}
deleteRemove Document from Project
Path Params
Definition
Result Format
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Attachment (87658a3f-8ee0-4188-9c55-b06a203fa9e7) was not found in project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}
{"_id":"5a0487c11058cd003cfb7b12","category":"5a0487bf1058cd003cfb7aa5","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-28T06:57:39.713Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"name":"","code":"{}","language":"json"},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Sheet Versions & Annotations\"\n}\n[/block]\nMultiple versions of the same sheet can exist in PlanGrid. As new versions of a sheet are uploaded, the annotations on old versions are copied to the newer version. We’ll illustrate how this is represented in PlanGrid’s data model via a simple example. Say you upload the first version of a sheet (“Version 1”); a Sheet record is created in PlanGrid with `sheet.version_name` set to “Version 1”:\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/CdUUaxKQwi24DmpR6KjD_1.png\",\n \"1.png\",\n \"2438\",\n \"451\",\n \"#c7c7c7\",\n \"\"\n ]\n }\n ]\n}\n[/block]\nSometime later you upload the second version of a sheet (“Version 2”). A second Sheet record is created in PlanGrid with `sheet.version_name` set to “Version 2”:\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/QVxkrdfxQGy9ILZd7kSL_2.png\",\n \"2.png\",\n \"2438\",\n \"451\",\n \"#cdcdcd\",\n \"\"\n ]\n }\n ]\n}\n[/block]\nYou add an annotation to the second version of the sheet. This creates an Annotation record that points to the second version Sheet record (via a foreign key for the Sheet `uid`):\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/fiqwlVJoS4iWroprHM9R_3.png\",\n \"3.png\",\n \"2438\",\n \"451\",\n \"#9c9c9c\",\n \"\"\n ]\n }\n ]\n}\n[/block]\nWhen you upload the third version of a sheet (“Version 3”), the annotation is copied from “Version 2”. In our data model, a new Sheet record is created (with `sheet.version_name` set to “Version 3”), the Annotation record is copied, and the copy points to the third version Sheet Record:\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/EbQKdX80SkC6REHl0Nrq_4.png\",\n \"4.png\",\n \"2438\",\n \"451\",\n \"#9e9e9e\",\n \"\"\n ]\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Issues and Annotations\"\n}\n[/block]\nWhen an issue is placed on a sheet, the PlanGrid data model creates an Issue record *and* an Annotation record. The annotation stores information on where and how to display the issue on the sheet. As new versions of a sheet are uploaded, multiple annotations are created:\n[block:image]\n{\n \"images\": [\n {\n \"image\": [\n \"https://files.readme.io/YVK4B3p1TIqcHDNkvp4F_5.png\",\n \"5.png\",\n \"1313\",\n \"392\",\n \"#c7c7c7\",\n \"\"\n ]\n }\n ]\n}\n[/block]\nAs a convenience, we include the most current annotation on any issue record returned through the PlanGrid API.","excerpt":"","slug":"sheet-versions-annotations","type":"basic","title":"Background","__v":0,"childrenPages":[]}
Background
Multiple versions of the same sheet can exist in PlanGrid. As new versions of a sheet are uploaded, the annotations on old versions are copied to the newer version. We’ll illustrate how this is represented in PlanGrid’s data model via a simple example. Say you upload the first version of a sheet (“Version 1”); a Sheet record is created in PlanGrid with sheet.version_name
set to “Version 1”:
Sometime later you upload the second version of a sheet (“Version 2”). A second Sheet record is created in PlanGrid with sheet.version_name
set to “Version 2”:
You add an annotation to the second version of the sheet. This creates an Annotation record that points to the second version Sheet record (via a foreign key for the Sheet uid
):
When you upload the third version of a sheet (“Version 3”), the annotation is copied from “Version 2”. In our data model, a new Sheet record is created (with sheet.version_name
set to “Version 3”), the Annotation record is copied, and the copy points to the third version Sheet Record:
When an issue is placed on a sheet, the PlanGrid data model creates an Issue record and an Annotation record. The annotation stores information on where and how to display the issue on the sheet. As new versions of a sheet are uploaded, multiple annotations are created:
As a convenience, we include the most current annotation on any issue record returned through the PlanGrid API.
{"_id":"5a0487c11058cd003cfb7b13","category":"5a0487bf1058cd003cfb7aa5","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-09-27T22:03:27.758Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"name":"","code":"{}","language":"json"},{"language":"json","status":400,"name":"","code":"{}"}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"[block:parameters]\n{\n \"data\": {\n \"0-0\": \"**uid**\\n`string`\",\n \"0-1\": \"Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n \"1-0\": \"**number**\\n`integer`\",\n \"3-0\": \"**current_annotation**\\n`object`\",\n \"4-0\": \"**current_annotation.uid**\\n`string`\",\n \"5-0\": \"**current_annotation.color**\\n`string`\",\n \"6-0\": \"**current_annotation.stamp**\\n`string`\",\n \"7-0\": \"**current_annotation.visibility**\\n`string`\",\n \"8-0\": \"**current_annotation.deleted**\\n`boolean`\",\n \"9-0\": \"**current_annotation.sheet**\\n`object`\",\n \"10-0\": \"**room**\\n`string`\",\n \"12-0\": \"**description**\\n`string`\",\n \"13-0\": \"**assigned_to**\\n`array`\",\n \"14-0\": \"**status**\\n`string`\",\n \"15-0\": \"**created_at**\\n`string`\",\n \"16-0\": \"**created_by**\\n`object`\",\n \"17-0\": \"**updated_at**\\n`string`\",\n \"18-0\": \"**updated_by**\\n`object`\",\n \"27-0\": \"**deleted**\\n`boolean`\",\n \"1-1\": \"Issue number assigned by PlanGrid. May not be unique. Never blank.\",\n \"3-1\": \"Associated annotation that exists on most recent version. May not be current set. In rare cases, may be blank.\",\n \"4-1\": \"Unique identifier of the annotation. Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n \"5-1\": \"Color of the annotation in [hexadecimal format](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet).\",\n \"6-1\": \"One to two character stamp associated with issue. Usually indicates type of issue or trade associated with issue.\",\n \"7-1\": \"Visibility level of issue. Can be either `user` or `master`. `User` indicates a team member (or former team member) has not published the issue to the project. Never blank.\",\n \"8-1\": \"Whether the annotation has been deleted. Never blank.\",\n \"9-1\": \"Reference to sheet the current annotation is located on. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"10-1\": \"Room or location of issue. May be `null`.\",\n \"12-1\": \"The description of the issue. May be `null`.\",\n \"13-1\": \"An array of users that the issue is assigned to. Currently only supports one user. Does not have to be a real PlanGrid user. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"14-1\": \"Current status of issue. Possible values are \\\"open\\\", \\\"in_review\\\", \\\"pending\\\", \\\"closed\\\".\",\n \"15-1\": \"When the issue was created by a client application. UTC date and time in ISO-8601 format.\",\n \"16-1\": \"Reference to PlanGrid user that created issue. In rare cases, this may not map to a real user. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"17-1\": \"When the issue was updated by a PlanGrid client. Publishing, moving issue on sheet, modifying photos, or adding comments *will not affect* updated_at. UTC date and time in ISO-8601 format.\",\n \"18-1\": \"Reference to PlanGrid user that last updated issue. In rare cases, this may not map to a real user. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"27-1\": \"Whether the issue has been deleted. Never blank.\",\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"19-0\": \"**photos**\\n`object`\",\n \"20-0\": \"**comments**\\n`object`\",\n \"19-1\": \"Reference to collection of photos on issue. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"20-1\": \"Reference to collection of comments on issue. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"11-0\": \"**title**\\n`string`\",\n \"11-1\": \"The title of the issue. May be `null`.\",\n \"21-0\": \"**due_at**\\n`string`\",\n \"21-1\": \"When the Issue is due. UTC date and time in ISO-8601 format. May be `null`.\",\n \"22-0\": \"**has_cost_impact**\\n`boolean`\",\n \"22-1\": \"Whether the Issue has a cost impact. Never blank.\",\n \"23-0\": \"**cost_impact**\\n`decimal`\",\n \"23-1\": \"What the Issue's cost impact with accuracy to hundredths of a cent. May be `null`.\",\n \"24-0\": \"**currency_code**\\n`string`\",\n \"24-1\": \"The ISO-4217 currency code of the `cost_impact`. Currently only supports `USD`. May be `null` if `cost_impact` is not specified.\",\n \"25-0\": \"**has_schedule_impact**\\n`boolean`\",\n \"25-1\": \"Whether the Issue has a schedule impact. Never blank.\",\n \"26-0\": \"**schedule_impact**\\n`integer`\",\n \"26-1\": \"What the Issue's schedule impact is in seconds. May be `null`.\",\n \"2-0\": \"**issue_list**\\n`object`\",\n \"2-1\": \"Reference to issue list. See [Foreign Keys](doc:foreign-keys) for attribute details. May be `null` if not assigned to an issue list.\"\n },\n \"cols\": 2,\n \"rows\": 28\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"uid\\\": \\\"22f3530a-a00b-42f9-8139-3a7554c77c27\\\",\\n \\\"number\\\": 1,\\n \\\"issue_list\\\": {\\n \\\"uid\\\": \\\"9a11e2d8-9449-46e6-881d-09cb2d0ec90c\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/11a2b248-fbf5-439e-ab49-34adef8875f8/issue_lists/9a11e2d8-9449-46e6-881d-09cb2d0ec90c\\\"\\n },\\n \\\"current_annotation\\\": {\\n \\\"uid\\\": \\\"6994b73b-c3b4-4aa3-a985-fd973e599526\\\",\\n \\\"color\\\": \\\"#F38109\\\",\\n \\\"stamp\\\": \\\"E\\\",\\n \\\"visibility\\\": \\\"master\\\",\\n \\\"deleted\\\": false,\\n \\\"sheet\\\": {\\n \\\"uid\\\": \\\"f3718ded-9919-4667-a746-969fda1cfe26\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26\\\"\\n }\\n },\\n \\\"title\\\": \\\"Electrical\\\",\\n \\\"room\\\": \\\"M100\\\",\\n \\\"description\\\": \\\"Missing wall outlets.\\\",\\n \\\"assigned_to\\\": [{\\n \\\"uid\\\": \\\"80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\\\", \\n \\\"email\\\": \\\"bob@subcontractor.com\\\"\\n }],\\n \\\"status\\\": \\\"open\\\",\\n \\\"created_at\\\": \\\"2015-06-08T18:04:02+00:00\\\",\\n \\\"created_by\\\": {\\n \\\"uid\\\": null,\\n \\\"url\\\": null,\\n \\\"email\\\": \\\"alfred@architect.com\\\"\\n },\\n \\\"updated_at\\\": \\\"2013-05-23T19:22:56+00:00\\\",\\n \\\"updated_by\\\": {\\n \\\"uid\\\": null,\\n \\\"url\\\": null,\\n \\\"email\\\": \\\"betty@construction.com\\\"\\n },\\n \\\"photos\\\": {\\n \\\"total_count\\\": 1,\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/22f3530a-a00b-42f9-8139-3a7554c77c27/photos\\\"\\n },\\n \\\"comments\\\": {\\n \\\"total_count\\\": 0,\\n \\\"url\\\": null\\n },\\n \\\"due_at\\\": \\\"2016-10-31T15:32:26+00:00\\\",\\n \\\"has_cost_impact\\\": true,\\n \\\"cost_impact\\\": 25850.10,\\n \\\"currency_code\\\": \\\"USD\\\",\\n \\\"has_schedule_impact\\\": true,\\n \\\"schedule_impact\\\": 186400,\\n \\\"deleted\\\": false\\n}\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]\n\n[block:api-header]\n{\n \"type\": \"basic\",\n \"title\": \"Archived Issues\"\n}\n[/block]\nWhen an issue is archived through the PlanGrid client apps, it is hidden on the sheet but visible in the issue log. An issue is represented through the PlanGrid API as an issue whose `deleted` value is `false` and whose `current_annotation.deleted` is `true`.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"deleted\\\": false,\\n \\\"current_annotation\\\": {\\n \\\"deleted\\\": true,\\n \\\"sheet\\\": {\\n ...\\n }\\n ...\\n },\\n ...\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]","excerpt":"","slug":"the-issue-object","type":"basic","title":"The Issue Object","__v":0,"childrenPages":[]}
The Issue Object
uidstring
Never blank. See Unique Identifiers for details.
numberinteger
Issue number assigned by PlanGrid. May not be unique. Never blank.
issue_listobject
Reference to issue list. See Foreign Keys for attribute details. May be null
if not assigned to an issue list.
current_annotationobject
Associated annotation that exists on most recent version. May not be current set. In rare cases, may be blank.
current_annotation.uidstring
Unique identifier of the annotation. Never blank. See Unique Identifiers for details.
current_annotation.colorstring
Color of the annotation in hexadecimal format.
current_annotation.stampstring
One to two character stamp associated with issue. Usually indicates type of issue or trade associated with issue.
current_annotation.visibilitystring
Visibility level of issue. Can be either user
or master
. User
indicates a team member (or former team member) has not published the issue to the project. Never blank.
current_annotation.deletedboolean
Whether the annotation has been deleted. Never blank.
current_annotation.sheetobject
Reference to sheet the current annotation is located on. See Foreign Keys for attribute details.
roomstring
Room or location of issue. May be null
.
titlestring
The title of the issue. May be null
.
descriptionstring
The description of the issue. May be null
.
assigned_toarray
An array of users that the issue is assigned to. Currently only supports one user. Does not have to be a real PlanGrid user. See Foreign Keys for attribute details.
statusstring
Current status of issue. Possible values are "open", "in_review", "pending", "closed".
created_atstring
When the issue was created by a client application. UTC date and time in ISO-8601 format.
created_byobject
Reference to PlanGrid user that created issue. In rare cases, this may not map to a real user. See Foreign Keys for attribute details.
updated_atstring
When the issue was updated by a PlanGrid client. Publishing, moving issue on sheet, modifying photos, or adding comments will not affect updated_at. UTC date and time in ISO-8601 format.
updated_byobject
Reference to PlanGrid user that last updated issue. In rare cases, this may not map to a real user. See Foreign Keys for attribute details.
photosobject
Reference to collection of photos on issue. See Foreign Keys for attribute details.
commentsobject
Reference to collection of comments on issue. See Foreign Keys for attribute details.
due_atstring
When the Issue is due. UTC date and time in ISO-8601 format. May be null
.
has_cost_impactboolean
Whether the Issue has a cost impact. Never blank.
cost_impactdecimal
What the Issue's cost impact with accuracy to hundredths of a cent. May be null
.
currency_codestring
The ISO-4217 currency code of the cost_impact
. Currently only supports USD
. May be null
if cost_impact
is not specified.
has_schedule_impactboolean
Whether the Issue has a schedule impact. Never blank.
schedule_impactinteger
What the Issue's schedule impact is in seconds. May be null
.
deletedboolean
Whether the issue has been deleted. Never blank.
When an issue is archived through the PlanGrid client apps, it is hidden on the sheet but visible in the issue log. An issue is represented through the PlanGrid API as an issue whose deleted
value is false
and whose current_annotation.deleted
is true
.
{
"deleted": false,
"current_annotation": {
"deleted": true,
"sheet": {
}
},
}
{
"uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
"number": 1,
"issue_list": {
"uid": "9a11e2d8-9449-46e6-881d-09cb2d0ec90c",
"url": "https://io.plangrid.com/projects/11a2b248-fbf5-439e-ab49-34adef8875f8/issue_lists/9a11e2d8-9449-46e6-881d-09cb2d0ec90c"
},
"current_annotation": {
"uid": "6994b73b-c3b4-4aa3-a985-fd973e599526",
"color": "#F38109",
"stamp": "E",
"visibility": "master",
"deleted": false,
"sheet": {
"uid": "f3718ded-9919-4667-a746-969fda1cfe26",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26"
}
},
"title": "Electrical",
"room": "M100",
"description": "Missing wall outlets.",
"assigned_to": [{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "bob@subcontractor.com"
}],
"status": "open",
"created_at": "2015-06-08T18:04:02+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "alfred@architect.com"
},
"updated_at": "2013-05-23T19:22:56+00:00",
"updated_by": {
"uid": null,
"url": null,
"email": "betty@construction.com"
},
"photos": {
"total_count": 1,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/22f3530a-a00b-42f9-8139-3a7554c77c27/photos"
},
"comments": {
"total_count": 0,
"url": null
},
"due_at": "2016-10-31T15:32:26+00:00",
"has_cost_impact": true,
"cost_impact": 25850.10,
"currency_code": "USD",
"has_schedule_impact": true,
"schedule_impact": 186400,
"deleted": false
}
{"_id":"5a0487c11058cd003cfb7b14","category":"5a0487bf1058cd003cfb7aa5","user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:05:36.806Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"status":200,"name":"Success","code":"{\n \"data\": [\n {\n \"uid\": \"22f3530a-a00b-42f9-8139-3a7554c77c27\",\n \"number\": 1,\n \"issue_list\": {\n \"uid\": \"9a11e2d8-9449-46e6-881d-09cb2d0ec90c\",\n \"url\": \"https://io.plangrid.com/projects/11a2b248-fbf5-439e-ab49-34adef8875f8/issue_lists/9a11e2d8-9449-46e6-881d-09cb2d0ec90c\"\n },\n \"current_annotation\": {\n \"uid\": \"6994b73b-c3b4-4aa3-a985-fd973e599526\",\n \"color\": \"#F38109\",\n \"stamp\": \"E\",\n \"visibility\": \"master\",\n \"deleted\": false,\n \"sheet\": {\n \"uid\": \"f3718ded-9919-4667-a746-969fda1cfe26\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26\"\n }\n },\n \"title\": \"Electrical\",\n \"room\": \"M100\",\n \"description\": \"Missing wall outlets.\",\n \"assigned_to\": [{\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"bob@subcontractor.com\"\n }],\n \"status\": \"open\",\n \"created_at\": \"2015-06-08T18:04:02+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"alfred@architect.com\"\n },\n \"updated_at\": \"2013-05-23T19:22:56+00:00\",\n \"updated_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"betty@construction.com\"\n },\n \"photos\": {\n \"total_count\": 0,\n \"url\": null\n },\n \"comments\": {\n \"total_count\": 2,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/22f3530a-a00b-42f9-8139-3a7554c77c27/comments\"\n },\n \"due_at\": \"2016-11-02T10:12:28+00:00\",\n \"has_cost_impact\": true,\n \"cost_impact\": 1800.00,\n \"currency_code\": \"USD\",\n \"has_schedule_impact\": false,\n \"schedule_impact\": null,\n \"deleted\": false\n },\n {\n \"uid\": \"51cb7310-6feb-47ae-8ad9-a89ac6101294\",\n \"number\": 2,\n \"issue_list\": null,\n \"current_annotation\": {\n \"uid\": \"6994b73b-c3b4-4aa3-a985-fd973e599526\",\n \"color\": \"#F38109\",\n \"stamp\": \"CN\",\n \"visibility\": \"master\",\n \"deleted\": false,\n \"sheet\": {\n \"uid\": \"f3718ded-9919-4667-a746-969fda1cfe26\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26\"\n }\n },\n \"title\": \"Cleaning Needed\",\n \"room\": \"M101\",\n \"description\": \"Clean paint and drywall mud from fire alarm.\",\n \"assigned_to\": [{\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"bob@subcontractor.com\"\n }],\n \"status\": \"open\",\n \"created_at\": \"2015-06-08T18:04:02+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"alfred@architect.com\"\n },\n \"updated_at\": \"2013-05-23T19:22:56+00:00\",\n \"updated_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"betty@construction.com\"\n },\n \"photos\": {\n \"total_count\": 1,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos\"\n },\n \"comments\": {\n \"total_count\": 2,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments\"\n },\n \"due_at\": null,\n \"has_cost_impact\": false,\n \"cost_impact\": null,\n \"currency_code\": null,\n \"has_schedule_impact\": true,\n \"schedule_impact\": 259200,\n \"deleted\": false\n }\n ],\n \"total_count\": 50,\n \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues?skip=2&limit=2\"\n}\n","language":"json"},{"code":"{\n \"data\": [\n {\n \"uid\": \"22f3530a-a00b-42f9-8139-3a7554c77c27\",\n \"number\": 1,\n \"current_annotation\": {\n \"uid\": \"6994b73b-c3b4-4aa3-a985-fd973e599526\",\n \"color\": \"#F38109\",\n \"stamp\": \"E\",\n \"visibility\": \"master\",\n \"deleted\": true,\n \"sheet\": {\n \"uid\": \"f3718ded-9919-4667-a746-969fda1cfe26\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26\"\n }\n },\n \"title\": \"Electrical\",\n \"description\": \"Missing wall outlets.\",\n \"assigned_to\": [{\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"bob@subcontractor.com\"\n }],\n \"status\": \"open\",\n \"created_at\": \"2015-06-08T18:04:02Z\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"alfred@architect.com\"\n },\n \"updated_at\": \"2013-05-23T19:22:56Z\",\n \"room\": \"S20\",\n \"updated_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"betty@construction.com\"\n },\n \"deleted\": false,\n \"photos\": {\n \"total_count\": 0,\n \"url\": null\n },\n \"comments\": {\n \"total_count\": 2,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/22f3530a-a00b-42f9-8139-3a7554c77c27/comments\"\n }\n },\n ],\n \"total_count\": 10,\n \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues?skip=1&limit=1\"\n}\n","language":"json","status":200,"name":"Archived Issue"},{"language":"json","status":404,"name":"Project Missing","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n"},{"name":"No Project Access","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","language":"json","status":403}]},"settings":"","auth":"required","params":[{"_id":"56cf1eca5267d70b00494ba2","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1eca5267d70b00494ba1","ref":"","in":"query","required":false,"desc":"Number of issues to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1eca5267d70b00494ba0","ref":"","in":"query","required":false,"desc":"Number of issues to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"56edbf5efc1410200082dc72","ref":"","in":"query","required":false,"desc":"Only retrieve issues created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"datetime","name":"updated_after"}],"url":"/projects/:project_uid/issues"},"isReference":false,"order":2,"body":"","excerpt":"Get a list of issues in a project. _All issues_ inside a project are returned, including deleted, archived, and personal issues across all team members. Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-issues-in-a-project","type":"get","title":"Retrieve Issues in a Project","__v":3,"childrenPages":[]}
getRetrieve Issues in a Project
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
"number": 1,
"issue_list": {
"uid": "9a11e2d8-9449-46e6-881d-09cb2d0ec90c",
"url": "https://io.plangrid.com/projects/11a2b248-fbf5-439e-ab49-34adef8875f8/issue_lists/9a11e2d8-9449-46e6-881d-09cb2d0ec90c"
},
"current_annotation": {
"uid": "6994b73b-c3b4-4aa3-a985-fd973e599526",
"color": "#F38109",
"stamp": "E",
"visibility": "master",
"deleted": false,
"sheet": {
"uid": "f3718ded-9919-4667-a746-969fda1cfe26",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26"
}
},
"title": "Electrical",
"room": "M100",
"description": "Missing wall outlets.",
"assigned_to": [{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "bob@subcontractor.com"
}],
"status": "open",
"created_at": "2015-06-08T18:04:02+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "alfred@architect.com"
},
"updated_at": "2013-05-23T19:22:56+00:00",
"updated_by": {
"uid": null,
"url": null,
"email": "betty@construction.com"
},
"photos": {
"total_count": 0,
"url": null
},
"comments": {
"total_count": 2,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/22f3530a-a00b-42f9-8139-3a7554c77c27/comments"
},
"due_at": "2016-11-02T10:12:28+00:00",
"has_cost_impact": true,
"cost_impact": 1800.00,
"currency_code": "USD",
"has_schedule_impact": false,
"schedule_impact": null,
"deleted": false
},
{
"uid": "51cb7310-6feb-47ae-8ad9-a89ac6101294",
"number": 2,
"issue_list": null,
"current_annotation": {
"uid": "6994b73b-c3b4-4aa3-a985-fd973e599526",
"color": "#F38109",
"stamp": "CN",
"visibility": "master",
"deleted": false,
"sheet": {
"uid": "f3718ded-9919-4667-a746-969fda1cfe26",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26"
}
},
"title": "Cleaning Needed",
"room": "M101",
"description": "Clean paint and drywall mud from fire alarm.",
"assigned_to": [{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "bob@subcontractor.com"
}],
"status": "open",
"created_at": "2015-06-08T18:04:02+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "alfred@architect.com"
},
"updated_at": "2013-05-23T19:22:56+00:00",
"updated_by": {
"uid": null,
"url": null,
"email": "betty@construction.com"
},
"photos": {
"total_count": 1,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos"
},
"comments": {
"total_count": 2,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments"
},
"due_at": null,
"has_cost_impact": false,
"cost_impact": null,
"currency_code": null,
"has_schedule_impact": true,
"schedule_impact": 259200,
"deleted": false
}
],
"total_count": 50,
"next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues?skip=2&limit=2"
}
{
"data": [
{
"uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
"number": 1,
"current_annotation": {
"uid": "6994b73b-c3b4-4aa3-a985-fd973e599526",
"color": "#F38109",
"stamp": "E",
"visibility": "master",
"deleted": true,
"sheet": {
"uid": "f3718ded-9919-4667-a746-969fda1cfe26",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26"
}
},
"title": "Electrical",
"description": "Missing wall outlets.",
"assigned_to": [{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "bob@subcontractor.com"
}],
"status": "open",
"created_at": "2015-06-08T18:04:02Z",
"created_by": {
"uid": null,
"url": null,
"email": "alfred@architect.com"
},
"updated_at": "2013-05-23T19:22:56Z",
"room": "S20",
"updated_by": {
"uid": null,
"url": null,
"email": "betty@construction.com"
},
"deleted": false,
"photos": {
"total_count": 0,
"url": null
},
"comments": {
"total_count": 2,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/22f3530a-a00b-42f9-8139-3a7554c77c27/comments"
}
},
],
"total_count": 10,
"next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues?skip=1&limit=1"
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{"_id":"5a0487c11058cd003cfb7b15","category":"5a0487bf1058cd003cfb7aa5","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-08-14T20:58:00.971Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","examples":{"codes":[]},"method":"get","results":{"codes":[{"language":"json","code":"{\n \"uid\": \"51cb7310-6feb-47ae-8ad9-a89ac6101294\",\n \"number\": 2,\n \"issue_list\": {\n \"uid\": \"9a11e2d8-9449-46e6-881d-09cb2d0ec90c\",\n \"url\": \"https://io.plangrid.com/projects/11a2b248-fbf5-439e-ab49-34adef8875f8/issue_lists/9a11e2d8-9449-46e6-881d-09cb2d0ec90c\"\n },\n \"current_annotation\": {\n \"uid\": \"6994b73b-c3b4-4aa3-a985-fd973e599526\",\n \"color\": \"#F38109\",\n \"stamp\": \"CN\",\n \"visibility\": \"master\",\n \"deleted\": false,\n \"sheet\": {\n \"uid\": \"f3718ded-9919-4667-a746-969fda1cfe26\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26\"\n }\n },\n \"title\": \"Cleaning Needed\",\n \"room\": \"M101\",\n \"description\": \"Clean paint and drywall mud from fire alarm.\",\n \"assigned_to\": [{\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"bob@subcontractor.com\"\n }],\n \"status\": \"open\",\n \"created_at\": \"2015-06-08T18:04:02+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"alfred@architect.com\"\n },\n \"updated_at\": \"2013-05-23T19:22:56+00:00\",\n \"updated_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"betty@construction.com\"\n },\n \"photos\": {\n \"total_count\": 1,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos\"\n },\n \"comments\": {\n \"total_count\": 2,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments\"\n },\n \"due_at\": false,\n \"has_cost_impact\": false,\n \"cost_impact\": null,\n \"currency_code\": null,\n \"has_schedule_impact\": false,\n \"schedule_impact\": null,\n \"deleted\": false\n}","name":"","status":200},{"name":"Project Missing","status":404,"language":"json","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}"},{"code":"{\n \"message\": \"Issue (ee28dd97-bb68-4108-8cea-fb4a1cbccff8) does not exist.\"\n}","name":"Issue Missing","status":404,"language":"json"},{"language":"json","status":403,"name":"No Project Access","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}"}]},"auth":"required","params":[{"_id":"57b0dc21430b3d0e00703a5f","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"57b0dc21430b3d0e00703a5e","ref":"","in":"path","required":true,"desc":"Unique identifier of issue","default":"","type":"string","name":"issue_uid"}],"url":"/projects/:project_uid/issues/:issue_uid"},"isReference":false,"order":3,"body":"","excerpt":"Get an issue in a project.","slug":"retrieve-issue-in-a-project","type":"get","title":"Retrieve Issue in a Project","__v":1,"childrenPages":[]}
getRetrieve Issue in a Project
Path Params
Definition
Result Format
{
"uid": "51cb7310-6feb-47ae-8ad9-a89ac6101294",
"number": 2,
"issue_list": {
"uid": "9a11e2d8-9449-46e6-881d-09cb2d0ec90c",
"url": "https://io.plangrid.com/projects/11a2b248-fbf5-439e-ab49-34adef8875f8/issue_lists/9a11e2d8-9449-46e6-881d-09cb2d0ec90c"
},
"current_annotation": {
"uid": "6994b73b-c3b4-4aa3-a985-fd973e599526",
"color": "#F38109",
"stamp": "CN",
"visibility": "master",
"deleted": false,
"sheet": {
"uid": "f3718ded-9919-4667-a746-969fda1cfe26",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26"
}
},
"title": "Cleaning Needed",
"room": "M101",
"description": "Clean paint and drywall mud from fire alarm.",
"assigned_to": [{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "bob@subcontractor.com"
}],
"status": "open",
"created_at": "2015-06-08T18:04:02+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "alfred@architect.com"
},
"updated_at": "2013-05-23T19:22:56+00:00",
"updated_by": {
"uid": null,
"url": null,
"email": "betty@construction.com"
},
"photos": {
"total_count": 1,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos"
},
"comments": {
"total_count": 2,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments"
},
"due_at": false,
"has_cost_impact": false,
"cost_impact": null,
"currency_code": null,
"has_schedule_impact": false,
"schedule_impact": null,
"deleted": false
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Issue (ee28dd97-bb68-4108-8cea-fb4a1cbccff8) does not exist."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{"_id":"5a0487c11058cd003cfb7b16","category":"5a0487bf1058cd003cfb7aa5","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:09:53.175Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{\n \"data\": [\n {\n \"uid\": \"87658a3f-8ee0-4188-9c55-b06a203fa9e7\",\n \"text\": \"there's that word again. \\\"heavy\\\". why are things so heavy in the future? is there a problem with the earth's gravitational pull?\",\n \"created_at\": \"2013-05-17t02:30:22z\",\n \"created_by\": {\n \"uid\": \"deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n \"email\": \"doc@subcontractor.com\"\n },\n \"record_type\": \"issue\",\n \"record\": {\n \"uid\": \"b9876ac1-369f-401b-8ca0-6f152b533895\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895\"\n }\n },\n {\n \"uid\": \"465abf98-accb-42cd-bd54-16f29e8447f2\",\n \"text\": \"woh. this is heavy!\",\n \"created_at\": \"2013-05-15t18:54:22+00:00\",\n \"created_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"marty@construction.com\"\n },\n \"record_type\": \"issue\",\n \"record\": {\n \"uid\": \"b9876ac1-369f-401b-8ca0-6f152b533895\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895\"\n }\n },\n {\n \"uid\": \"08ea8b05-a99c-40a7-a312-fee360ad432a\",\n \"text\": \"precisely.\",\n \"created_at\": \"2013-05-14t8:30:56+00:00\",\n \"created_by\": {\n \"uid\": \"deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n \"email\": \"doc@subcontractor.com\"\n },\n \"record_type\": \"issue\",\n \"record\": {\n \"uid\": \"b9876ac1-369f-401b-8ca0-6f152b533895\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895\"\n }\n },\n {\n \"uid\": \"68839690-e0aa-4751-aedf-e630b921e91e\",\n \"text\": \"wait a minute, Doc, are you trying to tell me that my mother has got the hots for me?\",\n \"created_at\": \"2013-05-13t11:22:56+00:00\",\n \"created_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"marty@construction.com\"\n },\n \"record_type\": \"issue\",\n \"record\": {\n \"uid\": \"b9876ac1-369f-401b-8ca0-6f152b533895\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895\"\n }\n }\n ],\n \"total_count\": 6,\n \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments?skip=4&limit=4\"\n}\n","name":"Success"},{"language":"json","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}","name":"Project Missing","status":404},{"language":"json","code":"{\n \"message\": \"Issue (68839690-e0aa-4751-aedf-e630b921e91e) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"Issue Missing","status":404},{"language":"json","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}\n","name":"No Project Access","status":403}]},"settings":"","examples":{"codes":[]},"method":"get","auth":"required","params":[{"_id":"56cf1ec95267d70b00494b9b","ref":"","in":"path","required":true,"desc":"Unique identifier for issue's project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ec95267d70b00494b9a","ref":"","in":"path","required":true,"desc":"Unique identifier of issue.","default":"","type":"string","name":"issue_uid"},{"_id":"56cf1ec95267d70b00494b99","ref":"","in":"query","required":false,"desc":"Number of comments to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ec95267d70b00494b98","ref":"","in":"query","required":false,"desc":"Number of comments to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"56edc058c3628a170081f008","ref":"","in":"query","required":false,"desc":"Only retrieve comments created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"datetime","name":"updated_after"}],"url":"/projects/:project_uid/issues/:issue_uid/comments"},"isReference":false,"order":4,"body":"","excerpt":"Get a list of comments on an issue. Comment data is described in [The Comment Object](doc:the-comment-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-comments-on-an-issue","type":"get","title":"Retrieve Comments on an Issue","__v":0,"childrenPages":[]}
getRetrieve Comments on an Issue
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"uid": "87658a3f-8ee0-4188-9c55-b06a203fa9e7",
"text": "there's that word again. \"heavy\". why are things so heavy in the future? is there a problem with the earth's gravitational pull?",
"created_at": "2013-05-17t02:30:22z",
"created_by": {
"uid": "deae0b56-81c7-4a05-8e8b-410fd17a01f0",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0",
"email": "doc@subcontractor.com"
},
"record_type": "issue",
"record": {
"uid": "b9876ac1-369f-401b-8ca0-6f152b533895",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895"
}
},
{
"uid": "465abf98-accb-42cd-bd54-16f29e8447f2",
"text": "woh. this is heavy!",
"created_at": "2013-05-15t18:54:22+00:00",
"created_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "marty@construction.com"
},
"record_type": "issue",
"record": {
"uid": "b9876ac1-369f-401b-8ca0-6f152b533895",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895"
}
},
{
"uid": "08ea8b05-a99c-40a7-a312-fee360ad432a",
"text": "precisely.",
"created_at": "2013-05-14t8:30:56+00:00",
"created_by": {
"uid": "deae0b56-81c7-4a05-8e8b-410fd17a01f0",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0",
"email": "doc@subcontractor.com"
},
"record_type": "issue",
"record": {
"uid": "b9876ac1-369f-401b-8ca0-6f152b533895",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895"
}
},
{
"uid": "68839690-e0aa-4751-aedf-e630b921e91e",
"text": "wait a minute, Doc, are you trying to tell me that my mother has got the hots for me?",
"created_at": "2013-05-13t11:22:56+00:00",
"created_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "marty@construction.com"
},
"record_type": "issue",
"record": {
"uid": "b9876ac1-369f-401b-8ca0-6f152b533895",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895"
}
}
],
"total_count": 6,
"next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments?skip=4&limit=4"
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Issue (68839690-e0aa-4751-aedf-e630b921e91e) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}
{"_id":"5a0487c11058cd003cfb7b17","category":"5a0487bf1058cd003cfb7aa5","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:11:37.361Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"status":200,"language":"json","code":"{\n \"data\": [\n {\n \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n \"title\": \"Bongo Drums\",\n \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n \"created_at\": \"2013-05-17T02:30:22+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"nick@subcontractor.com\"\n },\n \"deleted\": false\n },\n {\n \"uid\": \"9acc66f0-b704-4469-99fa-c13ce2b0bf0a\",\n \"title\": \"Bass Guitar\",\n \"url\": \"https://photo-assets.plangrid.com/9acc66f0-b704-4469-99fa-c13ce2b0bf0a.jpg\",\n \"created_at\": \"2013-05-13T04:30:22+00:00\",\n \"created_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"betty@construction.com\"\n },\n \"deleted\": false\n }\n ],\n \"total_count\": 14,\n \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos?skip=2&limit=2\"\n}\n","name":"Success"},{"language":"json","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","name":"Project Missing","status":404},{"language":"json","code":"{\n \"message\": \"Issue (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"Issue Missing","status":404},{"language":"json","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}\n","name":"No Project Access","status":403}]},"settings":"","auth":"required","params":[{"_id":"56cf1eca5267d70b00494b9f","ref":"","in":"path","required":true,"desc":"Unique identifier for issue's project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1eca5267d70b00494b9e","ref":"","in":"path","required":true,"desc":"Unique identifier of issue.","default":"","type":"string","name":"issue_uid"},{"_id":"56cf1eca5267d70b00494b9d","ref":"","in":"query","required":false,"desc":"Number of photos to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1eca5267d70b00494b9c","ref":"","in":"query","required":false,"desc":"Number of photos to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"56edc390fc1410200082dc7b","ref":"","in":"query","required":false,"desc":"Only retrieve photos created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"datetime","name":"updated_after"}],"url":"/projects/:project_uid/issues/:issue_uid/photos"},"isReference":false,"order":5,"body":"","excerpt":"Get a list of photos added to an issue. Photo data is described in [The Photo Object](doc:the-photo-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-photos-on-an-issue","type":"get","title":"Retrieve Photos on an Issue","__v":0,"childrenPages":[]}
getRetrieve Photos on an Issue
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
"title": "Bongo Drums",
"url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
"created_at": "2013-05-17T02:30:22+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "nick@subcontractor.com"
},
"deleted": false
},
{
"uid": "9acc66f0-b704-4469-99fa-c13ce2b0bf0a",
"title": "Bass Guitar",
"url": "https://photo-assets.plangrid.com/9acc66f0-b704-4469-99fa-c13ce2b0bf0a.jpg",
"created_at": "2013-05-13T04:30:22+00:00",
"created_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "betty@construction.com"
},
"deleted": false
}
],
"total_count": 14,
"next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos?skip=2&limit=2"
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Issue (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}
{"_id":"5a0487c11058cd003cfb7b18","category":"5a0487bf1058cd003cfb7aa5","project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-07-31T17:13:05.509Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"code":"{\n \"uid\": \"51cb7310-6feb-47ae-8ad9-a89ac6101294\",\n \"number\": 2,\n \"issue_list\": {\n \"uid\": \"9a11e2d8-9449-46e6-881d-09cb2d0ec90c\",\n \"url\": \"https://io.plangrid.com/projects/11a2b248-fbf5-439e-ab49-34adef8875f8/issue_lists/9a11e2d8-9449-46e6-881d-09cb2d0ec90c\"\n },\n \"current_annotation\": {\n \"uid\": \"6994b73b-c3b4-4aa3-a985-fd973e599526\",\n \"color\": \"#F38109\",\n \"stamp\": \"CN\",\n \"visibility\": \"master\",\n \"deleted\": false,\n \"sheet\": {\n \"uid\": \"f3718ded-9919-4667-a746-969fda1cfe26\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26\"\n }\n },\n \"title\": \"Cleaning Needed\",\n \"room\": \"M101\",\n \"description\": \"Clean paint and drywall mud from fire alarm.\",\n \"assigned_to\": [{\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"bob@subcontractor.com\"\n }],\n \"status\": \"open\",\n \"created_at\": \"2015-06-08T18:04:02+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"alfred@architect.com\"\n },\n \"due_at\": false,\n \"has_cost_impact\": false,\n \"cost_impact\": null,\n \"currency_code\": null,\n \"has_schedule_impact\": false,\n \"schedule_impact\": null,\n \"deleted\": false\n}","language":"json","name":"OK","status":200},{"status":400,"code":"{\n \"message\": \"Fields must be in JSON body.\"\n}","language":"json","name":"Missing JSON Body"},{"code":"{\n \"message\": \"Assignee (:uid) is not on project (:project_uid).\"\n}","language":"json","status":400,"name":"Invalid User"},{"name":"Invalid Due At Date","status":400,"language":"json","code":"{\n \"message\": \"Due at (:due_at) must be null or a datetime string in ISO-8601 format.\"\n}"},{"code":"{\n \"message\": \"Status (:status) must be a valid issue status on project (:project_uid).\"\n}","language":"json","status":400,"name":"Invalid Status"},{"code":"{\n \"message\": \"Issue (:issue_uid) does not exist in project (:project_uid).\"\n}","language":"json","status":404,"name":"Does Not Exist"}]},"method":"patch","examples":{"codes":[]},"auth":"required","params":[{"_id":"56cf1eca5267d70b00494ba2","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"597f6bfa18d5a5001e81a75a","ref":"","in":"path","required":true,"desc":"Unique identifier of the issue in the project.","default":"","type":"string","name":"issue_uid"},{"_id":"597f6bfa18d5a5001e81a759","ref":"","in":"body","required":false,"desc":"A list of user UIDs that the issue should be assigned to. Note that this list may only contain one user UID.","default":"","type":"array_string","name":"assigned_to_uids"},{"_id":"597f771f13e6ef00142dccdb","ref":"","in":"body","required":false,"desc":"The cost impact, if there is one.","default":"","type":"float","name":"cost_impact"},{"_id":"597f6bfa18d5a5001e81a757","ref":"","in":"body","required":false,"desc":"A description of the issue.","default":"","type":"string","name":"description"},{"_id":"597f6bfa18d5a5001e81a756","ref":"","in":"body","required":false,"desc":"When the issue is due. UTC date and time in ISO-8601. Note that the time component will be truncated into 00:00.","default":"","type":"string","name":"due_at"},{"_id":"597f6bfa18d5a5001e81a755","ref":"","in":"body","required":false,"desc":"Whether or not the issue has a cost impact. If `cost_impact` is specified in the request this field cannot be `false`, and if `has_cost_impact` is not specified, it will be treated as `true`.","default":"","type":"boolean","name":"has_cost_impact"},{"_id":"597f6bfa18d5a5001e81a754","ref":"","in":"body","required":false,"desc":"Whether or not the issue has a schedule impact. If `schedule_impact` is specified in the request this field cannot be `false`, and if `has_schedule_impact` is not specified it will be treated as `true`.","default":"","type":"boolean","name":"has_schedule_impact"},{"_id":"597f6bfa18d5a5001e81a753","ref":"","in":"body","required":false,"desc":"The issue's schedule impact in seconds, if it has one.","default":"","type":"int","name":"schedule_impact"},{"_id":"597f6bfa18d5a5001e81a752","ref":"","in":"body","required":false,"desc":"The status of the issue. Accepted values are `closed`, `in_review`, `open`, and `pending`.","default":"","type":"string","name":"status"},{"_id":"597f6bfa18d5a5001e81a751","ref":"","in":"body","required":false,"desc":"The title of the issue.","default":"","type":"string","name":"title"},{"_id":"5a134c6e45769d002674f840","ref":"","in":"body","required":false,"desc":"The unique identifier of the issue list to which the issue will be assigned to.","default":"","type":"string","name":"issue_list_uid"}],"url":"/projects/:project_uid/issues/:issue_uid"},"isReference":false,"order":6,"body":"","excerpt":"Update an issue in a project.","slug":"update-issue-in-a-project","type":"patch","title":"Update Issue in a Project","__v":5,"childrenPages":[]}
patchUpdate Issue in a Project
Path Params
Body Params
Definition
Result Format
{
"uid": "51cb7310-6feb-47ae-8ad9-a89ac6101294",
"number": 2,
"issue_list": {
"uid": "9a11e2d8-9449-46e6-881d-09cb2d0ec90c",
"url": "https://io.plangrid.com/projects/11a2b248-fbf5-439e-ab49-34adef8875f8/issue_lists/9a11e2d8-9449-46e6-881d-09cb2d0ec90c"
},
"current_annotation": {
"uid": "6994b73b-c3b4-4aa3-a985-fd973e599526",
"color": "#F38109",
"stamp": "CN",
"visibility": "master",
"deleted": false,
"sheet": {
"uid": "f3718ded-9919-4667-a746-969fda1cfe26",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26"
}
},
"title": "Cleaning Needed",
"room": "M101",
"description": "Clean paint and drywall mud from fire alarm.",
"assigned_to": [{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "bob@subcontractor.com"
}],
"status": "open",
"created_at": "2015-06-08T18:04:02+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "alfred@architect.com"
},
"due_at": false,
"has_cost_impact": false,
"cost_impact": null,
"currency_code": null,
"has_schedule_impact": false,
"schedule_impact": null,
"deleted": false
}
{
"message": "Fields must be in JSON body."
}
{
"message": "Assignee (:uid) is not on project (:project_uid)."
}
{
"message": "Due at (:due_at) must be null or a datetime string in ISO-8601 format."
}
{
"message": "Status (:status) must be a valid issue status on project (:project_uid)."
}
{
"message": "Issue (:issue_uid) does not exist in project (:project_uid)."
}
{"_id":"5a0488831058cd003cfb7b1d","project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","category":"5a049f9491d7ee00344de5a5","user":"57db49de0678030e008a76f8","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-11-09T16:55:31.846Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"status":200,"name":"","code":"{}","language":"json"},{"language":"json","status":400,"name":"","code":"{}"}]},"auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:parameters]\n{\n \"data\": {\n \"0-0\": \"**uid**\\n`string`\",\n \"0-1\": \"Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n \"1-0\": \"**name**\\n`string`\",\n \"1-1\": \"Name of the issue list. Never blank.\",\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"2-0\": \"**project_uid**\\n`string`\",\n \"2-1\": \"Unique identifier for the project. Never blank.\",\n \"3-0\": \"**deleted**\\n`boolean`\",\n \"3-1\": \"Whether the issue list has been deleted. Never blank.\"\n },\n \"cols\": 2,\n \"rows\": 4\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"uid\\\": \\\"27b3530c-00cc-4fd0-b55f-24b49181ff82\\\",\\n \\\"name\\\": \\\"Safety Observations\\\",\\n \\\"project_uid\\\": \\\"11a2b248-fbf5-439e-ab49-34adef8875f8\\\",\\n \\\"deleted\\\": false\\n}\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-issue-list-object","type":"basic","title":"The Issue List Object","__v":0,"parentDoc":null,"childrenPages":[]}
The Issue List Object
uidstring
Never blank. See Unique Identifiers for details.
namestring
Name of the issue list. Never blank.
project_uidstring
Unique identifier for the project. Never blank.
deletedboolean
Whether the issue list has been deleted. Never blank.
{
"uid": "27b3530c-00cc-4fd0-b55f-24b49181ff82",
"name": "Safety Observations",
"project_uid": "11a2b248-fbf5-439e-ab49-34adef8875f8",
"deleted": false
}
{"_id":"5a048a9738f024001097df1a","project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","category":"5a049f9491d7ee00344de5a5","user":"57db49de0678030e008a76f8","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-11-09T17:04:23.013Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"language":"json","code":"{\n \"uid\": \"31f54967-4eac-4bd7-9b35-57f00a973a1d\",\n \"name\": \"Constructability Review\",\n \"project_uid\": \"11a2b248-fbf5-439e-ab49-34adef8875f8\",\n \"deleted\": false\n}","name":"Success","status":201},{"status":403,"language":"json","code":"{\n \"message\": \"Access to project (:project_uid) prohibited.\"\n}\n","name":"No Project Access"},{"code":"{\n \"errors\": {\n \"name\": \"Missing data for required field.\"\n },\n \"message\": \"JSON body parameters are invalid.\"\n}","language":"json","status":400,"name":"Name Missing"},{"code":"{\n \"message\": \"Project (:project_uid) does not exist.\"\n}","language":"json","status":404,"name":"Project Not Found"}]},"method":"post","examples":{"codes":[]},"auth":"required","params":[{"_id":"5a048a9738f024001097df1b","ref":"","in":"body","required":true,"desc":"Name of the issue list.","default":"","type":"string","name":"name"},{"_id":"5a049e5839f4a10010cb521e","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"}],"url":"/projects/:project_uid/issue_lists"},"isReference":false,"order":1,"body":"","excerpt":"","slug":"create-issue-list","type":"post","title":"Create Issue List in a Project","__v":15,"parentDoc":null,"childrenPages":[]}
postCreate Issue List in a Project
Path Params
Body Params
Definition
Result Format
{
"uid": "31f54967-4eac-4bd7-9b35-57f00a973a1d",
"name": "Constructability Review",
"project_uid": "11a2b248-fbf5-439e-ab49-34adef8875f8",
"deleted": false
}
{
"message": "Access to project (:project_uid) prohibited."
}
{
"errors": {
"name": "Missing data for required field."
},
"message": "JSON body parameters are invalid."
}
{
"message": "Project (:project_uid) does not exist."
}
{"_id":"5a049e1f38f024001097e214","project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","category":"5a049f9491d7ee00344de5a5","user":"57db49de0678030e008a76f8","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-11-09T18:27:43.715Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"status":200,"name":"Success","code":"{\n \"data\": [\n {\n \"deleted\": false,\n \"name\": \"Constructability Review\",\n \"project_uid\": \"11a2b248-fbf5-439e-ab49-34adef8875f8\",\n \"uid\": \"d3c184d8-7f07-4958-bdce-28e295c36fc7\"\n },\n {\n \"deleted\": false,\n \"name\": \"Safety Observations\",\n \"project_uid\": \"11a2b248-fbf5-439e-ab49-34adef8875f8\",\n \"uid\": \"9ae72913-7308-467f-a881-d826875aea83\"\n }\n ],\n \"next_page_url\": \"https://io.plangrid.com/projects/11a2b248-fbf5-439e-ab49-34adef8875f8/issue_lists?skip=2&limit=2\",\n \"total_count\": 19\n}\n","language":"json"},{"language":"json","status":404,"name":"Project Not Found","code":"{\n \"message\": \"Project (:project_uid) does not exist.\"\n}\n"},{"name":"No Project Access","code":"{\n \"message\": \"Access to project (:project_uid) prohibited.\"\n}\n","language":"json","status":403},{"name":"Issue List Not Found","status":404,"language":"json","code":"{\n \"message\": \"Issue List (:issue_list_uid) does not exist in project (:project_uid).\"\n}"}]},"settings":"","auth":"required","params":[{"_id":"5a049e1f38f024001097e216","ref":"","in":"query","required":false,"desc":"Number of issues to retrieve. Maximum value of 50.","default":"","type":"int","name":"limit"},{"_id":"5a049e1f38f024001097e215","ref":"","in":"query","required":false,"desc":"Number of issues to skip in the set of results.","default":"","type":"int","name":"skip"},{"_id":"5a049e7791d7ee00344de592","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"}],"url":"/projects/:project_uid/issue_lists"},"isReference":false,"order":2,"body":"","excerpt":"","slug":"retrieve-issue-lists","type":"get","title":"Retrieve Issue Lists in a Project","__v":17,"parentDoc":null,"childrenPages":[]}
getRetrieve Issue Lists in a Project
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"deleted": false,
"name": "Constructability Review",
"project_uid": "11a2b248-fbf5-439e-ab49-34adef8875f8",
"uid": "d3c184d8-7f07-4958-bdce-28e295c36fc7"
},
{
"deleted": false,
"name": "Safety Observations",
"project_uid": "11a2b248-fbf5-439e-ab49-34adef8875f8",
"uid": "9ae72913-7308-467f-a881-d826875aea83"
}
],
"next_page_url": "https://io.plangrid.com/projects/11a2b248-fbf5-439e-ab49-34adef8875f8/issue_lists?skip=2&limit=2",
"total_count": 19
}
{
"message": "Project (:project_uid) does not exist."
}
{
"message": "Access to project (:project_uid) prohibited."
}
{
"message": "Issue List (:issue_list_uid) does not exist in project (:project_uid)."
}
{"_id":"5a04b5c719075e00100c213e","project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","category":"5a049f9491d7ee00344de5a5","user":"57db49de0678030e008a76f8","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-11-09T20:08:39.078Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"status":200,"name":"Success","code":"{\n \"uid\": \"31f54967-4eac-4bd7-9b35-57f00a973a1d\",\n \"name\": \"QA/QC\",\n \"deleted\": false,\n \"project_uid\": \"11a2b248-fbf5-439e-ab49-34adef8875f8\"\n}\n","language":"json"},{"language":"json","status":404,"name":"Project Missing","code":"{\n \"message\": \"Project (:project_uid) does not exist.\"\n}\n"},{"name":"No Project Access","code":"{\n \"message\": \"Access to project (:project_uid) prohibited.\"\n}\n","language":"json","status":403},{"name":"Not Found","status":404,"language":"json","code":"{\n \"message\": \"Issue List (:issue_list_uid) does not exist in project (:project_uid).\"\n}"}]},"method":"get","examples":{"codes":[]},"auth":"required","params":[{"_id":"5a049e7791d7ee00344de592","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"5a04b5c719075e00100c213f","ref":"","in":"path","required":true,"desc":"Unique identifier of issue list to retrieve.","default":"","type":"string","name":"issue_list_uid"}],"url":"/projects/:project_uid/issue_lists/:issue_list_uid"},"isReference":false,"order":999,"body":"","excerpt":"","slug":"retrieve-issue-list","type":"get","title":"Retrieve Issue List in a Project","__v":16,"childrenPages":[]}
getRetrieve Issue List in a Project
Path Params
Definition
Result Format
{
"uid": "31f54967-4eac-4bd7-9b35-57f00a973a1d",
"name": "QA/QC",
"deleted": false,
"project_uid": "11a2b248-fbf5-439e-ab49-34adef8875f8"
}
{
"message": "Project (:project_uid) does not exist."
}
{
"message": "Access to project (:project_uid) prohibited."
}
{
"message": "Issue List (:issue_list_uid) does not exist in project (:project_uid)."
}
{"_id":"5a04b6add9f3a40010cef133","project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","category":"5a049f9491d7ee00344de5a5","user":"57db49de0678030e008a76f8","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-11-09T20:12:29.427Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"patch","results":{"codes":[{"language":"json","code":"{\n \"uid\": \"31f54967-4eac-4bd7-9b35-57f00a973a1d\",\n \"name\": \"Constructability Review\",\n \"project_uid\": \"11a2b248-fbf5-439e-ab49-34adef8875f8\",\n \"deleted\": false\n}\n","name":"Success","status":200},{"code":"{\n \"message\": \"Project (:project_uid) does not exist.\"\n}\n","name":"Project Missing","status":404,"language":"json"},{"status":403,"language":"json","code":"{\n \"message\": \"Access to project (:project_uid) prohibited.\"\n}\n","name":"No Project Access"},{"code":"{\n \"message\": \"Issue List (:issue_list_uid) does not exist in project (:project_uid).\"\n}","language":"json","status":404,"name":"Not Found"}]},"settings":"","auth":"required","params":[{"_id":"5a049e7791d7ee00344de592","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"5a04b5c719075e00100c213f","ref":"","in":"path","required":true,"desc":"Unique identifier of issue list to retrieve.","default":"","type":"string","name":"issue_list_uid"},{"_id":"5a04b6add9f3a40010cef134","ref":"","in":"body","required":true,"desc":"Name of the issue list.","default":"","type":"string","name":"name"}],"url":"/projects/:project_uid/issue_lists/:issue_list_uid"},"isReference":false,"order":999,"body":"","excerpt":"","slug":"update-issue-list","type":"patch","title":"Update Issue List in a Project","__v":15,"childrenPages":[]}
patchUpdate Issue List in a Project
Path Params
Body Params
Definition
Result Format
{
"uid": "31f54967-4eac-4bd7-9b35-57f00a973a1d",
"name": "Constructability Review",
"project_uid": "11a2b248-fbf5-439e-ab49-34adef8875f8",
"deleted": false
}
{
"message": "Project (:project_uid) does not exist."
}
{
"message": "Access to project (:project_uid) prohibited."
}
{
"message": "Issue List (:issue_list_uid) does not exist in project (:project_uid)."
}
{"_id":"5a04b6fb19075e00100c2194","project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","category":"5a049f9491d7ee00344de5a5","user":"57db49de0678030e008a76f8","updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-11-09T20:13:47.217Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[{"status":204,"name":"Success","code":" ","language":"json"},{"language":"json","status":404,"name":"Project Missing","code":"{\n \"message\": \"Project (:project_uid) does not exist.\"\n}\n"},{"name":"No Project Access","code":"{\n \"message\": \"Access to project (:project_uid) prohibited.\"\n}\n","language":"json","status":403},{"code":"{\n \"message\": \"Issue List (:issue_list_uid) does not exist in project (:project_uid).\"\n}","language":"json","status":404,"name":null}]},"method":"delete","examples":{"codes":[]},"auth":"required","params":[{"_id":"5a049e7791d7ee00344de592","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"5a04b5c719075e00100c213f","ref":"","in":"path","required":true,"desc":"Unique identifier of issue list to retrieve.","default":"","type":"string","name":"issue_list_uid"}],"url":"/projects/:project_uid/issue_lists/:issue_list_uid"},"isReference":false,"order":999,"body":"","excerpt":"","slug":"delete-issue-list","type":"delete","title":"Delete Issue List in a Project","__v":16,"childrenPages":[]}
deleteDelete Issue List in a Project
Path Params
Definition
Result Format
{
"message": "Project (:project_uid) does not exist."
}
{
"message": "Access to project (:project_uid) prohibited."
}
{
"message": "Issue List (:issue_list_uid) does not exist in project (:project_uid)."
}
{"_id":"5a0487c11058cd003cfb7b09","category":"5a0487bf1058cd003cfb7aa6","parentDoc":null,"user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-10-12T14:24:04.370Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"name":"","code":"{}","language":"json"},{"language":"json","status":400,"name":"","code":"{}"}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:parameters]\n{\n \"data\": {\n \"0-0\": \"**uid**\\n`string`\",\n \"4-0\": \"**created_by**\\n`object`\",\n \"0-1\": \"Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n \"4-1\": \"Reference to PlanGrid user that created the photo. In rare cases, this may not map to a real user. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"1-0\": \"**title**\\n`string`\",\n \"1-1\": \"-\",\n \"3-1\": \"When the photo was created by a client application. UTC date and time in ISO-8601 format.\",\n \"3-0\": \"**created_at**\\n`string`\",\n \"5-0\": \"**deleted**\\n`boolean`\",\n \"5-1\": \"Whether the photo has been deleted. Never blank.\",\n \"2-0\": \"**url**\\n`string`\",\n \"2-1\": \"URL to retrieve image file.\"\n },\n \"cols\": 2,\n \"rows\": 6\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"uid\\\": \\\"319ec8e8-7ad8-4173-aa69-de55a5a259c0\\\",\\n \\\"title\\\": \\\"Selfie\\\",\\n \\\"url\\\": \\\"https://photo-assets.plangrid.com/319ec8e8-7ad8-4173-aa69-de55a5a259c0.jpg\\\",\\n \\\"created_at\\\": \\\"2015-10-12T16:22:54Z\\\",\\n \\\"created_by\\\": {\\n \\\"uid\\\": \\\"d3bade89-01bf-4ea0-889e-d5dad2f56e7e\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d3bade89-01bf-4ea0-889e-d5dad2f56e7e\\\",\\n \\\"email\\\": \\\"patrick.peterson@subcontractor.com\\\" \\n },\\n \\\"deleted\\\": false\\n}\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-photo-object","type":"basic","title":"The Photo Object","__v":0,"childrenPages":[]}
The Photo Object
uidstring
Never blank. See Unique Identifiers for details.
titlestring
-
urlstring
URL to retrieve image file.
created_atstring
When the photo was created by a client application. UTC date and time in ISO-8601 format.
created_byobject
Reference to PlanGrid user that created the photo. In rare cases, this may not map to a real user. See Foreign Keys for attribute details.
deletedboolean
Whether the photo has been deleted. Never blank.
{
"uid": "319ec8e8-7ad8-4173-aa69-de55a5a259c0",
"title": "Selfie",
"url": "https://photo-assets.plangrid.com/319ec8e8-7ad8-4173-aa69-de55a5a259c0.jpg",
"created_at": "2015-10-12T16:22:54Z",
"created_by": {
"uid": "d3bade89-01bf-4ea0-889e-d5dad2f56e7e",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d3bade89-01bf-4ea0-889e-d5dad2f56e7e",
"email": "patrick.peterson@subcontractor.com"
},
"deleted": false
}
{"_id":"5a0487c11058cd003cfb7b0a","category":"5a0487bf1058cd003cfb7aa6","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T20:40:37.886Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","examples":{"codes":[]},"method":"post","results":{"codes":[{"name":"Success","status":201,"language":"json","code":"{\n \"uid\": \"022c132d-cdd0-48a1-8874-d4c9fd310ec8\",\n \"webhook_url\": \"https://io.plangrid.com/projects/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7/photos/uploads/completions/8392cd3fbf2dfbf9fc539c8423a21201\",\n \"aws_post_form_arguments\": {\n \"action\": \"https://photos.s3.amazonaws.com/\",\n \"fields\": [\n {\n \"name\": \"key\",\n \"value\": \"4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\\/1ab29ace-adfe-4ff0-b4bd-267ca612df9a_ff\"\n },\n {\n \"name\": \"AWSAccessKeyId\",\n \"value\": \"AKIAIWKPH7OCNIEE5GGQ\"\n },\n {\n \"name\": \"success_action_redirect\",\n \"value\": \"https:\\/\\/plangrid-c-api-dispatcher-test.herokuapp.com\\/projects\\/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\\/photos\\/uploads\\/completions\\/1039b3921a93c7e74bdb3352779c2c6e\"\n },\n {\n \"name\": \"policy\",\n \"value\": \"eyJleHBpcmF0aW9uIjogIjIwMTUtMTItMjJUMjE6MTU6MTlaIiwKImNvbmRpdGlvbnMiOiBbeyJDb250ZW50LVR5cGUiOiAiYXBwbGljYXRpb24vcGRmIn0seyJidWNrZXQiOiAibG91cGUtdGVzdC1hdHRhY2gifSx7ImtleSI6ICI0ZDBmNGZmNi1iNGU3LWZiNDEtZWRiMi0xMzliMGZmZjllZjcvMWFiMjlhY2UtYWRmZS00ZmYwLWI0YmQtMjY3Y2E2MTJkZjlhX2ZmIn0seyJzdWNjZXNzX2FjdGlvbl9yZWRpcmVjdCI6ICJodHRwczovL3BsYW5ncmlkLWMtYXBpLWRpc3BhdGNoZXItdGVzdC5oZXJva3VhcHAuY29tL3YxL3Byb2plY3RzLzRkMGY0ZmY2LWI0ZTctZmI0MS1lZGIyLTEzOWIwZmZmOWVmNy9hdHRhY2htZW50cy91cGxvYWRzL2NvbXBsZXRpb25zLzEwMzliMzkyMWE5M2M3ZTc0YmRiMzM1Mjc3OWMyYzZlIn0seyJ4LWFtei1zdG9yYWdlLWNsYXNzIjogIlNUQU5EQVJEIn0seyJ4LWFtei1zZXJ2ZXItc2lkZS1lbmNyeXB0aW9uIjogIkFFUzI1NiJ9XX0=\"\n },\n {\n \"name\": \"signature\",\n \"value\": \"CztWq\\/9IU4hCaEiaw0P5IRYmh0g=\"\n },\n {\n \"name\": \"Content-Type\",\n \"value\": \"image\\/png\"\n },\n {\n \"name\": \"x-amz-storage-class\",\n \"value\": \"STANDARD\"\n },\n {\n \"name\": \"x-amz-server-side-encryption\",\n \"value\": \"AES256\"\n }\n ]\n }\n}\n"},{"language":"json","code":"{\n \"message\": \"Content type (application/msword) is not supported.\"\n}\n","name":"Unsupported Content Type","status":400},{"language":"json","code":"{\n \"message\": \"Content type (application/msword) is not supported.\"\n}\n","name":"Content Type Missing","status":400},{"language":"json","code":"{\n \"message\": \"Title (null) must be a string at least one character long.\"\n}\n","name":"Invalid Title","status":400},{"language":"json","code":"{\n \"message\": \"Insufficient permissions to upload photos to project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"Insufficient Permissions","status":403},{"language":"json","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","name":"No Access","status":403}]},"auth":"required","params":[{"_id":"56cf1ecc5267d70b00494bac","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ecc5267d70b00494bab","ref":"","in":"body","required":true,"desc":"Content type of the photo's file.","default":"","type":"string","name":"content_type"},{"_id":"56cf1ecc5267d70b00494baa","ref":"","in":"body","required":true,"desc":"Title of the photo.","default":"","type":"string","name":"title"}],"url":"/projects/:project_uid/photos/uploads"},"isReference":false,"order":1,"body":"","excerpt":"First of three step process for uploading a photo to a project. On success, necessary information for step two and three is returned. The photo record is not created until all three steps are completed. See [File Uploads](doc:file-uploads) for details. Currently, only PNGs and JPEGs are supported.","slug":"upload-photo-to-project","type":"post","title":"Upload Photo to Project","__v":0,"childrenPages":[]}
postUpload Photo to Project
Path Params
Body Params
Definition
Result Format
{
"uid": "022c132d-cdd0-48a1-8874-d4c9fd310ec8",
"webhook_url": "https://io.plangrid.com/projects/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7/photos/uploads/completions/8392cd3fbf2dfbf9fc539c8423a21201",
"aws_post_form_arguments": {
"action": "https://photos.s3.amazonaws.com/",
"fields": [
{
"name": "key",
"value": "4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\/1ab29ace-adfe-4ff0-b4bd-267ca612df9a_ff"
},
{
"name": "AWSAccessKeyId",
"value": "AKIAIWKPH7OCNIEE5GGQ"
},
{
"name": "success_action_redirect",
"value": "https:\/\/plangrid-c-api-dispatcher-test.herokuapp.com\/projects\/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\/photos\/uploads\/completions\/1039b3921a93c7e74bdb3352779c2c6e"
},
{
"name": "policy",
"value": "eyJleHBpcmF0aW9uIjogIjIwMTUtMTItMjJUMjE6MTU6MTlaIiwKImNvbmRpdGlvbnMiOiBbeyJDb250ZW50LVR5cGUiOiAiYXBwbGljYXRpb24vcGRmIn0seyJidWNrZXQiOiAibG91cGUtdGVzdC1hdHRhY2gifSx7ImtleSI6ICI0ZDBmNGZmNi1iNGU3LWZiNDEtZWRiMi0xMzliMGZmZjllZjcvMWFiMjlhY2UtYWRmZS00ZmYwLWI0YmQtMjY3Y2E2MTJkZjlhX2ZmIn0seyJzdWNjZXNzX2FjdGlvbl9yZWRpcmVjdCI6ICJodHRwczovL3BsYW5ncmlkLWMtYXBpLWRpc3BhdGNoZXItdGVzdC5oZXJva3VhcHAuY29tL3YxL3Byb2plY3RzLzRkMGY0ZmY2LWI0ZTctZmI0MS1lZGIyLTEzOWIwZmZmOWVmNy9hdHRhY2htZW50cy91cGxvYWRzL2NvbXBsZXRpb25zLzEwMzliMzkyMWE5M2M3ZTc0YmRiMzM1Mjc3OWMyYzZlIn0seyJ4LWFtei1zdG9yYWdlLWNsYXNzIjogIlNUQU5EQVJEIn0seyJ4LWFtei1zZXJ2ZXItc2lkZS1lbmNyeXB0aW9uIjogIkFFUzI1NiJ9XX0="
},
{
"name": "signature",
"value": "CztWq\/9IU4hCaEiaw0P5IRYmh0g="
},
{
"name": "Content-Type",
"value": "image\/png"
},
{
"name": "x-amz-storage-class",
"value": "STANDARD"
},
{
"name": "x-amz-server-side-encryption",
"value": "AES256"
}
]
}
}
{
"message": "Content type (application/msword) is not supported."
}
{
"message": "Content type (application/msword) is not supported."
}
{
"message": "Title (null) must be a string at least one character long."
}
{
"message": "Insufficient permissions to upload photos to project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{"_id":"5a0487c11058cd003cfb7b0b","category":"5a0487bf1058cd003cfb7aa6","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T20:42:32.011Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"language":"json","code":"{\n \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n \"title\": \"Bongo Drums\",\n \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n \"created_at\": \"2013-05-17T02:30:22+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"nick@subcontractor.com\"\n },\n \"deleted\": false\n}\n","name":"Success","status":201},{"language":"json","code":"{\n \"message\": \"File associated with upload token (8392cd3fbf2dfbf9fc539c8423a21201) is missing.\"\n}\n","name":"File Missing","status":400},{"status":404,"language":"json","code":"{\n \"message\": \"Attachment for upload token (8392cd3fbf2dfbf9fc539c8423a21201) does not exist\"\n}\n","name":"Upload Token Missing"},{"name":"Upload Token Expired","status":410,"language":"json","code":"{\n \"message\": \"Upload token (8392cd3fbf2dfbf9fc539c8423a21201) expired.\"\n}\n"},{"code":"{\n \"message\": \"Sorry, PlanGrid was unable to complete the upload. Use the url included with this message to try again.\"\n \"url\": \"https://io.plangrid.com/v1/projects/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7/photos/uploads/completions/8392cd3fbf2dfbf9fc539c8423a21201\"\n}\n","name":"Server Error","status":500,"language":"json"},{"code":"{\n \"message\": \"Upload token (8392cd3fbf2dfbf9fc539c8423a21201) consumed.\"\n}","language":"json","status":409}]},"settings":"","auth":"required","params":[{"_id":"56cf1eca5267d70b00494ba4","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1eca5267d70b00494ba3","ref":"","in":"path","required":true,"desc":"Token that uniquely identifies the upload.","default":"","type":"string","name":"upload_token"}],"url":"/projects/:project_uid/photos/uploads/completions/:upload_token"},"isReference":false,"order":2,"body":"","excerpt":"Last of three step process for uploading a photo to a project. On success, the new photo record is created and returned. This step is handled automatically with appropriate configuration. See [File Uploads](doc:file-uploads) for details.","slug":"complete-photo-upload-to-project","type":"get","title":"Complete Photo Upload to Project","__v":0,"childrenPages":[]}
getComplete Photo Upload to Project
Path Params
Definition
Result Format
{
"uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
"title": "Bongo Drums",
"url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
"created_at": "2013-05-17T02:30:22+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "nick@subcontractor.com"
},
"deleted": false
}
{
"message": "File associated with upload token (8392cd3fbf2dfbf9fc539c8423a21201) is missing."
}
{
"message": "Attachment for upload token (8392cd3fbf2dfbf9fc539c8423a21201) does not exist"
}
{
"message": "Upload token (8392cd3fbf2dfbf9fc539c8423a21201) expired."
}
{
"message": "Sorry, PlanGrid was unable to complete the upload. Use the url included with this message to try again."
"url": "https://io.plangrid.com/v1/projects/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7/photos/uploads/completions/8392cd3fbf2dfbf9fc539c8423a21201"
}
{
"message": "Upload token (8392cd3fbf2dfbf9fc539c8423a21201) consumed."
}
{"_id":"5a0487c11058cd003cfb7b0c","category":"5a0487bf1058cd003cfb7aa6","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T20:32:04.072Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","examples":{"codes":[]},"method":"get","results":{"codes":[{"code":"{\n \"data\": [\n {\n \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n \"title\": \"Bongo Drums\",\n \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n \"created_at\": \"2013-05-17T02:30:22Z\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"nick@subcontractor.com\"\n },\n \"deleted\": false\n },\n {\n \"uid\": \"9acc66f0-b704-4469-99fa-c13ce2b0bf0a\",\n \"title\": \"Bass Guitar\",\n \"url\": \"https://photo-assets.plangrid.com/9acc66f0-b704-4469-99fa-c13ce2b0bf0a.jpg\",\n \"created_at\": \"2013-05-13T04:30:22Z\",\n \"created_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"betty@construction.com\"\n },\n \"deleted\": false\n }\n ],\n \"total_count\": 14,\n \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/photos?skip=2&limit=2\"\n}\n","language":"json","status":200,"name":"Success"},{"name":"Project Missing","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","language":"json","status":404},{"language":"json","status":403,"name":"No Project Access","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n"}]},"auth":"required","params":[{"_id":"56cf1ecb5267d70b00494ba9","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ecb5267d70b00494ba8","ref":"","in":"query","required":false,"desc":"Number of photos to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ecb5267d70b00494ba7","ref":"","in":"query","required":false,"desc":"Number of photos to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"56edb744949cc23200837277","ref":"","in":"query","required":false,"desc":"Only retrieve photos created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"datetime","name":"updated_after"}],"url":"/projects/:project_uid/photos"},"isReference":false,"order":3,"body":"","excerpt":"Get a list of photos in a project optionally filtered by folder. Results return deleted photos and are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-photos-in-a-project","type":"get","title":"Retrieve Photos in a Project","__v":0,"childrenPages":[]}
getRetrieve Photos in a Project
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
"title": "Bongo Drums",
"url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
"created_at": "2013-05-17T02:30:22Z",
"created_by": {
"uid": null,
"url": null,
"email": "nick@subcontractor.com"
},
"deleted": false
},
{
"uid": "9acc66f0-b704-4469-99fa-c13ce2b0bf0a",
"title": "Bass Guitar",
"url": "https://photo-assets.plangrid.com/9acc66f0-b704-4469-99fa-c13ce2b0bf0a.jpg",
"created_at": "2013-05-13T04:30:22Z",
"created_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "betty@construction.com"
},
"deleted": false
}
],
"total_count": 14,
"next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/photos?skip=2&limit=2"
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{"_id":"5a0487c11058cd003cfb7b0d","category":"5a0487bf1058cd003cfb7aa6","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T20:39:44.322Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"name":"Success","code":"{\n \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n \"title\": \"Bongo Drums\",\n \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n \"created_at\": \"2013-05-17T02:30:22+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"nick@subcontractor.com\"\n },\n \"deleted\": false\n}\n","language":"json"},{"language":"json","status":404,"name":"Project Missing","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n"},{"status":404,"name":"Photo Missing","code":"{\n \"message\": \"Photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","language":"json"},{"status":403,"name":"No Project Access","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","language":"json"}]},"settings":"","examples":{"codes":[]},"method":"get","auth":"required","params":[{"_id":"56cf1ecb5267d70b00494ba6","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ecb5267d70b00494ba5","ref":"","in":"path","required":true,"desc":"Unique identifier of photo.","default":"","type":"string","name":"photo_uid"}],"url":"/projects/:project_uid/photos/:photo_uid"},"isReference":false,"order":4,"body":"","excerpt":"Get a photo in a project.","slug":"retrieve-photo-in-a-project","type":"get","title":"Retrieve Photo in a Project","__v":0,"childrenPages":[]}
getRetrieve Photo in a Project
Path Params
Definition
Result Format
{
"uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
"title": "Bongo Drums",
"url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
"created_at": "2013-05-17T02:30:22+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "nick@subcontractor.com"
},
"deleted": false
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{"_id":"5a0487c11058cd003cfb7b0e","category":"5a0487bf1058cd003cfb7aa6","user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-20T22:34:36.424Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","examples":{"codes":[]},"method":"patch","results":{"codes":[{"language":"json","code":"{\n \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n \"title\": \"Bongo Drums\",\n \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n \"created_at\": \"2013-05-17T02:30:22+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"nick@subcontractor.com\"\n },\n \"deleted\": false\n}\n","name":"Success","status":200},{"language":"json","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","name":"Project Missing","status":404},{"language":"json","code":"{\n \"message\": \"Photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"Photo Missing","status":404},{"language":"json","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","name":"No Project Access","status":403},{"code":"{\n \"message\": \"Insufficient permissions to update photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) in project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","language":"json","status":403,"name":"Insufficient Permissions"},{"name":"Invalid Title","status":400,"language":"json","code":"{\n \"message\": \"Title (2) must be a string at least one character long.\"\n}"},{"status":400,"name":"Photo Deleted","code":"{\n \"message\": \"Photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) is deleted and cannot be updated.\"\n}","language":"json"}]},"auth":"required","params":[{"_id":"56cf1ecb5267d70b00494ba6","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ecb5267d70b00494ba5","ref":"","in":"path","required":true,"desc":"Unique identifier of photo.","default":"","type":"string","name":"photo_uid"},{"_id":"56ef2704aff1620e00a3235b","ref":"","in":"body","required":false,"desc":"New title of the photo.","default":"","type":"string","name":"title"}],"url":"/projects/:project_uid/photos/:photo_uid"},"isReference":false,"order":5,"body":"","excerpt":"Update a photo's metadata. If you want to change the photo's file, you'll need to delete the photo and upload a new one.","slug":"update-photo-in-a-project","type":"patch","title":"Update Photo in a Project","__v":0,"childrenPages":[]}
patchUpdate Photo in a Project
Path Params
Body Params
Definition
Result Format
{
"uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
"title": "Bongo Drums",
"url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
"created_at": "2013-05-17T02:30:22+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "nick@subcontractor.com"
},
"deleted": false
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{
"message": "Insufficient permissions to update photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) in project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Title (2) must be a string at least one character long."
}
{
"message": "Photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) is deleted and cannot be updated."
}
{"_id":"5a0487c11058cd003cfb7b0f","category":"5a0487bf1058cd003cfb7aa6","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-20T21:52:22.949Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","examples":{"codes":[]},"method":"delete","results":{"codes":[{"status":204,"language":"json","code":" ","name":""},{"status":404,"language":"json","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}","name":"Project Missing"},{"language":"json","code":"{\n \"message\": \"Photo (87658a3f-8ee0-4188-9c55-b06a203fa9e7) was not found in project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","status":404,"name":"Photo Missing"},{"status":403,"language":"json","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}","name":"No Project Access"}]},"auth":"required","params":[{"_id":"56ef222ba5bcfd0e00951766","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56ef2236aff1620e00a32356","ref":"","in":"path","required":true,"desc":"Unique identifier of photo.","default":"","type":"string","name":"photo_uid"}],"url":"/projects/:project_uid/photos/:photo_uid"},"isReference":false,"order":6,"body":"","excerpt":"Removes a photo from a project. If photo has already been removed, a `204` is still returned. See [Deleted Records](doc:deleted-records) for details on deleted records.","slug":"remove-photo-from-project","type":"delete","title":"Remove Photo from Project","__v":1,"childrenPages":[]}
deleteRemove Photo from Project
Path Params
Definition
Result Format
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Photo (87658a3f-8ee0-4188-9c55-b06a203fa9e7) was not found in project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}
{"_id":"5a0487bf1058cd003cfb7ab9","category":"5a0487bf1058cd003cfb7aa7","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2015-10-24T16:42:36.371Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"name":"","code":"{}","language":"json"},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":0,"body":"[block:parameters]\n{\n \"data\": {\n \"0-0\": \"**uid**\\n`string`\",\n \"0-1\": \"Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n \"1-0\": \"**number**\\n`integer`\",\n \"2-0\": \"**status**\\n`object`\",\n \"3-0\": \"**locked**\\n`boolean`\",\n \"4-0\": \"**title**\\n`string`\",\n \"6-0\": \"**answer**\\n`string`\",\n \"7-0\": \"**assigned_to**\\n`array`\",\n \"10-0\": \"**created_at**\\n`string`\",\n \"11-0\": \"**created_by**\\n`object`\",\n \"12-0\": \"**updated_at**\\n`string`\",\n \"13-0\": \"**updated_by**\\n`object`\",\n \"1-1\": \"RFI number assigned by PlanGrid. May not be unique. Never blank.\",\n \"2-1\": \"An RFI status. See [The RFI Status Object](doc:the-rfi-status-object) for attribute details. Never blank.\",\n \"3-1\": \"Whether the RFI is locked. Never blank.\",\n \"4-1\": \"Cannot exceed 200 characters.\",\n \"6-1\": \"Cannot exceed 10,000 characters.\",\n \"7-1\": \"An array of references to PlanGrid users RFI is assigned to. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"10-1\": \"When the RFI was created by a client application. UTC date and time in ISO-8601 format.\",\n \"11-1\": \"Reference to PlanGrid user that created RFI. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"12-1\": \"When the RFI was updated by a PlanGrid client. Modifying references or adding comments updates `updated_at`. UTC date and time in ISO-8601 format.\",\n \"13-1\": \"Reference to PlanGrid user that last updated RFI. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"5-0\": \"**question**\\n`string`\",\n \"5-1\": \"Cannot exceed 10,000 characters.\",\n \"8-0\": \"**sent_at**\\n`string`\",\n \"9-0\": \"**due_at**\\n`string`\",\n \"8-1\": \"When the RFI was sent. UTC date and time in ISO-8601 format.\",\n \"9-1\": \"When the RFI is due. UTC date and time in ISO-8601 format.\",\n \"14-0\": \"**photos**\\n`object`\",\n \"14-1\": \"Reference to collection of photos on RFI. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"15-0\": \"**snapshots**\\n`object`\",\n \"16-0\": \"**attachments**\\n`object`\",\n \"15-1\": \"Reference to collection of snapshots on RFI. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"16-1\": \"Reference to collection of documents on RFI. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"17-0\": \"**comments**\\n`object`\",\n \"17-1\": \"Reference to collection of comments on RFI. See [Foreign Keys](doc:foreign-keys) for attribute details.\"\n },\n \"cols\": 2,\n \"rows\": 18\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"uid\\\": \\\"22f3530a-a00b-42f9-8139-3a7554c77c27\\\",\\n \\\"number\\\": 1,\\n \\\"status\\\": {\\n \\\"uid\\\": \\\"4898bfd4\\\",\\n \\\"label\\\": \\\"closed\\\",\\n \\\"color\\\": \\\"#000000\\\"\\n },\\n \\\"sent_at\\\": \\\"2015-10-20T19:22:56+00:00\\\",\\n \\\"due_at\\\": \\\"2015-10-24T19:22:56+00:00\\\",\\n \\\"locked\\\": true,\\n \\\"title\\\": \\\"Door heights do not match.\\\",\\n \\\"question\\\": \\\"Door heights on A1.01 and A2.02 do not match each other.\\\",\\n \\\"answer\\\": \\\"Door height is 100' high.\\\",\\n \\\"assigned_to\\\": [\\n {\\n \\\"uid\\\": \\\"80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\\\", \\n \\\"email\\\": \\\"bob@subcontractor.com\\\"\\n },\\n {\\n \\\"uid\\\": \\\"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\\\",\\n \\\"email\\\": \\\"alfred@architect.com\\\"\\n }\\n ],\\n \\\"created_at\\\": \\\"2015-06-08T18:04:02+00:00\\\",\\n \\\"created_by\\\": {\\n \\\"uid\\\": \\\"73ec5368-48aa-4dba-ba55-7e438a01b8d2\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2\\\",\\n \\\"email\\\": \\\"betty@construction.com\\\"\\n },\\n \\\"updated_at\\\": \\\"2013-05-23T19:22:56+00:00\\\",\\n \\\"updated_by\\\": {\\n \\\"uid\\\": \\\"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\\\",\\n \\\"email\\\": \\\"alfred@architect.com\\\"\\n },\\n \\\"photos\\\": {\\n \\\"total_count\\\": 0,\\n \\\"url\\\": null\\n },\\n \\\"attachments\\\": {\\n \\\"total_count\\\": 4,\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/attachments\\\"\\n },\\n \\\"snapshots\\\": {\\n \\\"total_count\\\": 2,\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots\\\"\\n },\\n \\\"comments\\\": {\\n \\\"total_count\\\": 2,\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments\\\"\\n }\\n}\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-rfi-object","type":"basic","title":"The RFI Object","__v":0,"childrenPages":[]}
The RFI Object
uidstring
Never blank. See Unique Identifiers for details.
numberinteger
RFI number assigned by PlanGrid. May not be unique. Never blank.
statusobject
An RFI status. See The RFI Status Object for attribute details. Never blank.
lockedboolean
Whether the RFI is locked. Never blank.
titlestring
Cannot exceed 200 characters.
questionstring
Cannot exceed 10,000 characters.
answerstring
Cannot exceed 10,000 characters.
assigned_toarray
An array of references to PlanGrid users RFI is assigned to. See Foreign Keys for attribute details.
sent_atstring
When the RFI was sent. UTC date and time in ISO-8601 format.
due_atstring
When the RFI is due. UTC date and time in ISO-8601 format.
created_atstring
When the RFI was created by a client application. UTC date and time in ISO-8601 format.
created_byobject
Reference to PlanGrid user that created RFI. See Foreign Keys for attribute details.
updated_atstring
When the RFI was updated by a PlanGrid client. Modifying references or adding comments updates updated_at
. UTC date and time in ISO-8601 format.
updated_byobject
Reference to PlanGrid user that last updated RFI. See Foreign Keys for attribute details.
photosobject
Reference to collection of photos on RFI. See Foreign Keys for attribute details.
snapshotsobject
Reference to collection of snapshots on RFI. See Foreign Keys for attribute details.
attachmentsobject
Reference to collection of documents on RFI. See Foreign Keys for attribute details.
commentsobject
Reference to collection of comments on RFI. See Foreign Keys for attribute details.
{
"uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
"number": 1,
"status": {
"uid": "4898bfd4",
"label": "closed",
"color": "#000000"
},
"sent_at": "2015-10-20T19:22:56+00:00",
"due_at": "2015-10-24T19:22:56+00:00",
"locked": true,
"title": "Door heights do not match.",
"question": "Door heights on A1.01 and A2.02 do not match each other.",
"answer": "Door height is 100' high.",
"assigned_to": [
{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "bob@subcontractor.com"
},
{
"uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"email": "alfred@architect.com"
}
],
"created_at": "2015-06-08T18:04:02+00:00",
"created_by": {
"uid": "73ec5368-48aa-4dba-ba55-7e438a01b8d2",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2",
"email": "betty@construction.com"
},
"updated_at": "2013-05-23T19:22:56+00:00",
"updated_by": {
"uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"email": "alfred@architect.com"
},
"photos": {
"total_count": 0,
"url": null
},
"attachments": {
"total_count": 4,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/attachments"
},
"snapshots": {
"total_count": 2,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots"
},
"comments": {
"total_count": 2,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments"
}
}
{"_id":"5a0487bf1058cd003cfb7aba","category":"5a0487bf1058cd003cfb7aa7","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-02T01:49:35.778Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":1,"body":"[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"0-0\": \"**field**\\n`string`\",\n \"0-1\": \"Field that was updated. Adding a photo, attachment, or snapshot as a references results in a `field` value of `photos`, `attachments`, or `snapshots`, respectively.\",\n \"1-0\": \"**old_value**\\n`string`, `array`, `object`, `null`\",\n \"1-1\": \"The previous value before this update. When `status` is changed, `old_value` is a [RFI Status Object](doc:the-rfi-status-object). When `assigned_to` is changed, `old_value` is an array of UserPointers. When references are changed, `old_value` is an array of Pointers. See [Foreign Keys](doc:foreign-keys) for more on UserPointers and Pointers.\",\n \"4-0\": \"**updated_by**\\n`object`\",\n \"4-1\": \"Reference to PlanGrid user that made this update. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"3-0\": \"**updated_at**\\n`string`\",\n \"3-1\": \"When the RFI was updated by a PlanGrid client. UTC date and time in ISO-8601 format.\",\n \"2-0\": \"**new_value**\\n`string`, `array`, `object`, `null`\",\n \"2-1\": \"The new value after this update. When `status` is changed, `new_value` is a [RFI Status Object](doc:the-rfi-status-object). When `assigned_to` is changed, `new_value` is an array of UserPointers. When references are changed, `new_value` is an array of Pointers. See [Foreign Keys](doc:foreign-keys) for more on UserPointers and Pointers.\"\n },\n \"cols\": 2,\n \"rows\": 5\n}\n[/block]\n\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"field\\\": \\\"assigned_to\\\",\\n \\\"old_value\\\": [\\n {\\n \\\"uid\\\": \\\"80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n \\\"email\\\": \\\"bob@subcontractor.com\\\"\\n }\\n ],\\n \\\"new_value\\\": [\\n {\\n \\\"uid\\\": \\\"80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n \\\"email\\\": \\\"bob@subcontractor.com\\\"\\n },\\n {\\n \\\"uid\\\": \\\"80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n \\\"email\\\": \\\"betty@construction.com\\\"\\n }\\n ],\\n \\\"updated_at\\\": \\\"2013-05-11T05:25:11+00:00\\\",\\n \\\"updated_by\\\": {\\n \\\"uid\\\": \\\"80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n \\\"email\\\": \\\"betty@construction.com\\\"\\n }\\n}\",\n \"language\": \"json\"\n }\n ],\n \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-rfi-history-object","type":"basic","title":"The RFI History Object","__v":0,"childrenPages":[]}
The RFI History Object
fieldstring
Field that was updated. Adding a photo, attachment, or snapshot as a references results in a field
value of photos
, attachments
, or snapshots
, respectively.
old_valuestring
, array
, object
, null
The previous value before this update. When status
is changed, old_value
is a RFI Status Object. When assigned_to
is changed, old_value
is an array of UserPointers. When references are changed, old_value
is an array of Pointers. See Foreign Keys for more on UserPointers and Pointers.
new_valuestring
, array
, object
, null
The new value after this update. When status
is changed, new_value
is a RFI Status Object. When assigned_to
is changed, new_value
is an array of UserPointers. When references are changed, new_value
is an array of Pointers. See Foreign Keys for more on UserPointers and Pointers.
updated_atstring
When the RFI was updated by a PlanGrid client. UTC date and time in ISO-8601 format.
updated_byobject
Reference to PlanGrid user that made this update. See Foreign Keys for attribute details.
{
"field": "assigned_to",
"old_value": [
{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "bob@subcontractor.com"
}
],
"new_value": [
{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "bob@subcontractor.com"
},
{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "betty@construction.com"
}
],
"updated_at": "2013-05-11T05:25:11+00:00",
"updated_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "betty@construction.com"
}
}
{"_id":"5a0487bf1058cd003cfb7abb","category":"5a0487bf1058cd003cfb7aa7","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:38:33.841Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"name":"","status":200,"language":"json","code":"{\n \"uid\": \"22f3530a-a00b-42f9-8139-3a7554c77c27\",\n \"number\": 1,\n \"status\": {\n \"uid\": \"4898bfd4\",\n \"label\": \"closed\",\n \"color\": \"#000000\"\n },\n \"locked\": true,\n \"title\": \"Door heights do not match.\",\n \"question\": \"Door heights on A1.01 and A2.02 do not match each other.\",\n \"answer\": \"Door height is 100' high.\",\n \"sent_at\": \"2015-10-20T18:04:02+00:00\",\n \"due_at\": \"2015-10-24T18:04:02+00:00\",\n \"assigned_to\": [\n {\n \"uid\": \"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n \"email\": \"alfred@architect.com\"\n }\n ],\n \"updated_at\": \"2015-06-08T18:04:02+00:00\",\n \"updated_by\": {\n \"uid\": \"73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n \"email\": \"betty@construction.com\"\n },\n \"created_at\": \"2015-06-08T18:04:02+00:00\",\n \"created_by\": {\n \"uid\": \"73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n \"email\": \"betty@construction.com\"\n },\n \"photos\": {\n \"total_count\": 0,\n \"url\": null\n },\n \"attachments\": {\n \"total_count\": 0,\n \"url\": null\n },\n \"snapshots\": {\n \"total_count\": 0,\n \"url\": null\n },\n \"comments\": {\n \"total_count\": 0,\n \"url\": null\n }\n}"},{"name":"Invalid Status","status":400,"language":"json","code":"{\n \"message\": \"Status (4898bfd4) must be a valid RFI status on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}"},{"language":"json","code":"{\n \"message\": \"Locked must be a boolean.\"\n}","status":400,"name":"Invalid Locked"},{"name":"Invalid Title","status":400,"language":"json","code":"{\n \"message\": \"Title (2) must be null or a string.\"\n}"},{"name":"Title Length","status":400,"language":"json","code":"{\n \"message\": \"RFI title cannot exceed 200 characters.\"\n}"},{"name":"Invalid Question","status":400,"language":"json","code":"{\n \"message\": \"Question (10) must be null or a string.\"\n}"},{"language":"json","code":"{\n \"message\": \"RFI question cannot exceed 10000 characters.\"\n}","status":400,"name":"Question Length"},{"code":"{\n \"message\": \"Answer (3) must be null or a string.\"\n}","name":"Invalid Answer","status":400,"language":"json"},{"language":"json","code":"{\n \"message\": \"RFI answer cannot exceed 10000 characters.\"\n}","status":400,"name":"Answer Length"},{"status":400,"language":"json","code":"{\n \"message\": \"Sent at (2015-9-2) must be null or a datetime in ISO-8601 format.\"\n}","name":"Invalid Sent At"},{"language":"json","code":"{\n \"message\": \"Due date (2015-9-2) must be null or a datetime in ISO-8601 format.\"\n}","status":400,"name":"Invalid Due At"},{"code":"{\n \"message\": \"Assignees ([0, bb29c783-bfb7-4664-8362-ba2ca716cade]) must be an array of UIDs of users on project.\"\n}","language":"json","status":400,"name":"Invalid Assigned To"},{"status":400,"language":"json","code":"{\n \"message\": \"Assignee (9003a891-8a49-4c91-9682-668b1a8a4241) is not on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","name":"Assignee Missing"},{"code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}","language":"text","name":"No Access","status":403}]},"settings":"","examples":{"codes":[]},"method":"post","auth":"required","params":[{"_id":"56edc6d9fc1410200082dc97","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56edc6d9fc1410200082dc96","ref":"","in":"body","required":false,"desc":"Unique identifier of the RFI's initial status. Defaults to the first RFI status in the project.","default":"","type":"string","name":"status"},{"_id":"56edc6d9fc1410200082dc95","ref":"","in":"body","required":false,"desc":"Whether the RFI is locked.","default":"false","type":"boolean","name":"locked"},{"_id":"56edc6d9fc1410200082dc94","ref":"","in":"body","required":false,"desc":"The RFI title.","default":"null","type":"string","name":"title"},{"_id":"56edc6d9fc1410200082dc93","ref":"","in":"body","required":false,"desc":"The RFI question.","default":"null","type":"string","name":"question"},{"_id":"56edc6d9fc1410200082dc92","ref":"","in":"body","required":false,"desc":"The RFI answer.","default":"null","type":"string","name":"answer"},{"_id":"56edc6d9fc1410200082dc91","ref":"","in":"body","required":false,"desc":"Date when the RFI was sent. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"null","type":"datetime","name":"sent_at"},{"_id":"56edc6d9fc1410200082dc90","ref":"","in":"body","required":false,"desc":"Date when the RFI is due. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"null","type":"datetime","name":"due_at"},{"_id":"56edc6d9fc1410200082dc8f","ref":"","in":"body","required":false,"desc":"Array of unique identifiers of users who are RFI assignees.","default":"null","type":"array_string","name":"assigned_to_uids"}],"url":"/projects/:project_uid/rfis"},"isReference":false,"order":2,"body":"","excerpt":"Creates an RFI on a project and sends appropriate notifications (e.g. to assignees). At least one field must be provided to successfully create an RFI.","slug":"create-rfi-in-a-project","type":"post","title":"Create RFI in a Project","__v":0,"childrenPages":[]}
postCreate RFI in a Project
Path Params
Body Params
Definition
Result Format
{
"uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
"number": 1,
"status": {
"uid": "4898bfd4",
"label": "closed",
"color": "#000000"
},
"locked": true,
"title": "Door heights do not match.",
"question": "Door heights on A1.01 and A2.02 do not match each other.",
"answer": "Door height is 100' high.",
"sent_at": "2015-10-20T18:04:02+00:00",
"due_at": "2015-10-24T18:04:02+00:00",
"assigned_to": [
{
"uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"email": "alfred@architect.com"
}
],
"updated_at": "2015-06-08T18:04:02+00:00",
"updated_by": {
"uid": "73ec5368-48aa-4dba-ba55-7e438a01b8d2",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2",
"email": "betty@construction.com"
},
"created_at": "2015-06-08T18:04:02+00:00",
"created_by": {
"uid": "73ec5368-48aa-4dba-ba55-7e438a01b8d2",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2",
"email": "betty@construction.com"
},
"photos": {
"total_count": 0,
"url": null
},
"attachments": {
"total_count": 0,
"url": null
},
"snapshots": {
"total_count": 0,
"url": null
},
"comments": {
"total_count": 0,
"url": null
}
}
{
"message": "Status (4898bfd4) must be a valid RFI status on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Locked must be a boolean."
}
{
"message": "Title (2) must be null or a string."
}
{
"message": "RFI title cannot exceed 200 characters."
}
{
"message": "Question (10) must be null or a string."
}
{
"message": "RFI question cannot exceed 10000 characters."
}
{
"message": "Answer (3) must be null or a string."
}
{
"message": "RFI answer cannot exceed 10000 characters."
}
{
"message": "Sent at (2015-9-2) must be null or a datetime in ISO-8601 format."
}
{
"message": "Due date (2015-9-2) must be null or a datetime in ISO-8601 format."
}
{
"message": "Assignees ([0, bb29c783-bfb7-4664-8362-ba2ca716cade]) must be an array of UIDs of users on project."
}
{
"message": "Assignee (9003a891-8a49-4c91-9682-668b1a8a4241) is not on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{"_id":"5a0487bf1058cd003cfb7abc","category":"5a0487bf1058cd003cfb7aa7","user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:14:20.678Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"language":"json","status":200,"name":"Success","code":"{\n \"data\": [\n {\n \"uid\": \"22f3530a-a00b-42f9-8139-3a7554c77c27\",\n \"number\": 1,\n \"status\": {\n \"uid\": \"4898bfd4\",\n \"label\": \"closed\",\n \"color\": \"#000000\"\n },\n \"locked\": true,\n \"title\": \"Door heights do not match.\",\n \"question\": \"Door heights on A1.01 and A2.02 do not match each other.\",\n \"answer\": \"Door height is 100' high.\",\n \"sent_at\": \"2015-10-20T19:22:56+00:00\",\n \"due_at\": \"2015-10-24T19:22:56+00:00\",\n \"assigned_to\": [\n {\n \"uid\": \"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n \"email\": \"alfred@architect.com\"\n }\n ],\n \"updated_at\": \"2013-05-23T19:22:56+00:00\",\n \"updated_by\": {\n \"uid\": \"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n \"email\": \"alfred@architect.com\"\n },\n \"created_at\": \"2015-06-08T18:04:02+00:00\",\n \"created_by\": {\n \"uid\": \"73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n \"email\": \"betty@construction.com\"\n },\n \"photos\": {\n \"total_count\": 0,\n \"url\": null\n },\n \"attachments\": {\n \"total_count\": 1,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/attachments\"\n },\n \"snapshots\": {\n \"total_count\": 1,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots\"\n },\n \"comments\": {\n \"total_count\": 2,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments\"\n }\n },\n {\n \"uid\": \"51cb7310-6feb-47ae-8ad9-a89ac6101294\",\n \"number\": 2,\n \"status\": {\n \"uid\": \"0a83939c\",\n \"label\": \"open\",\n \"color\": \"#FF0000\"\n },\n \"title\": \"Toilet won't fit\",\n \"question\": \"Toilet will not fit with current dimensions of bathroom\",\n \"answer\": null,\n \"sent_at\": \"2015-9-12T19:22:56+00:00\",\n \"due_at\": \"2015-9-14T19:22:56+00:00\",\n \"assigned_to\": [\n {\n \"uid\": \"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"bob@subcontractor.com\"\n },\n {\n \"uid\": \"e5eb1338-e8c0-4a1a-8191-bcc082a8bc96\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/e5eb1338-e8c0-4a1a-8191-bcc082a8bc96\",\n \"email\": \"stacy@civilengineer.com\"\n }\n ],\n \"updated_at\": \"2013-05-23T19:22:56+00:00\",\n \"updated_by\": {\n \"uid\": \"e5eb1338-e8c0-4a1a-8191-bcc082a8bc96\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/e5eb1338-e8c0-4a1a-8191-bcc082a8bc96\",\n \"email\": \"stacy@civilengineer.com\"\n },\n \"created_at\": \"2015-06-08T18:04:02+00:00\",\n \"created_by\": {\n \"uid\": \"73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n \"email\": \"betty@construction.com\"\n },\n \"photos\": {\n \"total_count\": 1,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/photos\"\n },\n \"attachments\": {\n \"total_count\": 0,\n \"url\": null\n },\n \"snapshots\": {\n \"total_count\": 1,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots\"\n },\n \"comments\": {\n \"total_count\": 2,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments\"\n }\n }\n ],\n \"total_count\": 50,\n \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis?skip=2&limit=2\"\n}\n"},{"code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","language":"json","status":404,"name":"Missing"},{"name":"No Access","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","language":"json","status":403}]},"settings":"","auth":"required","params":[{"_id":"56cf1ed05267d70b00494bd7","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ed05267d70b00494bd6","ref":"","in":"query","required":false,"desc":"Number of RFIs to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ed05267d70b00494bd5","ref":"","in":"query","required":false,"desc":"Number of RFIs to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"56edc361949cc23200837284","ref":"","in":"query","required":false,"desc":"Only retrieve RFIs created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"timestamp","name":"updated_after"}],"url":"/projects/:project_uid/rfis"},"isReference":false,"order":3,"body":"","excerpt":"Get a list of RFIs in a project. Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-rfis-in-a-project","type":"get","title":"Retrieve RFIs in a Project","__v":0,"childrenPages":[]}
getRetrieve RFIs in a Project
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
"number": 1,
"status": {
"uid": "4898bfd4",
"label": "closed",
"color": "#000000"
},
"locked": true,
"title": "Door heights do not match.",
"question": "Door heights on A1.01 and A2.02 do not match each other.",
"answer": "Door height is 100' high.",
"sent_at": "2015-10-20T19:22:56+00:00",
"due_at": "2015-10-24T19:22:56+00:00",
"assigned_to": [
{
"uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"email": "alfred@architect.com"
}
],
"updated_at": "2013-05-23T19:22:56+00:00",
"updated_by": {
"uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"email": "alfred@architect.com"
},
"created_at": "2015-06-08T18:04:02+00:00",
"created_by": {
"uid": "73ec5368-48aa-4dba-ba55-7e438a01b8d2",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2",
"email": "betty@construction.com"
},
"photos": {
"total_count": 0,
"url": null
},
"attachments": {
"total_count": 1,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/attachments"
},
"snapshots": {
"total_count": 1,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots"
},
"comments": {
"total_count": 2,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments"
}
},
{
"uid": "51cb7310-6feb-47ae-8ad9-a89ac6101294",
"number": 2,
"status": {
"uid": "0a83939c",
"label": "open",
"color": "#FF0000"
},
"title": "Toilet won't fit",
"question": "Toilet will not fit with current dimensions of bathroom",
"answer": null,
"sent_at": "2015-9-12T19:22:56+00:00",
"due_at": "2015-9-14T19:22:56+00:00",
"assigned_to": [
{
"uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "bob@subcontractor.com"
},
{
"uid": "e5eb1338-e8c0-4a1a-8191-bcc082a8bc96",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/e5eb1338-e8c0-4a1a-8191-bcc082a8bc96",
"email": "stacy@civilengineer.com"
}
],
"updated_at": "2013-05-23T19:22:56+00:00",
"updated_by": {
"uid": "e5eb1338-e8c0-4a1a-8191-bcc082a8bc96",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/e5eb1338-e8c0-4a1a-8191-bcc082a8bc96",
"email": "stacy@civilengineer.com"
},
"created_at": "2015-06-08T18:04:02+00:00",
"created_by": {
"uid": "73ec5368-48aa-4dba-ba55-7e438a01b8d2",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2",
"email": "betty@construction.com"
},
"photos": {
"total_count": 1,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/photos"
},
"attachments": {
"total_count": 0,
"url": null
},
"snapshots": {
"total_count": 1,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots"
},
"comments": {
"total_count": 2,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments"
}
}
],
"total_count": 50,
"next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis?skip=2&limit=2"
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{"_id":"5a0487bf1058cd003cfb7abd","category":"5a0487bf1058cd003cfb7aa7","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:15:08.934Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{\n \"uid\": \"22f3530a-a00b-42f9-8139-3a7554c77c27\",\n \"number\": 1,\n \"status\": {\n \"uid\": \"4898bfd4\",\n \"label\": \"closed\",\n \"color\": \"#000000\"\n },\n \"locked\": true,\n \"title\": \"Door heights do not match.\",\n \"question\": \"Door heights on A1.01 and A2.02 do not match each other.\",\n \"answer\": \"Door height is 100' high.\",\n \"sent_at\": \"2015-10-20T19:22:56+00:00\",\n \"due_at\": \"2015-10-24T19:22:56+00:00\",\n \"assigned_to\": [\n {\n \"uid\": \"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n \"email\": \"alfred@architect.com\"\n }\n ],\n \"updated_at\": \"2013-05-23T19:22:56+00:00\",\n \"updated_by\": {\n \"uid\": \"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n \"email\": \"alfred@architect.com\"\n },\n \"created_at\": \"2015-06-08T18:04:02+00:00\",\n \"created_by\": {\n \"uid\": \"73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n \"email\": \"betty@construction.com\"\n },\n \"photos\": {\n \"total_count\": 0,\n \"url\": null\n },\n \"attachments\": {\n \"total_count\": 1,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/attachments\"\n },\n \"snapshots\": {\n \"total_count\": 1,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots\"\n },\n \"comments\": {\n \"total_count\": 2,\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments\"\n }\n}\n","name":"Success"},{"language":"json","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","name":"Project Missing","status":404},{"name":"RFI Missing","status":404,"language":"json","code":"{\n \"message\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n"},{"language":"json","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","name":"No Access","status":403}]},"settings":"","examples":{"codes":[]},"method":"get","auth":"required","params":[{"_id":"56cf1ecd5267d70b00494bbd","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ecd5267d70b00494bbc","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI to retrieve.","default":"","type":"string","name":"rfi_uid"}],"url":"/projects/:project_uid/rfis/:rfi_uid"},"isReference":false,"order":4,"body":"","excerpt":"Get an RFI in a project.","slug":"retrieve-rfi-in-a-project","type":"get","title":"Retrieve RFI in a Project","__v":0,"childrenPages":[]}
getRetrieve RFI in a Project
Path Params
Definition
Result Format
{
"uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
"number": 1,
"status": {
"uid": "4898bfd4",
"label": "closed",
"color": "#000000"
},
"locked": true,
"title": "Door heights do not match.",
"question": "Door heights on A1.01 and A2.02 do not match each other.",
"answer": "Door height is 100' high.",
"sent_at": "2015-10-20T19:22:56+00:00",
"due_at": "2015-10-24T19:22:56+00:00",
"assigned_to": [
{
"uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"email": "alfred@architect.com"
}
],
"updated_at": "2013-05-23T19:22:56+00:00",
"updated_by": {
"uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"email": "alfred@architect.com"
},
"created_at": "2015-06-08T18:04:02+00:00",
"created_by": {
"uid": "73ec5368-48aa-4dba-ba55-7e438a01b8d2",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2",
"email": "betty@construction.com"
},
"photos": {
"total_count": 0,
"url": null
},
"attachments": {
"total_count": 1,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/attachments"
},
"snapshots": {
"total_count": 1,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots"
},
"comments": {
"total_count": 2,
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments"
}
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{"_id":"5a0487bf1058cd003cfb7abe","category":"5a0487bf1058cd003cfb7aa7","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:17:26.943Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"status":200,"name":"Success","code":"{\n \"data\": [\n {\n \"uid\": \"147a420e-a182-4312-8fa5-4d10064d2f1a\",\n \"name\": \"Bender\",\n \"folder\": \"Specifications\",\n \"url\": \"https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf\",\n \"created_at\": \"2013-05-17T02:30:22+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"nick@subcontractor.com\"\n },\n \"deleted\": false\n },\n {\n \"uid\": \"40f38b8b-019e-44d8-8cb8-86454c327fb5\",\n \"name\": \"Cement\",\n \"folder\": \"Submittals\",\n \"url\": \"https://attachment-assets.plangrid.com/40f38b8b-019e-44d8-8cb8-86454c327fb5.pdf\",\n \"created_at\": \"2013-05-13T04:30:22+00:00\",\n \"created_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"betty@construction.com\"\n },\n \"deleted\": true\n }\n ],\n \"total_count\": 14,\n \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/attachments?skip=2&limit=2\"\n}\n","language":"json"},{"name":"Project Missing","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","language":"json","status":404},{"language":"json","status":404,"name":"RFI Missing","code":"{\n \"message\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n"},{"code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}\n","language":"json","status":403,"name":"No Project Access"}]},"settings":"","auth":"required","params":[{"_id":"56cf1ece5267d70b00494bc1","ref":"","in":"path","required":true,"desc":"Unique identifier for RFI's project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ece5267d70b00494bc0","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI.","default":"","type":"string","name":"rfi_uid"},{"_id":"56cf1ece5267d70b00494bbf","ref":"","in":"query","required":false,"desc":"Number of attachments to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ece5267d70b00494bbe","ref":"","in":"query","required":false,"desc":"Number of attachments to skip in the set of results.","default":"0","type":"int","name":"skip"}],"url":"/projects/:project_uid/rfis/:rfi_uid/attachments"},"isReference":false,"order":5,"body":"","excerpt":"Get a list of documents referenced in an RFI. Document data is described in [The Document Object](doc:the-attachment-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-attachments-referenced-in-rfi","type":"get","title":"Retrieve Documents Referenced in RFI","__v":0,"childrenPages":[]}
getRetrieve Documents Referenced in RFI
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"uid": "147a420e-a182-4312-8fa5-4d10064d2f1a",
"name": "Bender",
"folder": "Specifications",
"url": "https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf",
"created_at": "2013-05-17T02:30:22+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "nick@subcontractor.com"
},
"deleted": false
},
{
"uid": "40f38b8b-019e-44d8-8cb8-86454c327fb5",
"name": "Cement",
"folder": "Submittals",
"url": "https://attachment-assets.plangrid.com/40f38b8b-019e-44d8-8cb8-86454c327fb5.pdf",
"created_at": "2013-05-13T04:30:22+00:00",
"created_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "betty@construction.com"
},
"deleted": true
}
],
"total_count": 14,
"next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/attachments?skip=2&limit=2"
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}
{"_id":"5a0487bf1058cd003cfb7abf","category":"5a0487bf1058cd003cfb7aa7","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:20:12.083Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"status":200,"name":"Success","code":"{\n \"data\": [\n {\n \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n \"title\": \"Bongo Drums\",\n \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n \"created_at\": \"2013-05-17T02:30:22+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"nick@subcontractor.com\"\n },\n \"deleted\": false\n },\n {\n \"uid\": \"9acc66f0-b704-4469-99fa-c13ce2b0bf0a\",\n \"title\": \"Bass Guitar\",\n \"url\": \"https://photo-assets.plangrid.com/9acc66f0-b704-4469-99fa-c13ce2b0bf0a.jpg\",\n \"created_at\": \"2013-05-13T04:30:22+00:00\",\n \"created_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"betty@construction.com\"\n },\n \"deleted\": false\n }\n ],\n \"total_count\": 14,\n \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos?skip=2&limit=2\"\n}\n","language":"json"},{"status":404,"name":"Project Missing","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","language":"json"},{"status":404,"name":"RFI Missing","code":"{\n \"message\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","language":"json"},{"name":"No Project Access","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}\n","language":"json","status":403}]},"settings":"","auth":"required","params":[{"_id":"56cf1ecf5267d70b00494bcd","ref":"","in":"path","required":true,"desc":"Unique identifier for RFI's project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ecf5267d70b00494bcc","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI.","default":"","type":"string","name":"rfi_uid"},{"_id":"56cf1ecf5267d70b00494bcb","ref":"","in":"query","required":false,"desc":"Number of photos to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ecf5267d70b00494bca","ref":"","in":"query","required":false,"desc":"Number of photos to skip in the set of results.","default":"0","type":"int","name":"skip"}],"url":"/projects/:project_uid/rfis/:rfi_uid/photos"},"isReference":false,"order":6,"body":"","excerpt":"Get a list of photos referenced in an RFI. Photo data is described in [The Photo Object](doc:the-photo-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-photos-referenced-in-rfi","type":"get","title":"Retrieve Photos Referenced in RFI","__v":0,"childrenPages":[]}
getRetrieve Photos Referenced in RFI
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
"title": "Bongo Drums",
"url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
"created_at": "2013-05-17T02:30:22+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "nick@subcontractor.com"
},
"deleted": false
},
{
"uid": "9acc66f0-b704-4469-99fa-c13ce2b0bf0a",
"title": "Bass Guitar",
"url": "https://photo-assets.plangrid.com/9acc66f0-b704-4469-99fa-c13ce2b0bf0a.jpg",
"created_at": "2013-05-13T04:30:22+00:00",
"created_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "betty@construction.com"
},
"deleted": false
}
],
"total_count": 14,
"next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos?skip=2&limit=2"
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}
{"_id":"5a0487bf1058cd003cfb7ac0","category":"5a0487bf1058cd003cfb7aa7","parentDoc":null,"user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:21:32.510Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"language":"json","code":"{\n \"data\": [\n {\n \"uid\": \"ee131be1-c1b1-4b81-93f6-6363516186f3\",\n \"title\": \"Area where toilet doesn't fit\",\n \"url\": \"https://snapshot-assets.plangrid.com/ee131be1-c1b1-4b81-93f6-6363516186f3.jpg\",\n \"created_at\": \"2013-05-17T02:30:22+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"nick@subcontractor.com\"\n },\n \"deleted\": false\n },\n {\n \"uid\": \"154f1ab0-0b31-4854-87d9-dbb772f5f388\",\n \"title\": \"Another area where toilet doesn't fit\",\n \"url\": \"https://snapshot-assets.plangrid.com/154f1ab0-0b31-4854-87d9-dbb772f5f388.jpg\",\n \"created_at\": \"2013-05-13T04:30:22+00:00\",\n \"created_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"betty@construction.com\"\n },\n \"deleted\": true\n }\n ],\n \"total_count\": 14,\n \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/snapshots?skip=2&limit=2\"\n}\n","name":"Success","status":200},{"code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","name":"Project Missing","status":404,"language":"json"},{"status":404,"language":"json","code":"{\n \"message\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"RFI Missing"},{"language":"json","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}\n","name":"No Project Access","status":403}]},"settings":"","examples":{"codes":[]},"method":"get","auth":"required","params":[{"_id":"56cf1ecf5267d70b00494bd1","ref":"","in":"path","required":true,"desc":"Unique identifier for RFI's project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ecf5267d70b00494bd0","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI.","default":"","type":"string","name":"rfi_uid"},{"_id":"56cf1ecf5267d70b00494bcf","ref":"","in":"query","required":false,"desc":"Number of snapshots to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ecf5267d70b00494bce","ref":"","in":"query","required":false,"desc":"Number of snapshots to skip in the set of results.","default":"0","type":"int","name":"skip"}],"url":"/projects/:project_uid/rfis/:rfi_uid/snapshots"},"isReference":false,"order":7,"body":"","excerpt":"Get a list of snapshots referenced in an RFI. Snapshot data is described in [The Snapshot Object](doc:the-snapshot-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-snapshots-referenced-in-rfi","type":"get","title":"Retrieve Snapshots Referenced in RFI","__v":0,"childrenPages":[]}
getRetrieve Snapshots Referenced in RFI
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"uid": "ee131be1-c1b1-4b81-93f6-6363516186f3",
"title": "Area where toilet doesn't fit",
"url": "https://snapshot-assets.plangrid.com/ee131be1-c1b1-4b81-93f6-6363516186f3.jpg",
"created_at": "2013-05-17T02:30:22+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "nick@subcontractor.com"
},
"deleted": false
},
{
"uid": "154f1ab0-0b31-4854-87d9-dbb772f5f388",
"title": "Another area where toilet doesn't fit",
"url": "https://snapshot-assets.plangrid.com/154f1ab0-0b31-4854-87d9-dbb772f5f388.jpg",
"created_at": "2013-05-13T04:30:22+00:00",
"created_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "betty@construction.com"
},
"deleted": true
}
],
"total_count": 14,
"next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/snapshots?skip=2&limit=2"
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}
{"_id":"5a0487bf1058cd003cfb7ac1","category":"5a0487bf1058cd003cfb7aa7","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:21:47.591Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"status":200,"name":"Success","code":"{\n \"data\": [\n {\n \"uid\": \"87658a3f-8ee0-4188-9c55-b06a203fa9e7\",\n \"text\": \"Those people are trying to kill us!\",\n \"created_at\": \"2013-05-17T02:30:22+00:00\",\n \"created_by\": {\n \"uid\": \"deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n \"email\": \"henry.jones@oxford.edu\"\n },\n \"record_type\": \"rfi\",\n \"record\": {\n \"uid\": \"c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\"\n }\n },\n {\n \"uid\": \"465abf98-accb-42cd-bd54-16f29e8447f2\",\n \"text\": \"I know, Dad!\",\n \"created_at\": \"2013-05-15T18:54:22+00:00\",\n \"created_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"indiana.jones@marshallcollege.edu\"\n },\n \"record_type\": \"rfi\",\n \"record\": {\n \"uid\": \"c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\"\n }\n },\n {\n \"uid\": \"08ea8b05-a99c-40a7-a312-fee360ad432a\",\n \"text\": \"This is a new experience for me.\",\n \"created_at\": \"2013-05-14T8:30:56+00:00\",\n \"created_by\": {\n \"uid\": \"deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n \"email\": \"henry.jones@oxford.edu\"\n },\n \"record_type\": \"rfi\",\n \"record\": {\n \"uid\": \"c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\"\n }\n },\n {\n \"uid\": \"68839690-e0aa-4751-aedf-e630b921e91e\",\n \"text\": \"It happens to me all the time.\",\n \"created_at\": \"2013-05-13T11:22:56+00:00\",\n \"created_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"indiana.jones@marshallcollege.edu\"\n },\n \"record_type\": \"rfi\",\n \"record\": {\n \"uid\": \"c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\"\n }\n }\n ],\n \"total_count\": 6,\n \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments?skip=4&limit=4\"\n}\n","language":"json"},{"language":"json","status":404,"name":"Project Missing","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n"},{"code":"{\n \"message\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","language":"json","status":404,"name":"RFI Missing"},{"name":"No Access","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}\n","language":"json","status":403}]},"settings":"","auth":"required","params":[{"_id":"56cf1ece5267d70b00494bc5","ref":"","in":"path","required":true,"desc":"Unique identifier for RFI's project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ece5267d70b00494bc4","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI.","default":"","type":"string","name":"rfi_uid"},{"_id":"56cf1ece5267d70b00494bc3","ref":"","in":"query","required":false,"desc":"Number of comments to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ece5267d70b00494bc2","ref":"","in":"query","required":false,"desc":"Number of comments to skip in the set of results.","default":"0","type":"int","name":"skip"}],"url":"/projects/:project_uid/rfis/:rfi_uid/comments"},"isReference":false,"order":8,"body":"","excerpt":"Get a list of comments on an RFI. Comment data is described in [The Comment Object](doc:the-comment-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-comments-on-an-rfi","type":"get","title":"Retrieve Comments on an RFI","__v":0,"childrenPages":[]}
getRetrieve Comments on an RFI
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"uid": "87658a3f-8ee0-4188-9c55-b06a203fa9e7",
"text": "Those people are trying to kill us!",
"created_at": "2013-05-17T02:30:22+00:00",
"created_by": {
"uid": "deae0b56-81c7-4a05-8e8b-410fd17a01f0",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0",
"email": "henry.jones@oxford.edu"
},
"record_type": "rfi",
"record": {
"uid": "c62d6a09-1e7c-4aa0-b60b-86249eba7e5b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b"
}
},
{
"uid": "465abf98-accb-42cd-bd54-16f29e8447f2",
"text": "I know, Dad!",
"created_at": "2013-05-15T18:54:22+00:00",
"created_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "indiana.jones@marshallcollege.edu"
},
"record_type": "rfi",
"record": {
"uid": "c62d6a09-1e7c-4aa0-b60b-86249eba7e5b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b"
}
},
{
"uid": "08ea8b05-a99c-40a7-a312-fee360ad432a",
"text": "This is a new experience for me.",
"created_at": "2013-05-14T8:30:56+00:00",
"created_by": {
"uid": "deae0b56-81c7-4a05-8e8b-410fd17a01f0",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0",
"email": "henry.jones@oxford.edu"
},
"record_type": "rfi",
"record": {
"uid": "c62d6a09-1e7c-4aa0-b60b-86249eba7e5b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b"
}
},
{
"uid": "68839690-e0aa-4751-aedf-e630b921e91e",
"text": "It happens to me all the time.",
"created_at": "2013-05-13T11:22:56+00:00",
"created_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "indiana.jones@marshallcollege.edu"
},
"record_type": "rfi",
"record": {
"uid": "c62d6a09-1e7c-4aa0-b60b-86249eba7e5b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b"
}
}
],
"total_count": 6,
"next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments?skip=4&limit=4"
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}
{"_id":"5a0487bf1058cd003cfb7ac2","category":"5a0487bf1058cd003cfb7aa7","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5a0487bf1058cd003cfb7a9b","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:47:16.283Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"status":200,"name":"Success","code":"{\n \"data\": [\n {\n \"field\": \"title\",\n \"old_value\": \"Toilet does fit\",\n \"new_value\": \"Toilet doesn't fit\",\n \"updated_at\": \"2013-05-13T04:30:22+00:00\",\n \"updated_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"betty@construction.com\"\n }\n },\n {\n \"field\": \"assigned_to\",\n \"old_value\": [\n {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"bob@subcontractor.com\"\n }\n ],\n \"new_value\": [\n {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"bob@subcontractor.com\"\n },\n {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"betty@construction.com\"\n }\n ],\n \"updated_at\": \"2013-05-11T05:25:11+00:00\",\n \"updated_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"betty@construction.com\"\n }\n },\n {\n \"field\": \"photos\",\n \"old_value\": [],\n \"new_value\": [\n {\n \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n \"title\": \"Bongo Drums\",\n \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n \"created_at\": \"2013-05-17T02:30:22+00:00\",\n \"created_by\": {\n \"uid\": null,\n \"url\": null,\n \"email\": \"nick@subcontractor.com\"\n },\n \"deleted\": false\n }\n ],\n \"updated_at\": \"2013-04-11T02:18:53+00:00\",\n \"updated_by\": {\n \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n \"email\": \"betty@construction.com\"\n },\n },\n ],\n \"total_count\": 14,\n \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/history?skip=2&limit=2\"\n}\n","language":"json"},{"status":404,"name":"Project Missing","code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","language":"json"},{"language":"json","status":404,"name":"RFI Missing","code":"{\n \"message\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n"},{"code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}\n","language":"json","status":403,"name":"No Project Access"}]},"settings":"","auth":"required","params":[{"_id":"56cf1ece5267d70b00494bc9","ref":"","in":"path","required":true,"desc":"Unique identifier for RFI's project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ece5267d70b00494bc8","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI.","default":"","type":"string","name":"rfi_uid"},{"_id":"56cf1ece5267d70b00494bc7","ref":"","in":"query","required":false,"desc":"Number of history items to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ece5267d70b00494bc6","ref":"","in":"query","required":false,"desc":"Number of history to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"56edc8e4c3628a170081f019","ref":"","in":"query","required":false,"desc":"Only retrieve RFI history created after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"string","name":"updated_after"}],"url":"/projects/:project_uid/rfis/:rfi_uid/history"},"isReference":false,"order":9,"body":"","excerpt":"Get the change history of an RFI (includes references). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-rfi-history","type":"get","title":"Retrieve RFI History","__v":0,"childrenPages":[]}
getRetrieve RFI History
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"field": "title",
"old_value": "Toilet does fit",
"new_value": "Toilet doesn't fit",
"updated_at": "2013-05-13T04:30:22+00:00",
"updated_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "betty@construction.com"
}
},
{
"field": "assigned_to",
"old_value": [
{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "bob@subcontractor.com"
}
],
"new_value": [
{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "bob@subcontractor.com"
},
{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "betty@construction.com"
}
],
"updated_at": "2013-05-11T05:25:11+00:00",
"updated_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "betty@construction.com"
}
},
{
"field": "photos",
"old_value": [],
"new_value": [
{
"uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
"title": "Bongo Drums",
"url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
"created_at": "2013-05-17T02:30:22+00:00",
"created_by": {
"uid": null,
"url": null,
"email": "nick@subcontractor.com"
},
"deleted": false
}
],
"updated_at": "2013-04-11T02:18:53+00:00",
"updated_by": {
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "betty@construction.com"
},
},
],
"total_count": 14,
"next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/history?skip=2&limit=2"
}
{
"message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
"message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
"message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."