{"_id":"5ecd75071d70200039607215","category":"5ecd75071d702000396071ff","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d70200039607216","category":"5ecd75071d702000396071ff","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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:[email protected]?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- If you are having issues with the API, please email [[email protected]](mailto:[email protected]m). If you are encountering general PlanGrid issues, please email [[email protected]](mailto:[email protected]).\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,"metadata":{"title":"","description":"","image":[]},"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
. - If you are having issues with the API, please email [email protected]. If you are encountering general PlanGrid issues, please email [email protected].
We'll do our best to accommodate you.
{"_id":"5ecd75071d70200039607217","category":"5ecd75071d702000396071ff","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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- Miscellaneous endpoints and associated documentation related to the resource","excerpt":"","slug":"documentation-conventions","type":"basic","title":"Conventions","__v":1,"metadata":{"title":"","description":"","image":[]},"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
- Miscellaneous endpoints and associated documentation related to the resource
{"_id":"5ecd75071d70200039607218","category":"5ecd75071d702000396071ff","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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:[email protected]).","excerpt":"Oh my!","slug":"libraries-and-sdks","type":"basic","title":"Libraries, SDKs, and Packages","__v":0,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d70200039607219","category":"5ecd75071d702000396071ff","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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:[email protected]).","excerpt":"Tickets?","slug":"access","type":"basic","title":"Access","__v":0,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960721a","category":"5ecd75071d702000396071ff","user":"55d201fe945e481700afbb19","parentDoc":null,"project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","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 API_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,"metadata":{"title":"","description":"","image":[]},"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 API_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":"5ecd75071d70200039607232","category":"5ecd75071d70200039607200","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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://www.plangrid.com/security/) 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:[email protected]). 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\\\": \\\"[email protected]\\\"\\n },\\n \\\"updated_at\\\": \\\"2013-05-23T19:22:56+00:00\\\",\\n \\\"room\\\": null,\\n \\\"updated_by\\\": {\\n \\\"email\\\": \\\"[email protected]\\\"\\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[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 API_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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"updated_at": "2013-05-23T19:22:56+00:00",
"room": null,
"updated_by": {
"email": "[email protected]"
}
}
{
"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 API_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":"5ecd75071d70200039607233","category":"5ecd75071d70200039607200","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5ecd75071d702000396072a2","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:[email protected]) 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 API_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,"metadata":{"title":"","description":"","image":[]},"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 API_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":"5ecd75071d70200039607234","category":"5ecd75071d70200039607200","user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","parentDoc":null,"version":"5ecd75071d702000396072a2","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 explicitly 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:[email protected]) 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,"metadata":{"title":"","description":"","image":[]},"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 explicitly 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":"5ecd75071d70200039607235","category":"5ecd75071d70200039607200","user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","parentDoc":null,"version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d70200039607236","category":"5ecd75071d70200039607200","user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","parentDoc":null,"version":"5ecd75071d702000396072a2","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\\\": \\\"[email protected]\\\",\\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]",
"url": "https://io.plangrid.com/projects/da48fcc3-7af1-4fd6-a083-70195468718a/users/54ab24c10d1c74ff22ae4874",
"uid": "54ab24c10d1c74ff22ae4874"
},
"folder": "Submittals"
}
{"_id":"5ecd75071d70200039607237","category":"5ecd75071d70200039607200","parentDoc":null,"user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","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\\\": \\\"[email protected]\\\"\\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\\\": \\\"[email protected]\\\"\\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\\\": \\\"[email protected]\\\"\\n }\\n ]\\n ...\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:api-header]\n{\n \"title\": \"References to User(s) Assigned to Objects\"\n}\n[/block]\nReferences to assigned users on certain objects, such as [submittal items](doc:the-submittal-items-object) and [submittal packages](doc:the-submittal-packages-object), may be represented as an object specifying whether a user or a group is assigned.\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"type\\\": \\\"user\\\",\\n \\\"uid\\\": \\\"8510cfc9-2a82-4736-bf37-753c900d1c68\\\",\\n \\\"url\\\": \\\"http://io.plangrid.com/projects/7b9b299a-2906-4fa4-bdc2-6417cec02cfe/users/8510cfc9-2a82-4736-bf37-753c900d1c68\\\"\\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\n\n[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Attribute\",\n \"0-0\": \"**type**\\n`string`\",\n \"1-0\": \"**uid**\\n`string`\",\n \"1-1\": \"Unique identifier referencing the user or group.\",\n \"0-1\": \"Possible values are `user` and `group`. Note that not all objects support `group` assignment.\",\n \"h-1\": \"Description\",\n \"2-0\": \"**url**\\n`string`\",\n \"2-1\": \"URL to retrieve the user record's data.\"\n },\n \"cols\": 2,\n \"rows\": 3\n}\n[/block]\nWhen a collection of assigned users is referenced, an array is returned:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"reviewers\\\": [\\n {\\n \\\"type\\\": \\\"user\\\",\\n \\\"uid\\\": \\\"5575daca12921d0075fdd456\\\",\\n \\\"url\\\": \\\"http://io.plangrid.com/projects/7b9b299a-2906-4fa4-bdc2-6417cec02cfe/users/5575daca12921d0075fdd456\\\"\\n },\\n {\\n \\\"type\\\": \\\"user\\\",\\n \\\"uid\\\": \\\"5b96afdff0d0fd50c2f4f8b5\\\",\\n \\\"url\\\": \\\"http://io.plangrid.com/projects/7b9b299a-2906-4fa4-bdc2-6417cec02cfe/users/5b96afdff0d0fd50c2f4f8b5\\\"\\n }\\n ] \\n}\",\n \"language\": \"json\"\n }\n ]\n}\n[/block]\nWhen assigning user(s) to a role for an object such as the [submittal items](doc:the-submittal-items-object) or [packages](doc:the-submittal-packages-object), the body of the request must also contain references to the assigned user(s) in this format with the `type` and `uid` attributes:\n[block:code]\n{\n \"codes\": [\n {\n \"code\": \"{\\n \\\"reviewers\\\": [\\n {\\n \\\"type\\\": \\\"user\\\",\\n \\\"uid\\\": \\\"5575daca12921d0075fdd456\\\"\\n },\\n {\\n \\\"type\\\": \\\"user\\\",\\n \\\"uid\\\": \\\"5b96afdff0d0fd50c2f4f8b5\\\"\\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
}
}
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": "[email protected]"
},
{
"uid": "8510cfc9-2a82-4736-bf37-753c900d1c68",
"url": "https://io.plangrid.com/projects/78128c72-5862-458a-9577-33eaa189a5c1/users/8510cfc9-2a82-4736-bf37-753c900d1c68",
"email": "[email protected]"
}
]
}
References to assigned users on certain objects, such as submittal items and submittal packages, may be represented as an object specifying whether a user or a group is assigned.
{
"type": "user",
"uid": "8510cfc9-2a82-4736-bf37-753c900d1c68",
"url": "http://io.plangrid.com/projects/7b9b299a-2906-4fa4-bdc2-6417cec02cfe/users/8510cfc9-2a82-4736-bf37-753c900d1c68"
}
typestring
Possible values are user
and group
. Note that not all objects support group
assignment.
uidstring
Unique identifier referencing the user or group.
urlstring
URL to retrieve the user record's data.
When a collection of assigned users is referenced, an array is returned:
{
"reviewers": [
{
"type": "user",
"uid": "5575daca12921d0075fdd456",
"url": "http://io.plangrid.com/projects/7b9b299a-2906-4fa4-bdc2-6417cec02cfe/users/5575daca12921d0075fdd456"
},
{
"type": "user",
"uid": "5b96afdff0d0fd50c2f4f8b5",
"url": "http://io.plangrid.com/projects/7b9b299a-2906-4fa4-bdc2-6417cec02cfe/users/5b96afdff0d0fd50c2f4f8b5"
}
]
}
When assigning user(s) to a role for an object such as the submittal items or packages, the body of the request must also contain references to the assigned user(s) in this format with the type
and uid
attributes:
{
"reviewers": [
{
"type": "user",
"uid": "5575daca12921d0075fdd456"
},
{
"type": "user",
"uid": "5b96afdff0d0fd50c2f4f8b5"
}
]
}
{"_id":"5ecd75071d70200039607238","category":"5ecd75071d70200039607200","user":"55d201fe945e481700afbb19","parentDoc":null,"project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","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 API_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,"metadata":{"title":"","description":"","image":[]},"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 API_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":"5ecd75071d70200039607239","category":"5ecd75071d70200039607200","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960723a","category":"5ecd75071d70200039607200","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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:[email protected]) 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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960723b","category":"5ecd75071d70200039607200","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}
Timestamps and Timezones
{"_id":"5ecd75071d7020003960723c","category":"5ecd75071d70200039607200","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d70200039607276","category":"5ecd75071d70200039607201","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d70200039607277","category":"5ecd75071d70200039607201","parentDoc":null,"user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960722f","category":"5ecd75071d70200039607202","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d70200039607230","category":"5ecd75071d70200039607202","project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","parentDoc":null,"version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d70200039607231","category":"5ecd75071d70200039607202","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"5ecd75071d702000396072a2","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 [email protected]\\\"}\"\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 API_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,"metadata":{"title":"","description":"","image":[]},"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 API_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 [email protected]\"}"
}
]
}
{ "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":"5ecd75071d70200039607265","category":"5ecd75071d70200039607203","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"5ecd75071d702000396072a2","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 partner or customer, you can register your app through the [Admin Console](https://enterprise.plangrid.com).\"\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,"metadata":{"title":"","description":"","image":[]},"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 partner or customer, you can register your app through the Admin Console.
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":"5ecd75071d70200039607266","category":"5ecd75071d70200039607203","project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","parentDoc":null,"version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d70200039607267","category":"5ecd75071d70200039607203","project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","parentDoc":null,"version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d70200039607268","category":"5ecd75071d70200039607203","project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","parentDoc":null,"version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d70200039607269","category":"5ecd75071d70200039607203","project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","parentDoc":null,"version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960726a","category":"5ecd75071d70200039607203","project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","parentDoc":null,"version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960726b","category":"5ecd75071d70200039607203","parentDoc":null,"user":"57db49de0678030e008a76f8","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960724b","category":"5ecd75071d70200039607204","user":"55d201fe945e481700afbb19","parentDoc":null,"project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960724c","category":"5ecd75071d70200039607204","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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"},{"_id":"5d2cf00310ed18001e69cbab","ref":"","in":"body","required":false,"desc":"Boolean indicating whether to add the project to the organization that the API user belongs to or not. By default the project is created as a personal project and not as an organization-linked project.","default":"false","type":"boolean","name":"add_to_organization"}],"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":4,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960724d","category":"5ecd75071d70200039607204","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5ecd75071d702000396072a2","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":5,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960724e","category":"5ecd75071d70200039607204","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960724f","category":"5ecd75071d70200039607204","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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":2,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960723d","category":"5ecd75071d70200039607205","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960723e","category":"5ecd75071d70200039607205","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d70200039607261","category":"5ecd75071d70200039607206","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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\\\": \\\"[email protected]\\\" \\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"record_type": "project",
"record": {
"uid": "bafce976-8f33-437f-9c52-fb274456940f",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f",
}
}
{"_id":"5ecd75071d70200039607262","category":"5ecd75071d70200039607206","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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 sensitive 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":1,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"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": "[email protected]"
},
"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": "[email protected]"
},
"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": "[email protected]"
},
"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":"5ecd75071d70200039607259","category":"5ecd75071d70200039607207","parentDoc":null,"user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","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\\\": \\\"[email protected]\\\" \\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"deleted": false
}
{"_id":"5ecd75071d7020003960725a","category":"5ecd75071d70200039607207","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55fc7da63c21291900e7e0a5","version":"5ecd75071d702000396072a2","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\": \"Design\",\n \"0-1\": \".dgn\\n.dwf\\n.dwfx\\n.dwg\\n.dxf\\n.rvt\",\n \"3-0\": \"Spreadsheet\",\n \"3-1\": \".csv\\n.xls\\n.xlsx\",\n \"4-0\": \"Text Document\",\n \"4-1\": \".doc\\n.docx\\n.odf\\n.pdf\\n.rtf\\n.txt\",\n \"5-0\": \"Video\",\n \"5-1\": \".avi\\n.f4v\\n.mov\\n.mpg\\n.mp4\\n.webm\\n.wmv\",\n \"2-1\": \".bmp\\n.gif\\n.jpeg\\n.jpg\\n.png\",\n \"2-0\": \"Image\",\n \"1-0\": \"Google Earth\",\n \"1-1\": \".kml\\n.kmz\"\n },\n \"cols\": 2,\n \"rows\": 6\n}\n[/block]","excerpt":"","slug":"supported-file-types","type":"basic","title":"Supported File Types","__v":0,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}
Supported File Types
The following table lists supported file types for documents:
Design
.dgn
.dwf
.dwfx
.dwg
.dxf
.rvt
Google Earth
.kml
.kmz
Image
.bmp
.gif
.jpeg
.jpg
.png
Spreadsheet
.csv
.xls
.xlsx
Text Document
.doc
.docx
.odf
.pdf
.rtf
.txt
Video
.avi
.f4v
.mov
.mpg
.mp4
.webm
.wmv
{"_id":"5ecd75071d7020003960725b","category":"5ecd75071d70200039607207","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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"},{"_id":"5d28c7cc07d80d001808abea","ref":"","in":"body","required":false,"desc":"Boolean indicating whether to automatically version the document if a file with the same name exists within the specified folder. By default, documents are not versioned.","default":"false","type":"boolean","name":"auto_version"}],"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":5,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960725c","category":"5ecd75071d70200039607207","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"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":"5ecd75071d7020003960725d","category":"5ecd75071d70200039607207","parentDoc":null,"user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"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": "[email protected]"
},
"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":"5ecd75071d7020003960725e","category":"5ecd75071d70200039607207","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"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":"5ecd75071d7020003960725f","category":"5ecd75071d70200039607207","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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":"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"},{"_id":"5af4c1fd4405d80003977454","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":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":2,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"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":"5ecd75071d70200039607260","category":"5ecd75071d70200039607207","user":"55d201fe945e481700afbb19","parentDoc":null,"project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d70200039607287","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","category":"5ecd75071d70200039607213","user":"57db49de0678030e008a76f8","updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-10-30T20:29:00.028Z","link_external":false,"link_url":"","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":"[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 for details.\",\n \"1-0\": \"**title**\\n`string`\",\n \"1-1\": \"Title of the report. May be `null`.\",\n \"3-0\": \"**report_date**\\n`string`\",\n \"3-1\": \"Date for which the report is submitted. UTC date in ISO-8601 format.\",\n \"2-0\": \"**description**\\n`string`\",\n \"4-0\": \"**field_report_type.name**\\n`string`\",\n \"5-0\": \"**field_report_type.status**\\n`string`\",\n \"7-0\": \"**field_report_type.uid**\\n`string`\",\n \"8-0\": \"**pdf_url**\\n`string`\",\n \"9-0\": \"**pdf_form_values**\\n`array`\",\n \"10-0\": \"**pg_form_values**\\n`object`\",\n \"15-0\": \"**attachments**\\n`object`\",\n \"16-0\": \"**photos**\\n`object`\",\n \"17-0\": \"**snapshots**\\n`object`\",\n \"20-0\": \"**created_by**\\n`object`\",\n \"20-1\": \"Reference to PlanGrid user that created the field report. In rare cases, this may not map to a real user. See Foreign Keys for attribute details.\",\n \"15-1\": \"Reference to collection of documents in the field report. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"16-1\": \"Reference to collection of photos in the field report. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"17-1\": \"Reference to collection of snapshots in the Field report. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"2-1\": \"Description of the report.\",\n \"4-1\": \"Name of the report template.\",\n \"5-1\": \"Status of the report template. May be `active` or `archived`.\",\n \"7-1\": \"Unique identifier for the field report template.\",\n \"8-1\": \"URL to retrieve the submitted report. May be empty if not a custom field report.\",\n \"9-1\": \"An array of objects containing `name`/`value` pairs referencing the fields and values of a custom PDF form. May be empty if not a custom field report.\",\n \"21-0\": \"**updated_at**\\n`string`\",\n \"21-1\": \"When the field report was updated by a PlanGrid client. UTC date and time in ISO-8601 format.\",\n \"13-0\": \"**pg_form_values.pg_worklog_entries**\\n`array`\",\n \"13-1\": \"An array representing the work log entries if uthe template is a native daily report. See [The Worklog Entries Object](doc:the-worklog-entries-object) for attribute details.\",\n \"10-1\": \"May be empty if not using the native daily report.\",\n \"11-0\": \"**pg_form_values.pg_equipment_entries**\\n`array`\",\n \"12-0\": \"**pg_form_values.pg_materials_entries**\\n`array`\",\n \"11-1\": \"An array representing the equipment entries if using the native daily report. See [The Equipment Entries Object](doc:the-materials-entries-object) for attribute details.\",\n \"12-1\": \"An array representing the materials entries if the template is a native daily report. See [The Materials Entries Object](doc:the-materials-entries-object-1) for attribute details.\",\n \"18-0\": \"**status**\\n`string`\",\n \"18-1\": \"Refers to the status of the field report. Possible values can be `draft`, `submitted`, `archived`, or `deleted`.\",\n \"6-0\": \"**field_report_type.template_type**\\n`string`\",\n \"6-1\": \"Indicates the template type used if a default PlanGrid report was used. `null` if a PDF or custom form was used.\",\n \"14-0\": \"**custom_items**\\n`array`\",\n \"14-1\": \"An array representing custom form field items if the template is a native daily report. See [The Custom Items Object](doc:the-custom-items-object) for attribute details.\",\n \"19-0\": \"**weather**\\n`object`\",\n \"19-1\": \"If an address is provided for the project, weather can be automatically generated based on the report date. See [The Weather Object](doc:the-weather-object) for more attribute details.\"\n },\n \"cols\": 2,\n \"rows\": 22\n}\n[/block]","excerpt":"","slug":"the-field-report-object","type":"basic","title":"The Field Report Object","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}
The Field Report Object
uidstring
Never blank. See Unique Identifiers for details.
titlestring
Title of the report. May be null
.
descriptionstring
Description of the report.
report_datestring
Date for which the report is submitted. UTC date in ISO-8601 format.
field_report_type.namestring
Name of the report template.
field_report_type.statusstring
Status of the report template. May be active
or archived
.
field_report_type.template_typestring
Indicates the template type used if a default PlanGrid report was used. null
if a PDF or custom form was used.
field_report_type.uidstring
Unique identifier for the field report template.
pdf_urlstring
URL to retrieve the submitted report. May be empty if not a custom field report.
pdf_form_valuesarray
An array of objects containing name
/value
pairs referencing the fields and values of a custom PDF form. May be empty if not a custom field report.
pg_form_valuesobject
May be empty if not using the native daily report.
pg_form_values.pg_equipment_entriesarray
An array representing the equipment entries if using the native daily report. See The Equipment Entries Object for attribute details.
pg_form_values.pg_materials_entriesarray
An array representing the materials entries if the template is a native daily report. See The Materials Entries Object for attribute details.
pg_form_values.pg_worklog_entriesarray
An array representing the work log entries if uthe template is a native daily report. See The Worklog Entries Object for attribute details.
custom_itemsarray
An array representing custom form field items if the template is a native daily report. See The Custom Items Object for attribute details.
attachmentsobject
Reference to collection of documents in the field report. See Foreign Keys for attribute details.
photosobject
Reference to collection of photos in the field report. See Foreign Keys for attribute details.
snapshotsobject
Reference to collection of snapshots in the Field report. See Foreign Keys for attribute details.
statusstring
Refers to the status of the field report. Possible values can be draft
, submitted
, archived
, or deleted
.
weatherobject
If an address is provided for the project, weather can be automatically generated based on the report date. See The Weather Object for more attribute details.
created_byobject
Reference to PlanGrid user that created the field report. In rare cases, this may not map to a real user. See Foreign Keys for attribute details.
updated_atstring
When the field report was updated by a PlanGrid client. UTC date and time in ISO-8601 format.
{"_id":"5ecd75071d70200039607290","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","category":"5ecd75071d70200039607213","user":"5c4f7b3b014143002ce6c065","updates":[],"next":{"pages":[],"description":""},"createdAt":"2020-02-11T22:52:24.012Z","link_external":false,"link_url":"","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":1,"body":"[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Attributes\",\n \"h-1\": \"Description\",\n \"0-0\": \"**uid**\\n`string`\",\n \"3-0\": \"**field_reports**\\n`object`\",\n \"3-1\": \"Object containing reference URL to all field reports associated with this template. See query parameters for [Retrieve Field Reports in a Project](doc:retrieve-field-reports-in-a-project) for details on template specific querying.\",\n \"7-0\": \"**is_pdf**\\n`boolean`\",\n \"7-1\": \"Indicates whether the report is a PDF template.\",\n \"8-0\": \"**pdf_url**\\n`string`\",\n \"8-1\": \"URL of the PDF template if using a custom PDF.\",\n \"9-0\": \"**template_type**\\n`string`\",\n \"9-1\": \"Name of the template type. May be `null`.\",\n \"15-0\": \"**updated_at**\\n`string`\",\n \"15-1\": \"When the report template was created or last updated. UTC date and time in ISO-8601 format.\",\n \"0-1\": \"Never blank. See Unique Identifiers for details.\",\n \"14-0\": \"**created_by**\\n`object`\",\n \"14-1\": \"Reference to PlanGrid user that created the field report template. In rare cases, this may not map to a real user. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n \"10-0\": \"**status**\\n`string`\",\n \"10-1\": \"The status of the template. Possible values are `active`, `inactive`, or `archived`.\",\n \"1-0\": \"**name**\\n`string`\",\n \"1-1\": \"Name of the field report template.\",\n \"4-0\": \"**group_permissions**\\n`array`\",\n \"4-1\": \"Array of objects referencing the permission for groups of users.\",\n \"5-0\": \"**group_permissions.permissions**\\n`array`\",\n \"5-1\": \"Allowed permissions for the group. Possible values include: `review`, `manage`, `submit`.\",\n \"6-0\": \"**group_permission.role_uid**\\n`string`\",\n \"6-1\": \"Unique identifier of the group that the permissions pertain to.\",\n \"11-0\": \"**user_permissions**\\n`array`\",\n \"11-1\": \"Array of objects referencing the permission users.\",\n \"12-0\": \"**user_permission.permissions**\\n`array`\",\n \"12-1\": \"Allowed permissions for the user. Possible values include: `review`, `manage`, `submit`.\",\n \"13-0\": \"**user_permissions.user_id**\\n`string`\",\n \"13-1\": \"Unique identifier for the user that the permissions pertain to.\",\n \"2-0\": \"**cadence**\\n`string`\",\n \"2-1\": \"Indicates whether the report is set to be submitted daily. May be `daily` or `null`.\"\n },\n \"cols\": 2,\n \"rows\": 16\n}\n[/block]","excerpt":"","slug":"the-field-report-template-object","type":"basic","title":"The Field Report Template Object","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}
The Field Report Template Object
uidstring
Never blank. See Unique Identifiers for details.
namestring
Name of the field report template.
cadencestring
Indicates whether the report is set to be submitted daily. May be daily
or null
.
field_reportsobject
Object containing reference URL to all field reports associated with this template. See query parameters for Retrieve Field Reports in a Project for details on template specific querying.
group_permissionsarray
Array of objects referencing the permission for groups of users.
group_permissions.permissionsarray
Allowed permissions for the group. Possible values include: review
, manage
, submit
.
group_permission.role_uidstring
Unique identifier of the group that the permissions pertain to.
is_pdfboolean
Indicates whether the report is a PDF template.
pdf_urlstring
URL of the PDF template if using a custom PDF.
template_typestring
Name of the template type. May be null
.
statusstring
The status of the template. Possible values are active
, inactive
, or archived
.
user_permissionsarray
Array of objects referencing the permission users.
user_permission.permissionsarray
Allowed permissions for the user. Possible values include: review
, manage
, submit
.
user_permissions.user_idstring
Unique identifier for the user that the permissions pertain to.
created_byobject
Reference to PlanGrid user that created the field report template. In rare cases, this may not map to a real user. See Foreign Keys for attribute details.
updated_atstring
When the report template was created or last updated. UTC date and time in ISO-8601 format.
{"_id":"5ecd75071d7020003960728e","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","category":"5ecd75071d70200039607213","user":"5c4f7b3b014143002ce6c065","updates":[],"next":{"pages":[],"description":""},"createdAt":"2020-02-11T22:00:41.210Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":2,"body":"[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"0-0\": \"**section_label**\\n`string`\",\n \"0-1\": \"Name of the section.\",\n \"1-0\": \"**item_label**\\n`string`\",\n \"1-1\": \"Name of the question within the section.\",\n \"3-0\": \"**value_name**\\n`string`\",\n \"3-1\": \"Indicates the type of value for this item. Possible values are:\\n- `text_val` for text responses\\n- `number_val` for number responses\\n- `toggle_val` for preconfigured responses\\n- `choice_val` for multiple choice responses\\n- `date_val` for date responses\\n- `array_val` for multi-select responses\",\n \"2-0\": \"**notes**\\n`string`\",\n \"2-1\": \"Notes associated with the item.\",\n \"4-0\": \"**text_val**\\n`string`\",\n \"5-0\": \"**number_val**\\n`float`\",\n \"4-1\": \"May not exist if the item is not a text response.\",\n \"5-1\": \"May not exist if the item is not a number response.\",\n \"6-0\": \"**toggle_val**\\n`integer`\",\n \"6-1\": \"May not exist if the item is not a preconfigured response. The value will correspond with the following user selection:\\n- `0` = No / False / Minus / Fail\\n- `1` = Yes / True / Plus / Pass\\n- `2` = NA\\n- `null` = No answer selected\",\n \"7-0\": \"**choice_val**\\n`string`\",\n \"7-1\": \"May not exist if the item is not a multiple choice response.\",\n \"8-0\": \"**date_val**\\n`string`\",\n \"8-1\": \"UTC date in ISO-8601 format. May not exist if the item is not a date response.\",\n \"9-0\": \"**array_val**\\n`array`\",\n \"9-1\": \"Array of strings. May not exist if the item is not a multi-select response.\"\n },\n \"cols\": 2,\n \"rows\": 10\n}\n[/block]","excerpt":"","slug":"the-custom-items-object","type":"basic","title":"The Custom Item Object","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}
The Custom Item Object
section_labelstring
Name of the section.
item_labelstring
Name of the question within the section.
notesstring
Notes associated with the item.
value_namestring
Indicates the type of value for this item. Possible values are:
text_val
for text responsesnumber_val
for number responsestoggle_val
for preconfigured responseschoice_val
for multiple choice responsesdate_val
for date responsesarray_val
for multi-select responses
text_valstring
May not exist if the item is not a text response.
number_valfloat
May not exist if the item is not a number response.
toggle_valinteger
May not exist if the item is not a preconfigured response. The value will correspond with the following user selection:
0
= No / False / Minus / Fail1
= Yes / True / Plus / Pass2
= NAnull
= No answer selected
choice_valstring
May not exist if the item is not a multiple choice response.
date_valstring
UTC date in ISO-8601 format. May not exist if the item is not a date response.
array_valarray
Array of strings. May not exist if the item is not a multi-select response.
{"_id":"5ecd75071d7020003960728c","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","category":"5ecd75071d70200039607213","user":"5c4f7b3b014143002ce6c065","updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-01-29T22:59:40.683Z","link_external":false,"link_url":"","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":"[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"0-0\": \"**deleted**\\n`boolean`\",\n \"1-0\": \"**description**\\n`string`\",\n \"2-0\": \"**item**\\n`string`\",\n \"3-0\": \"**quantity**\\n`integer`\",\n \"4-0\": \"**timespan**\\n`integer`\",\n \"5-0\": \"**uid**\\n`string`\",\n \"5-1\": \"The unique identifier for the equipment entry.\",\n \"0-1\": \"Whether the equipment entry has been deleted or not.\",\n \"1-1\": \"A description of the equipment utilized (may be blank if `item` below contains all details).\",\n \"2-1\": \"A specific description of the equipment item used.\",\n \"4-1\": \"The total time all equipment was used for in milliseconds.\",\n \"3-1\": \"The number of pieces of the equipment that was used.\"\n },\n \"cols\": 2,\n \"rows\": 6\n}\n[/block]","excerpt":"","slug":"the-equipment-entries-object","type":"basic","title":"The Equipment Entries Object","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}
The Equipment Entries Object
deletedboolean
Whether the equipment entry has been deleted or not.
descriptionstring
A description of the equipment utilized (may be blank if item
below contains all details).
itemstring
A specific description of the equipment item used.
quantityinteger
The number of pieces of the equipment that was used.
timespaninteger
The total time all equipment was used for in milliseconds.
uidstring
The unique identifier for the equipment entry.
{"_id":"5ecd75071d7020003960728d","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","category":"5ecd75071d70200039607213","user":"5c4f7b3b014143002ce6c065","updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-01-29T23:12:42.692Z","link_external":false,"link_url":"","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":4,"body":"[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"0-0\": \"**deleted**\\n`boolean`\",\n \"1-0\": \"**description**\\n`string`\",\n \"2-0\": \"**item**\\n`string`\",\n \"3-0\": \"**quantity**\\n`integer`\",\n \"4-0\": \"**unit**\\n`integer`\",\n \"5-0\": \"**uid**\\n`string`\",\n \"5-1\": \"The unique identifier for the material entry.\",\n \"0-1\": \"Whether the material entry has been deleted or not.\",\n \"1-1\": \"A description of the material used (may be blank if `item` below contains all details).\",\n \"2-1\": \"A specific description of the material item used.\",\n \"4-1\": \"The unit of measure for the `quantity` specified.\",\n \"3-1\": \"The quantity of material that was used.\"\n },\n \"cols\": 2,\n \"rows\": 6\n}\n[/block]","excerpt":"","slug":"the-materials-entries-object","type":"basic","title":"The Materials Entries Object","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}
The Materials Entries Object
deletedboolean
Whether the material entry has been deleted or not.
descriptionstring
A description of the material used (may be blank if item
below contains all details).
itemstring
A specific description of the material item used.
quantityinteger
The quantity of material that was used.
unitinteger
The unit of measure for the quantity
specified.
uidstring
The unique identifier for the material entry.
{"_id":"5ecd75071d7020003960728a","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","category":"5ecd75071d70200039607213","user":"57db49de0678030e008a76f8","updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-01-29T17:52:53.217Z","link_external":false,"link_url":"","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":5,"body":"[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"0-0\": \"**description**\\n`string`\",\n \"1-0\": \"**headcount**\\n`integer`\",\n \"2-0\": \"**timespan**\\n`integer`\",\n \"3-0\": \"**trade**\\n`string`\",\n \"4-0\": \"**uid**\\n`string`\",\n \"5-0\": \"**deleted**\\n`boolean`\",\n \"5-1\": \"Whether the work log entry has been deleted or not.\",\n \"0-1\": \"A description of the work performed.\",\n \"1-1\": \"The number of workers for the work log entry.\",\n \"2-1\": \"The total number of works for the work log entry in milliseconds.\",\n \"3-1\": \"The trade that performed the work.\",\n \"4-1\": \"The unique identifier for the work log entry.\"\n },\n \"cols\": 2,\n \"rows\": 6\n}\n[/block]","excerpt":"","slug":"the-worklog-entries-object","type":"basic","title":"The Worklog Entries Object","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}
The Worklog Entries Object
descriptionstring
A description of the work performed.
headcountinteger
The number of workers for the work log entry.
timespaninteger
The total number of works for the work log entry in milliseconds.
tradestring
The trade that performed the work.
uidstring
The unique identifier for the work log entry.
deletedboolean
Whether the work log entry has been deleted or not.
{"_id":"5ecd75071d7020003960728b","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","category":"5ecd75071d70200039607213","user":"5c4f7b3b014143002ce6c065","updates":[],"next":{"pages":[],"description":""},"createdAt":"2019-01-29T22:17:45.819Z","link_external":false,"link_url":"","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":6,"body":"[block:parameters]\n{\n \"data\": {\n \"h-0\": \"Attribute\",\n \"h-1\": \"Description\",\n \"0-0\": \"**humidity**\\n`decimal`\",\n \"1-0\": \"**precipitation_accumulation**\\n`decimal`\",\n \"2-0\": \"**precipitation_accumulation_unit**\\n`string`\",\n \"3-0\": \"**speed_unit**\\n`string`\",\n \"4-0\": \"**summary_key**\\n`string`\",\n \"5-0\": \"**temperature_max**\\n`integer`\",\n \"6-0\": \"**temperature_min**\\n`integer`\",\n \"7-0\": \"**temperature_unit**\\n`string`\",\n \"7-1\": \"The unit of the temperature measurements.\",\n \"8-0\": \"**wind_bearing**\\n`integer`\",\n \"9-0\": \"**wind_gust**\\n`decimal`\",\n \"10-0\": \"**wind_speed**\\n`decimal`\",\n \"0-1\": \"A percentage value indicating the humidity over the course of the day.\",\n \"1-1\": \"The amount of precipitation accumulated throughout the day. Unit specified in `precipitation_accumulation_unit`.\",\n \"2-1\": \"The unit of the precipitation accumulated.\",\n \"3-1\": \"The unit of the wind speed measurement.\",\n \"4-1\": \"A description of the weather (i.e. Partly Cloudy).\",\n \"5-1\": \"The maximum temperature during the day.\",\n \"6-1\": \"The minimum temperature during the day.\",\n \"8-1\": \"The direction of the wind.\",\n \"9-1\": \"The maximum wind speed observed throughout the day.\",\n \"10-1\": \"The average wind speed observed throughout the day.\"\n },\n \"cols\": 2,\n \"rows\": 11\n}\n[/block]","excerpt":"","slug":"the-weather-object","type":"basic","title":"The Weather Object","__v":0,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}
The Weather Object
humiditydecimal
A percentage value indicating the humidity over the course of the day.
precipitation_accumulationdecimal
The amount of precipitation accumulated throughout the day. Unit specified in precipitation_accumulation_unit
.
precipitation_accumulation_unitstring
The unit of the precipitation accumulated.
speed_unitstring
The unit of the wind speed measurement.
summary_keystring
A description of the weather (i.e. Partly Cloudy).
temperature_maxinteger
The maximum temperature during the day.
temperature_mininteger
The minimum temperature during the day.
temperature_unitstring
The unit of the temperature measurements.
wind_bearinginteger
The direction of the wind.
wind_gustdecimal
The maximum wind speed observed throughout the day.
wind_speeddecimal
The average wind speed observed throughout the day.
{"_id":"5ecd75071d70200039607288","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","category":"5ecd75071d70200039607213","user":"57db49de0678030e008a76f8","updates":[],"next":{"pages":[],"description":""},"createdAt":"2018-10-30T20:29:31.421Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"results":{"codes":[{"status":200,"name":null,"code":"{\n \"data\": [\n {\n \"attachments\": {\n \"total_count\": 1,\n \"url\": \"https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/field_reports/12528a5e-3865-4ec8-9ec5-64f6859d08a1/attachments\"\n },\n \"created_by\": {\n \"email\": \"[email protected]\",\n \"uid\": \"57d2e95cfb361f01832cf8e0\",\n \"url\": \"https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/users/57d2e95cfb361f01832cf8e0\"\n },\n \"description\": \"\",\n \"field_report_type\": {\n \"name\": \"Daily Report\",\n \"project_uid\": \"fd9d4f20-da14-48ee-ad73-c875cf1b4882\",\n \"status\": \"active\",\n \"uid\": \"b2955f3a-9dae-3de8-82bb-88074d933b14\"\n },\n \"pg_form_values\": {\n \"pg_worklog_entries\": [\n {\n \"deleted\": false,\n \"description\": null,\n \"headcount\": 10,\n \"timespan\": 43200000,\n \"trade\": \"Electrical\",\n \"uid\": \"8e8b3a08-1aad-994c-56ba-929de8ea5926\"\n }\n ]\n },\n \"photos\": {\n \"total_count\": 1,\n \"url\": \"https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/field_reports/12528a5e-3865-4ec8-9ec5-64f6859d08a1/photos\"\n },\n \"project_uid\": \"fd9d4f20-da14-48ee-ad73-c875cf1b4882\",\n \"report_date\": \"2018-10-30\",\n \"snapshots\": {\n \"total_count\": 0,\n \"url\": \"https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/field_reports/12528a5e-3865-4ec8-9ec5-64f6859d08a1/snapshots\"\n },\n \"title\": null,\n \"uid\": \"12528a5e-3865-4ec8-9ec5-64f6859d08a1\",\n \"updated_at\": \"2018-10-30T22:17:56.239734+00:00\",\n \"weather\": {\n \"humidity\": 0.77,\n \"precipitation_accumulation\": null,\n \"precipitation_accumulation_unit\": \"in\",\n \"speed_unit\": \"mph\",\n \"summary_key\": \"rain\",\n \"temperature_max\": 81,\n \"temperature_min\": 67,\n \"temperature_unit\": \"Fahrenheit\",\n \"wind_bearing\": 185,\n \"wind_gust\": 31.7,\n \"wind_speed\": 11.4\n }\n },\n {\n \"attachments\": {\n \"total_count\": 0,\n \"url\": \"https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/field_reports/4a4eed61-7fe4-448c-91b6-f9248bfc7d9d/attachments\"\n },\n \"created_by\": {\n \"email\": \"[email protected]\",\n \"uid\": \"57d2e95cfb361f01832cf8e0\",\n \"url\": \"https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/users/57d2e95cfb361f01832cf8e0\"\n },\n \"description\": \"\",\n \"field_report_type\": {\n \"name\": \"Job Hazard Analysis\",\n \"project_uid\": \"fd9d4f20-da14-48ee-ad73-c875cf1b4882\",\n \"status\": \"active\",\n \"uid\": \"ab88e316-6115-41f4-82c5-e41d9495bbee\"\n },\n \"pdf_form_values\": [\n {\n \"name\": \"Project\",\n \"value\": \"Downtown Museum\"\n },\n {\n \"name\": \"Date\",\n \"value\": \"12/25/18\"\n },\n {\n \"name\": \"Project_No\",\n \"value\": \"90201\"\n },\n {\n \"name\": \"Location\",\n \"value\": \"Malibu, CA\"\n },\n {\n \"name\": \"Activity\",\n \"value\": \"Loading presensts\"\n },\n {\n \"name\": \"Hazard\",\n \"value\": \"Elf not wearing protective gear\"\n },\n {\n \"name\": \"Corrective Action\",\n \"value\": \"Provide elves with protective gear\"\n },\n {\n \"name\": \"Notes\",\n \"value\": \"\"\n },\n {\n \"name\": \"Name\",\n \"value\": \"Safety Inspector\"\n }\n ],\n \"pdf_url\": \"https://field-reports.plangrid.com/fd9d4f20-da14-48ee-ad73-c875cf1b4882/4a4eed61-7fe4-448c-91b6-f9248bfc7d9d.pdf\",\n \"pg_form_values\": {},\n \"photos\": {\n \"total_count\": 0,\n \"url\": \"https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/field_reports/4a4eed61-7fe4-448c-91b6-f9248bfc7d9d/photos\"\n },\n \"project_uid\": \"fd9d4f20-da14-48ee-ad73-c875cf1b4882\",\n \"report_date\": \"2018-11-28\",\n \"snapshots\": {\n \"total_count\": 0,\n \"url\": \"https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/field_reports/4a4eed61-7fe4-448c-91b6-f9248bfc7d9d/snapshots\"\n },\n \"title\": \"Safety Checklist\",\n \"uid\": \"4a4eed61-7fe4-448c-91b6-f9248bfc7d9d\",\n \"updated_at\": \"2018-11-28T15:28:20.521415+00:00\",\n \"weather\": {\n \"humidity\": 0.52,\n \"precipitation_accumulation\": null,\n \"precipitation_accumulation_unit\": \"in\",\n \"speed_unit\": \"mph\",\n \"summary_key\": \"clear\",\n \"temperature_max\": 70,\n \"temperature_min\": 42.8,\n \"temperature_unit\": \"Fahrenheit\",\n \"wind_bearing\": 179,\n \"wind_gust\": 19.6,\n \"wind_speed\": 9.7\n }\n }\n ],\n \"next_page_url\": null,\n \"total_count\": 2\n}","language":"json"},{"code":"{\n \"message\": \"Project (fd9d4f20-da14-48ee-ad73-c875cf1b4882) does not exist.\"\n}","language":"json","status":404},{"status":403,"language":"json","code":"{\n \"message\": \"Access to project (fd9d4f20-da14-48ee-ad73-c875cf1b4882) prohibited.\"\n}"}]},"settings":"","auth":"required","params":[{"_id":"5bd8bf48a92a01004400a2c5","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"5bfd95e05d904100449cd507","ref":"","in":"query","required":false,"desc":"Only retrieve field reports 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":"5bd8c1041e8ea301ba6438ac","ref":"","in":"query","required":false,"desc":"Only retrieve field reports between a date range starting with this date in UTC format. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"string","name":"report_date_min"},{"_id":"5bd8c1041e8ea301ba6438ab","ref":"","in":"query","required":false,"desc":"Only retrieve field reports between a date range ending with this date in UTC format. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"string","name":"report_date_max"},{"_id":"5bd8c1041e8ea301ba6438aa","ref":"","in":"query","required":false,"desc":"Sort retrieved field reports either by `report_date` or `updated_at` values.","default":"report_date","type":"string","name":"sort_by"},{"_id":"5bd8c1041e8ea301ba6438a9","ref":"","in":"query","required":false,"desc":"Sort retrieved field reports in either `asc` or `desc` format.","default":"asc","type":"string","name":"sort_order"},{"_id":"5e4335819ed17d0018f78a4f","ref":"","in":"query","required":false,"desc":"The unique identifier of the field report template for which field report instances should be returned.","default":"","type":"string","name":"template_uid"}],"url":"/projects/:project_uid/field_reports","method":"get"},"isReference":false,"order":7,"body":"","excerpt":"Get a list of field reports in a project optionally filtered by report start and end date. Results return archived field reports and are paginated, see [Pagination](docs:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-field-reports-in-a-project","type":"get","title":"Retrieve Field Reports in a Project","__v":32,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}
getRetrieve Field Reports in a Project
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"attachments": {
"total_count": 1,
"url": "https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/field_reports/12528a5e-3865-4ec8-9ec5-64f6859d08a1/attachments"
},
"created_by": {
"email": "[email protected]",
"uid": "57d2e95cfb361f01832cf8e0",
"url": "https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/users/57d2e95cfb361f01832cf8e0"
},
"description": "",
"field_report_type": {
"name": "Daily Report",
"project_uid": "fd9d4f20-da14-48ee-ad73-c875cf1b4882",
"status": "active",
"uid": "b2955f3a-9dae-3de8-82bb-88074d933b14"
},
"pg_form_values": {
"pg_worklog_entries": [
{
"deleted": false,
"description": null,
"headcount": 10,
"timespan": 43200000,
"trade": "Electrical",
"uid": "8e8b3a08-1aad-994c-56ba-929de8ea5926"
}
]
},
"photos": {
"total_count": 1,
"url": "https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/field_reports/12528a5e-3865-4ec8-9ec5-64f6859d08a1/photos"
},
"project_uid": "fd9d4f20-da14-48ee-ad73-c875cf1b4882",
"report_date": "2018-10-30",
"snapshots": {
"total_count": 0,
"url": "https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/field_reports/12528a5e-3865-4ec8-9ec5-64f6859d08a1/snapshots"
},
"title": null,
"uid": "12528a5e-3865-4ec8-9ec5-64f6859d08a1",
"updated_at": "2018-10-30T22:17:56.239734+00:00",
"weather": {
"humidity": 0.77,
"precipitation_accumulation": null,
"precipitation_accumulation_unit": "in",
"speed_unit": "mph",
"summary_key": "rain",
"temperature_max": 81,
"temperature_min": 67,
"temperature_unit": "Fahrenheit",
"wind_bearing": 185,
"wind_gust": 31.7,
"wind_speed": 11.4
}
},
{
"attachments": {
"total_count": 0,
"url": "https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/field_reports/4a4eed61-7fe4-448c-91b6-f9248bfc7d9d/attachments"
},
"created_by": {
"email": "[email protected]",
"uid": "57d2e95cfb361f01832cf8e0",
"url": "https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/users/57d2e95cfb361f01832cf8e0"
},
"description": "",
"field_report_type": {
"name": "Job Hazard Analysis",
"project_uid": "fd9d4f20-da14-48ee-ad73-c875cf1b4882",
"status": "active",
"uid": "ab88e316-6115-41f4-82c5-e41d9495bbee"
},
"pdf_form_values": [
{
"name": "Project",
"value": "Downtown Museum"
},
{
"name": "Date",
"value": "12/25/18"
},
{
"name": "Project_No",
"value": "90201"
},
{
"name": "Location",
"value": "Malibu, CA"
},
{
"name": "Activity",
"value": "Loading presensts"
},
{
"name": "Hazard",
"value": "Elf not wearing protective gear"
},
{
"name": "Corrective Action",
"value": "Provide elves with protective gear"
},
{
"name": "Notes",
"value": ""
},
{
"name": "Name",
"value": "Safety Inspector"
}
],
"pdf_url": "https://field-reports.plangrid.com/fd9d4f20-da14-48ee-ad73-c875cf1b4882/4a4eed61-7fe4-448c-91b6-f9248bfc7d9d.pdf",
"pg_form_values": {},
"photos": {
"total_count": 0,
"url": "https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/field_reports/4a4eed61-7fe4-448c-91b6-f9248bfc7d9d/photos"
},
"project_uid": "fd9d4f20-da14-48ee-ad73-c875cf1b4882",
"report_date": "2018-11-28",
"snapshots": {
"total_count": 0,
"url": "https://io.plangrid.com/projects/fd9d4f20-da14-48ee-ad73-c875cf1b4882/field_reports/4a4eed61-7fe4-448c-91b6-f9248bfc7d9d/snapshots"
},
"title": "Safety Checklist",
"uid": "4a4eed61-7fe4-448c-91b6-f9248bfc7d9d",
"updated_at": "2018-11-28T15:28:20.521415+00:00",
"weather": {
"humidity": 0.52,
"precipitation_accumulation": null,
"precipitation_accumulation_unit": "in",
"speed_unit": "mph",
"summary_key": "clear",
"temperature_max": 70,
"temperature_min": 42.8,
"temperature_unit": "Fahrenheit",
"wind_bearing": 179,
"wind_gust": 19.6,
"wind_speed": 9.7
}
}
],
"next_page_url": null,
"total_count": 2
}
{
"message": "Project (fd9d4f20-da14-48ee-ad73-c875cf1b4882) does not exist."
}
{
"message": "Access to project (fd9d4f20-da14-48ee-ad73-c875cf1b4882) prohibited."
}
{"_id":"5ecd75071d7020003960728f","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","category":"5ecd75071d70200039607213","user":"5c4f7b3b014143002ce6c065","updates":[],"next":{"pages":[],"description":""},"createdAt":"2020-02-11T22:49:54.818Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"method":"get","settings":"","results":{"codes":[{"language":"json","code":"{\n \"data\": [\n {\n \"cadence\": null,\n \"created_by\": {\n \"email\": \"[email protected]\",\n \"uid\": \"509c08e1165f0d0002000236\",\n \"url\": \"https://io.plangrid.com/projects/6495298b-7ce0-a797-f392-055fbe4cbadc/users/509c08e1165f0d0002000236\"\n },\n \"field_reports\": {\n \"url\": \"https://io.plangrid.com/projects/6495298b-7ce0-a797-f392-055fbe4cbadc/field_reports?template_uid=eb543de7-a8b3-4380-aaab-06b7466c899f\"\n },\n \"group_permissions\": [\n {\n \"permissions\": [\n \"review\",\n \"manage\",\n \"submit\"\n ],\n \"role_key\": \"projects.roles.admin\",\n \"role_name\": \"Admin\",\n \"role_uid\": \"9d139e64-cac9-4f23-b4d5-9fd3688b498e\"\n },\n {\n \"permissions\": [\n \"submit\"\n ],\n \"role_key\": \"projects.roles.collaborator\",\n \"role_name\": \"Collaborator\",\n \"role_uid\": \"17dce2c5-4931-47e7-8c98-84b35f00ba03\"\n },\n {\n \"permissions\": [\n \"review\",\n \"submit\"\n ],\n \"role_key\": \"projects.roles.power_collab\",\n \"role_name\": \"Power Collaborator\",\n \"role_uid\": \"e7295fe5-5312-4559-b784-a74498464fb7\"\n }\n ],\n \"is_pdf\": true,\n \"name\": \"(Sample) Daily Report\",\n \"pdf_url\": \"https://plangrid-prod-field-reports.s3.amazonaws.com/default-templates/74f25ca0-1812-47a0-9bd1-216ba125263c.pdf?Signature=YtEVwhqO%2BeqqL%2FU%2Fm6Z8lSvkYnQ%3D&Expires=1611255412&AWSAccessKeyId=AKIAIWQYS4STAYSUNIKQ&response-content-disposition=attachment%3B%20filename%3D%22Daily%20Report%22\",\n \"project_uid\": \"6495298b-7ce0-a797-f392-055fbe4cbadc\",\n \"status\": \"active\",\n \"template_type\": null,\n \"uid\": \"eb543de7-a8b3-4380-aaab-06b7466c899f\",\n \"updated_at\": \"2019-02-28T18:25:01.498610+00:00\",\n \"user_permissions\": [\n {\n \"permissions\": [\n \"manage\",\n \"submit\",\n \"review\"\n ],\n \"user_id\": \"5c48e3dca97740498aed0692\"\n }\n ]\n }\n ],\n \"next_page_url\": null,\n \"total_count\": 2\n}","name":null,"status":200},{"status":404,"language":"json","code":"{\n \"message\": \"Project (fd9d4f20-da14-48ee-ad73-c875cf1b4882) does not exist.\"\n}"},{"code":"{\n \"message\": \"Access to project (fd9d4f20-da14-48ee-ad73-c875cf1b4882) prohibited.\"\n}","language":"json","status":403}]},"examples":{"codes":[]},"auth":"required","params":[{"name":"project_uid","type":"string","default":"","desc":"Unique identifier of project.","required":true,"in":"path","ref":"","_id":"5bd8bf48a92a01004400a2c5"},{"name":"updated_after","type":"datetime","default":"","desc":"Only retrieve field reports created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","required":false,"in":"query","ref":"","_id":"5bfd95e05d904100449cd507"},{"name":"updated_before","type":"datetime","default":"","desc":"Only retrieve field reports created/updated before specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","required":false,"in":"query","ref":"","_id":"5e432f92c27c0b0042dc4f94"},{"name":"limit","type":"int","default":"50","desc":"Number of report templates to retrieve. Maximum value of 50.","required":false,"in":"query","ref":"","_id":"5e432f92c27c0b0042dc4f92"},{"name":"skip","type":"int","default":"0","desc":"Number of photos to skip in the set of results.","required":false,"in":"query","ref":"","_id":"5e432f92c27c0b0042dc4f93"}],"url":"/projects/:project_uid/field_report_templates"},"isReference":false,"order":8,"body":"","excerpt":"Get a list of field report templates in a project optionally filtered by updated after and updated before dates. See [The Field Report Template Object](doc:the-field-report-template-object). Results return archived field report templates and are paginated, see [Pagination](docs:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-field-report-templates-in-a-project","type":"get","title":"Retrieve Field Report Templates in a Project","__v":7,"parentDoc":null,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}
getRetrieve Field Report Templates in a Project
Path Params
Query Params
Definition
Result Format
{
"data": [
{
"cadence": null,
"created_by": {
"email": "[email protected]",
"uid": "509c08e1165f0d0002000236",
"url": "https://io.plangrid.com/projects/6495298b-7ce0-a797-f392-055fbe4cbadc/users/509c08e1165f0d0002000236"
},
"field_reports": {
"url": "https://io.plangrid.com/projects/6495298b-7ce0-a797-f392-055fbe4cbadc/field_reports?template_uid=eb543de7-a8b3-4380-aaab-06b7466c899f"
},
"group_permissions": [
{
"permissions": [
"review",
"manage",
"submit"
],
"role_key": "projects.roles.admin",
"role_name": "Admin",
"role_uid": "9d139e64-cac9-4f23-b4d5-9fd3688b498e"
},
{
"permissions": [
"submit"
],
"role_key": "projects.roles.collaborator",
"role_name": "Collaborator",
"role_uid": "17dce2c5-4931-47e7-8c98-84b35f00ba03"
},
{
"permissions": [
"review",
"submit"
],
"role_key": "projects.roles.power_collab",
"role_name": "Power Collaborator",
"role_uid": "e7295fe5-5312-4559-b784-a74498464fb7"
}
],
"is_pdf": true,
"name": "(Sample) Daily Report",
"pdf_url": "https://plangrid-prod-field-reports.s3.amazonaws.com/default-templates/74f25ca0-1812-47a0-9bd1-216ba125263c.pdf?Signature=YtEVwhqO%2BeqqL%2FU%2Fm6Z8lSvkYnQ%3D&Expires=1611255412&AWSAccessKeyId=AKIAIWQYS4STAYSUNIKQ&response-content-disposition=attachment%3B%20filename%3D%22Daily%20Report%22",
"project_uid": "6495298b-7ce0-a797-f392-055fbe4cbadc",
"status": "active",
"template_type": null,
"uid": "eb543de7-a8b3-4380-aaab-06b7466c899f",
"updated_at": "2019-02-28T18:25:01.498610+00:00",
"user_permissions": [
{
"permissions": [
"manage",
"submit",
"review"
],
"user_id": "5c48e3dca97740498aed0692"
}
]
}
],
"next_page_url": null,
"total_count": 2
}
{
"message": "Project (fd9d4f20-da14-48ee-ad73-c875cf1b4882) does not exist."
}
{
"message": "Access to project (fd9d4f20-da14-48ee-ad73-c875cf1b4882) prohibited."
}
{"_id":"5ecd75071d7020003960726f","category":"5ecd75071d70200039607209","parentDoc":null,"user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","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\\\": \\\"[email protected]\\\" \\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"deleted": false
}
{"_id":"5ecd75071d70200039607270","category":"5ecd75071d70200039607209","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d70200039607271","category":"5ecd75071d70200039607209","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"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":"5ecd75071d70200039607272","category":"5ecd75071d70200039607209","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"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": "[email protected]"
},
"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":"5ecd75071d70200039607273","category":"5ecd75071d70200039607209","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"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":"5ecd75071d70200039607274","category":"5ecd75071d70200039607209","user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","parentDoc":null,"version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"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":"5ecd75071d70200039607275","category":"5ecd75071d70200039607209","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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,"metadata":{"title":"","description":"","image":[]},"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":"5ecd75071d7020003960721f","category":"5ecd75071d7020003960720a","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5ecd75071d702000396072a2","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\\\": \\\"[email protected]\\\"\\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\\\": \\\"[email protected]\\\"\\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\\\": \\\"[email protected]\\\"\\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\\\": \\\"[email protected]\\\"\\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
{
"uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
"email": "[email protected]"
}
],
"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": "[email protected]"
},
"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": "[email protected]"
},
"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":"5ecd75071d70200039607220","category":"5ecd75071d7020003960720a","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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\\\": \\\"[email protected]\\\"\\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\\\": \\\"[email protected]\\\"\\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\\\": \\\"[email protected]\\\"\\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\\\": \\\"[email protected]\\\"\\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
}
],
"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": "[email protected]"
},
{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "[email protected]"
}
],
"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": "[email protected]"
}
}
{"_id":"5ecd75071d70200039607221","category":"5ecd75071d7020003960720a","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
}
],
"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": "[email protected]"
},
"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": "[email protected]"
},
"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":"5ecd75071d70200039607222","category":"5ecd75071d7020003960720a","user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","parentDoc":null,"version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
}
],
"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": "[email protected]"
},
"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": "[email protected]"
},
"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": "[email protected]"
},
{
"uid": "e5eb1338-e8c0-4a1a-8191-bcc082a8bc96",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/e5eb1338-e8c0-4a1a-8191-bcc082a8bc96",
"email": "[email protected]"
}
],
"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": "[email protected]"
},
"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": "[email protected]"
},
"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":"5ecd75071d70200039607223","category":"5ecd75071d7020003960720a","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
}
],
"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": "[email protected]"
},
"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": "[email protected]"
},
"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":"5ecd75071d70200039607224","category":"5ecd75071d7020003960720a","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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\": \"[email protected]on.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 documents to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ece5267d70b00494bbe","ref":"","in":"query","required":false,"desc":"Number of documents 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":1,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"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": "[email protected]"
},
"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":"5ecd75071d70200039607225","category":"5ecd75071d7020003960720a","project":"55d2023b3c74062300aee506","parentDoc":null,"user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"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": "[email protected]"
},
"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":"5ecd75071d70200039607226","category":"5ecd75071d7020003960720a","parentDoc":null,"user":"55d201fe945e481700afbb19","project":"55d2023b3c74062300aee506","version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"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": "[email protected]"
},
"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":"5ecd75071d70200039607227","category":"5ecd75071d7020003960720a","project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","parentDoc":null,"version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
},
"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": "[email protected]"
},
"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": "[email protected]"
},
"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": "[email protected]"
},
"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":"5ecd75071d70200039607228","category":"5ecd75071d7020003960720a","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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\": \"[email protected]\"\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,"metadata":{"title":"","description":"","image":[]},"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": "[email protected]"
}
},
{
"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": "[email protected]"
}
],
"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": "[email protected]"
},
{
"uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
"url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
"email": "[email protected]"
}
],
"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": "[email protected]"
}
},
{
"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": "[email protected]ractor.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": "[email protected]"
},
},
],
"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."
}
{"_id":"5ecd75071d70200039607229","category":"5ecd75071d7020003960720a","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"5ecd75071d702000396072a2","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:33:29.568Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","examples":{"codes":[]},"method":"patch","results":{"codes":[{"name":"Success","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\": \"[email protected]\"\n }\n ],\n \"updated_at\": \"2015-08-23T19:22:56+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\": \"[email protected]\"\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\": \"[email protected]\"\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","language":"json","status":200},{"status":400,"name":"Invalid Status","code":"{\n \"message\": \"Status (4898bfd4) must be a valid RFI status on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","language":"json"},{"name":"Invalid Locked","code":"{\n \"message\": \"Locked must be a boolean.\"\n}\n","language":"json","status":400},{"language":"json","status":400,"name":"Invalid Title","code":"{\n \"message\": \"Title (2) must be null or a string.\"\n}\n"},{"status":400,"name":"Title Length","code":"{\n \"message\": \"RFI title cannot exceed 200 characters.\"\n}\n","language":"json"},{"status":400,"name":"Invalid Question","code":"{\n \"message\": \"Question (10) must be null or a string.\"\n}\n","language":"json"},{"status":400,"name":"Question Length","code":"{\n \"message\": \"RFI question cannot exceed 10000 characters.\"\n}\n","language":"json"},{"status":400,"name":"Invalid Answer","code":"{\n \"message\": \"Answer (3) must be null or a string.\"\n}\n","language":"json"},{"status":400,"name":"Answer Length","code":"{\n \"message\": \"RFI answer cannot exceed 10000 characters.\"\n}\n","language":"json"},{"status":400,"name":"Invalid Sent At","code":"{\n \"message\": \"Sent date (2015-9-2) must be null or a datetime in ISO-8601 format.\"\n}\n","language":"json"},{"status":400,"name":"Invalid Due At","code":"{\n \"message\": \"Due date (2015-9-2) must be null or a datetime in ISO-8601 format.\"\n}\n","language":"json"},{"code":"{\n \"message\": \"Assignees ([0, bb29c783-bfb7-4664-8362-ba2ca716cade]) must be an array of UIDs of users on project.\"\n}\n","language":"json","status":400,"name":"Invalid Assigned To"},{"name":"Assignee Missing","code":"{\n \"message\": \"Assignee (9003a891-8a49-4c91-9682-668b1a8a4241) is not on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","language":"json","status":400},{"language":"json","status":400,"name":"RFI Locked","code":"{\n \"message\": \"RFI (22f3530a-a00b-42f9-8139-3a7554c77c27) must be unlocked before it can be updated.\"\n}\n"},{"code":"{\n \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","language":"json","status":404,"name":"Project Missing"},{"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"},{"status":403,"name":"No Access","code":"{\n \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","language":"json"}]},"auth":"required","params":[{"_id":"56cf1ed05267d70b00494be1","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ed05267d70b00494be0","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI to update.","default":"","type":"string","name":"rfi_uid"},{"_id":"56cf1ed05267d70b00494bdf","ref":"","in":"body","required":false,"desc":"Unique identifier of the RFI's new status.","default":"","type":"string","name":"status"},{"_id":"56cf1ed05267d70b00494bde","ref":"","in":"body","required":false,"desc":"Whether the RFI is locked.","default":"","type":"boolean","name":"locked"},{"_id":"56cf1ed05267d70b00494bdd","ref":"","in":"body","required":false,"desc":"The RFI title.","default":"","type":"string","name":"title"},{"_id":"56cf1ed05267d70b00494bdc","ref":"","in":"body","required":false,"desc":"The RFI question.","default":"","type":"string","name":"question"},{"_id":"56cf1ed05267d70b00494bdb","ref":"","in":"body","required":false,"desc":"The RFI answer.","default":"","type":"string","name":"answer"},{"_id":"56cf1ed05267d70b00494bda","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":"","type":"datetime","name":"sent_at"},{"_id":"56cf1ed05267d70b00494bd9","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":"","type":"datetime","name":"due_at"},{"_id":"56cf1ed05267d70b00494bd8","ref":"","in":"body","required":false,"desc":"Array of unique identifiers of users who are RFI assignees and replaces the current list of assignees.","default":"","type":"array_string","name":"assigned_to_uids"}],"url":"/projects/:project_uid/rfis/:rfi_uid"},"isReference":false,"order":10,"body":"","excerpt":"Updates an RFI on a project and sends appropriate notifications (e.g. to new assignees).","slug":"update-rfi-in-a-project","type":"patch","title":"Update RFI in a Project","__v":0,"metadata":{"title":"","description":"","image":[]},"childrenPages":[]}
patchUpdate 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-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": "[email protected]"
}
],
"updated_at": "2015-08-23T19:22:56+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": "[email protected]"
},
"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": "[email protected]"
},
"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"
}
}
{
"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 date (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": "RFI (22f3530a-a00b-42f9-8139-3a7554c77c27) must be unlocked before it can be updated."
}
{
"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."
}