{"category":"58fe37462b628c0f0033a793","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":["5835c945524e752500ba93bc"],"_id":"58fe37462b628c0f0033a7bb","next":{"pages":[],"description":""},"createdAt":"2015-09-27T18:57:20.311Z","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 hosted at [io.plangrid.com](https://io.plangrid.com).\n\nThis documentation describes PlanGrid’s API standards, data model, and endpoints. We strive for documentation that is understandable, detailed, and comprehensive. Please suggest edits when you feel we’re not accomplishing these goals (or forget commas).\n\nEvery endpoint in the PlanGrid API has a dedicated section and can be tested using the API Explorer (accessed via a button at the end of the section). The API Explorer may require you to enter your API key.","excerpt":"Our promise.","slug":"introduction","type":"basic","title":"Introduction","__v":0,"childrenPages":[]}

Introduction

Our promise.

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.

View all 60 endpoints
{"category":"58fe37462b628c0f0033a793","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7bc","next":{"pages":[],"description":""},"createdAt":"2016-10-20T20:41:42.171Z","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":"Our team is happy to answer any questions, address any frustrations, or consider any requests. You can communicate with us in the following ways:\n\n- [Request an invite](mailto:developers@plangrid.com?subject=PlanGrid API Slack channel invite request) to our Slack channel to chat with us and other PlanGrid API experts.\n- Post a question in [Stack Overflow](http://stackoverflow.com/questions/tagged/plangrid-api) and tag it with [`plangrid-api`](http://stackoverflow.com/questions/tagged/plangrid-api).\n- Contact support directly by emailing [developers@plangrid.com](mailto:developers@plangrid.com).\n\nWe'll do our best to accommodate you.","excerpt":"Did you try turning it off and on again?","slug":"support","type":"basic","title":"Support","__v":0,"childrenPages":[]}

Support

Did you try turning it off and on again?

Our team is happy to answer any questions, address any frustrations, or consider any requests. You can communicate with us in the following ways:

We'll do our best to accommodate you.

{"__v":0,"_id":"58fe37462b628c0f0033a7bd","api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","auth":"required","params":[],"url":""},"body":"We use conventions in our documentation to help you navigate and understand it.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Nomenclature\"\n}\n[/block]\nWe use consistent naming to describe concepts and features of an API:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"*Record*\",\n    \"0-1\": \"A single, implicitly structured data item. 99% of the time they have a unique identifier.\",\n    \"0-2\": \"Each project in PlanGrid is considered a record\",\n    \"1-0\": \"*Attribute* \",\n    \"1-1\": \"A named value inside a record.\",\n    \"1-2\": \"`project.name`\",\n    \"2-0\": \"*Object* \",\n    \"2-1\": \"Represents and defines a common record.\",\n    \"2-2\": \"[The Project object](doc:the-project-object)\",\n    \"4-0\": \"*Endpoint* \",\n    \"4-1\": \"An API method\",\n    \"5-0\": \"*Parameter* \",\n    \"5-1\": \"A variable value passed to an endpoint\",\n    \"4-2\": \"GET `/projects`\",\n    \"5-2\": \"POST `/projects` needs a `name` parameter\",\n    \"6-0\": \"*Request* \",\n    \"6-1\": \"Calling an endpoint via an HTTP request\",\n    \"6-2\": \"-\",\n    \"h-0\": \"Word\",\n    \"h-1\": \"Meaning\",\n    \"h-2\": \"Example\",\n    \"3-2\": \"[The RFI object](doc:the-rfi-object) contains an attribute that is a reference to its comments `rfi.comments`\",\n    \"3-1\": \"A pointer or foreign key to a record\",\n    \"3-0\": \"*Reference*\",\n    \"7-0\": \"*Response*\",\n    \"7-1\": \"The result of an HTTP request to an endpoint\",\n    \"7-2\": \"-\"\n  },\n  \"cols\": 3,\n  \"rows\": 8\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Organization\"\n}\n[/block]\nOur documentation is structured into categories in the following order:\n\n- *Introduction* - Introduces you to the API, our documentation, and how to start using it.\n- *Standards* - Describes our API standards and conventions.\n- *Common Objects* - Describes common objects used across multiple endpoints. Pages are ordered alphabetically.\n- *[Resource]* - Resource accessed via a URL pattern of `/[resource]` or `/projects/:project_uid/[resource]`. Ordered alphabetically.\n\n### Resources\n\nTo make the table of contents easily skimmable, documentation pages in Resource categories order by [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete):\n\n- Object definitions and background information on the resource\n- Endpoints and associated documentation to create a record\n- Endpoints and associated documentation to list records\n- Endpoints and associated documentation to retrieve single records\n- Endpoints and associated documentation to update a record\n- Endpoints and associated documentation to remove a record\n- Miscellanious endpoints and associated documentation related to the resource","category":"58fe37462b628c0f0033a793","createdAt":"2016-10-20T20:55:50.291Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","next":{"pages":[],"description":""},"order":2,"parentDoc":null,"project":"55d2023b3c74062300aee506","slug":"documentation-conventions","sync_unique":"","title":"Conventions","type":"basic","updates":[],"user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","childrenPages":[]}

Conventions


We use conventions in our documentation to help you navigate and understand it.

Nomenclature

We use consistent naming to describe concepts and features of an API:

Word
Meaning
Example

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

Object

Represents and defines a common record.

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

-

Organization

Our documentation is structured into categories in the following order:

  • Introduction - Introduces you to the API, our documentation, and how to start using it.
  • Standards - Describes our API standards and conventions.
  • Common Objects - Describes common objects used across multiple endpoints. Pages are ordered alphabetically.
  • [Resource] - Resource accessed via a URL pattern of /[resource] or /projects/:project_uid/[resource]. Ordered alphabetically.

Resources

To make the table of contents easily skimmable, documentation pages in Resource categories order by CRUD:

  • Object definitions and background information on the resource
  • Endpoints and associated documentation to create a record
  • Endpoints and associated documentation to list records
  • Endpoints and associated documentation to retrieve single records
  • Endpoints and associated documentation to update a record
  • Endpoints and associated documentation to remove a record
  • Miscellanious endpoints and associated documentation related to the resource
{"category":"58fe37462b628c0f0033a793","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7be","next":{"pages":[],"description":""},"createdAt":"2016-08-04T17:56:01.191Z","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":3,"body":"To make it even easier to get started with the PlanGrid API, we provide libraries for the following languages and frameworks:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Language/Framework\",\n    \"h-1\": \"Source/Download\",\n    \"0-1\": \"[plangrid-api-net](https://github.com/plangrid/plangrid-api-net)\",\n    \"0-0\": \".NET\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\nIf you've built a library for the PlanGrid API and would like it listed, please [contact support](mailto:developers@plangrid.com).","excerpt":"Oh my!","slug":"libraries-and-sdks","type":"basic","title":"Libraries, SDKs, and Packages","__v":0,"childrenPages":[]}

Libraries, SDKs, and Packages

Oh my!

To make it even easier to get started with the PlanGrid API, we provide libraries for the following languages and frameworks:

Language/Framework
Source/Download

If you've built a library for the PlanGrid API and would like it listed, please contact support.

{"category":"58fe37462b628c0f0033a793","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7bf","next":{"pages":[],"description":""},"createdAt":"2016-07-26T21:58:12.172Z","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":4,"body":"We provide API access to PlanGrid customers and partners. If you're a customer, [please contact sales](https://www.plangrid.com/contact/) to purchase API access. If you're a software vendor interested in partnering, [please contact our partnerships team](mailto:partners@plangrid.com).","excerpt":"Tickets?","slug":"access","type":"basic","title":"Access","__v":0,"childrenPages":[]}

Access

Tickets?

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.

{"category":"58fe37462b628c0f0033a793","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7c0","next":{"pages":[],"description":""},"createdAt":"2015-09-04T23:55:39.000Z","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":5,"body":"We don’t expect you to read our documentation like a book (you’ll get a little bored). Instead, we’d like to get you started right away and help you find the documentation you need. If that sounds appealing, keep reading. Otherwise, jump to [Standards](doc:getting-started).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Get a List of Your Projects\"\n}\n[/block]\nWith 5 seconds of effort, you’ll grab a list of PlanGrid projects. We'll send HTTP requests to the PlanGrid API via the `curl` command. On Windows, you’ll need to install `curl` by downloading and running the “#.#.# - SSL enabled SSH enabled” installer [here](http://curl.haxx.se/dlwiz/?type=bin&os=Win32&flav=-&ver=*).\n\nOpen up a Terminal (OS X) or Command Prompt (Windows) and run the following command:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -i https://io.plangrid.com/projects -u [[app:key]]: -H \\\"Accept: application/vnd.plangrid+json; version=1\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nBelow your command a list of projects should have been returned.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"data\\\": [\\n    {\\n      \\\"uid\\\": \\\"bafce976-8f33-437f-9c52-fb274456940f\\\",\\n      \\\"name\\\": \\\"LA Natural History Museum\\\"\\n    },\\n    {\\n      \\\"uid\\\": \\\"327e8c64-a70d-433c-b4ac-d077415a5547\\\",\\n      \\\"name\\\": \\\"3265 17th Street\\\"\\n    }\\n  ],\\n  \\\"total_count\\\": 2,\\n  \\\"next_page_url\\\": null\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\nCongratulations, you’ve successfully used the PlanGrid API! You may have noticed that you only received fifty projects; the reason is we paginate our results. You can learn more in [Pagination](doc:pagination).","excerpt":"Get your first data out of PlanGrid faster than a Camaro can do 0-60.","slug":"getting-started-1","type":"basic","title":"Quick Start","__v":0,"childrenPages":[]}

Quick Start

Get your first data out of PlanGrid faster than a Camaro can do 0-60.

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.

Get a List of Your Projects

With 5 seconds of effort, you’ll grab a list of PlanGrid projects. We'll send HTTP requests to the PlanGrid API via the curl command. On Windows, you’ll need to install curl by downloading and running the “#.#.# - SSL enabled SSH enabled” installer here.

Open up a Terminal (OS X) or Command Prompt (Windows) and run the following command:

curl -i https://io.plangrid.com/projects -u [[app:key]]: -H "Accept: application/vnd.plangrid+json; version=1"

Below your command a list of projects should have been returned.

Congratulations, you’ve successfully used the PlanGrid API! You may have noticed that you only received fifty projects; the reason is we paginate our results. You can learn more in Pagination.

{
  "data": [
    {
      "uid": "bafce976-8f33-437f-9c52-fb274456940f",
      "name": "LA Natural History Museum"
    },
    {
      "uid": "327e8c64-a70d-433c-b4ac-d077415a5547",
      "name": "3265 17th Street"
    }
  ],
  "total_count": 2,
  "next_page_url": null
}
{"category":"58fe37462b628c0f0033a794","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7a8","next":{"pages":[],"description":""},"createdAt":"2015-08-17T15:48:13.217Z","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":6,"body":"The PlanGrid API is a [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer) API that uses predictable, resource-oriented URLs and standard [HTTP response codes](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes). It uses built-in HTTP features, such as HTTP authentication and HTTP verbs, so it can be understood by off-the-shelf HTTP clients.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Security\"\n}\n[/block]\nPlanGrid [values](https://help.plangrid.com/customer/portal/articles/1253410-how-secure-is-plangrid-) the security of your data, and all API requests must be made over [HTTPS](https://en.wikipedia.org/wiki/HTTPS). \n\nWe strongly recommend you keep your API key as secure as possible:\n\n- Don't store it in publicly accessible code (e.g. Javascript for a public website).\n- Avoid checking it into source control. Use configuration files that can be loaded into your code.\n\nIf you think your API key is compromised, don't hesitate to [contact support](mailto:developers@plangrid.com). We will deactivate your API key and issue a new one.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"HTTP Verbs\"\n}\n[/block]\nPlanGrid’s API follows IETF standards ([RFC 5789](http://tools.ietf.org/html/rfc5789) & [RFC 7231](https://tools.ietf.org/html/rfc7231#section-4.3)) when using HTTP methods. A summary is provided below:\n\n| Verb | Used for... |\n|------|-------------|\n| GET | Retrieving records |\n| POST | Creating records |\n| PUT | Replacing records |\n| PATCH | Updating records |\n| DELETE | Deleting records |\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Responses\"\n}\n[/block]\nAll responses return [JSON](http://www.json.org/), including errors.\n\n### Blank Attributes\n\nBlank attributes are included as null instead of being omitted. The example below illustrates how the API would return an issue where `assignee`, `room`, and `current_annotation` are blank:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"uid\\\": \\\"22f3530a-a00b-42f9-8139-3a7554c77c27\\\",\\n  \\\"number\\\": 1,\\n  \\\"current_annotation\\\": null,\\n  \\\"title\\\": \\\"Electrical\\\",\\n  \\\"description\\\": \\\"Missing wall outlets.\\\",\\n  \\\"assigned_to\\\": null,\\n  \\\"status\\\": \\\"open\\\",\\n  \\\"created_at\\\": \\\"2015-06-08T18:04:02+00:00\\\",\\n  \\\"created_by\\\": {\\n    \\\"email\\\": \\\"alfred@architect.com\\\"\\n  },\\n  \\\"updated_at\\\": \\\"2013-05-23T19:22:56+00:00\\\",\\n  \\\"room\\\": null,\\n  \\\"updated_by\\\": {\\n    \\\"email\\\": \\\"betty@construction.com\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n### Errors\n\nErrors return a JSON object with a human readable message:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"message\\\": \\\"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nThe value of `message` may be updated in minor and patch versions; don’t write conditions that depend on it.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Requests\"\n}\n[/block]\nMany API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path (prefixed by `:` in our documentation) can be passed as an HTTP query string parameter (prefixed by `?` in our documentation).\n\nIn the example below, the `:project_uid` parameter is passed in as a segment of the URL path while pagination parameters (`?page` and `?per_page`) are passed in as HTTP query string parameters:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://io.plangrid.com/projects/bafce976-8f33-437f-9c58-fb274456940f/issues?page=2&per_page=10 -u [[app:key]]: -H \\\"Accept: application/vnd.plangrid+json; version=1\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nFor POST and PUT requests, parameters not included in the URL are passed in the request body. All request bodies must be encoded as JSON with a Content-Type of `‘application/json’`.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Unique Identifiers\"\n}\n[/block]\nEvery record\\* stored in PlanGrid is assigned a *universally* unique identifier (`uid`) that will not change. UIDs are strings with four dashes between thirty-two alphanumeric characters: `“cce19790-2f7b-46fc-ade0-c932181c35d9”`. You can safely use the PlanGrid `uid` when mapping PlanGrid records with another system’s records.\n\n<sub>* The two exceptions are the [RFI status record](doc:the-rfi-status-object) and [permission role record](doc:the-role-object). For RFI status records, the unique identifiers are strings with 8 alphanumeric characters (`'4898bfd4'`). The unique identifiers for permission role records are strings with four dashes between thirty-two alphanumeric characters (`'17dce2c5-4931-47e7-8c98-84b35f00ba03'`) but are _not_ universally unique.</sub>","excerpt":"Some basic conventions we've established.","slug":"getting-started","type":"basic","title":"Basics","__v":0,"childrenPages":[]}

Basics

Some basic conventions we've established.

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.

Security

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.

HTTP Verbs

PlanGrid’s API follows IETF standards (RFC 5789 & RFC 7231) when using HTTP methods. A summary is provided below:

Verb Used for...
GET Retrieving records
POST Creating records
PUT Replacing records
PATCH Updating records
DELETE Deleting records

Responses

All responses return JSON, including errors.

Blank Attributes

Blank attributes are included as null instead of being omitted. The example below illustrates how the API would return an issue where assignee, room, and current_annotation are blank:

{
  "uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
  "number": 1,
  "current_annotation": null,
  "title": "Electrical",
  "description": "Missing wall outlets.",
  "assigned_to": null,
  "status": "open",
  "created_at": "2015-06-08T18:04:02+00:00",
  "created_by": {
    "email": "alfred@architect.com"
  },
  "updated_at": "2013-05-23T19:22:56+00:00",
  "room": null,
  "updated_by": {
    "email": "betty@construction.com"
  }
}

Errors

Errors return a JSON object with a human readable message:

{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}

The value of message may be updated in minor and patch versions; don’t write conditions that depend on it.

Requests

Many API methods take optional parameters. For GET requests, any parameters not specified as a segment in the path (prefixed by : in our documentation) can be passed as an HTTP query string parameter (prefixed by ? in our documentation).

In the example below, the :project_uid parameter is passed in as a segment of the URL path while pagination parameters (?page and ?per_page) are passed in as HTTP query string parameters:

curl https://io.plangrid.com/projects/bafce976-8f33-437f-9c58-fb274456940f/issues?page=2&per_page=10 -u [[app:key]]: -H "Accept: application/vnd.plangrid+json; version=1"

For POST and PUT requests, parameters not included in the URL are passed in the request body. All request bodies must be encoded as JSON with a Content-Type of ‘application/json’.

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.

{"category":"58fe37462b628c0f0033a794","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7a9","next":{"pages":[],"description":""},"createdAt":"2015-09-02T23:46:36.592Z","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":7,"body":"We provide you two methods to authenticate with our API: [OAuth 2.0](https://oauth.net/2/) and [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). Depending on the use case and requirements, either method can be used to request PlanGrid data. For most applications we recommend using OAuth 2.0.\n[block:api-header]\n{\n  \"title\": \"OAuth\"\n}\n[/block]\nOur API provides OAuth 2.0 as a protocol for authenticating and authorizing PlanGrid users. When using OAuth, a PlanGrid user will be required to log into their PlanGrid account and authorize your application access to their PlanGrid data. \n\nIf you are a developer looking to get started with OAuth, please [contact us](mailto:developers@plangrid.com) to register your application and obtain your credentials. Once you have received your credentials, you can jump to [Getting Started with OAuth](doc:getting-started-with-oauth).\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Registering your application\",\n  \"body\": \"The following will be required when providing information about your application: application name, logo, and a list of redirect URIs.\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"title\": \"HTTP Basic Auth\"\n}\n[/block]\nTo use HTTP Basic Auth, you must send your API key with every request to the PlanGrid API. Put your API key as the basic auth username and leave the password blank:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://io.plangrid.com/projects -u [[app:key]]: -H \\\"Accept: application/vnd.plangrid+json; version=1\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nIf your API key is missing, the API will respond with a 401 status code. When the provided key is wrong or deactivated, the API will respond with a 403 status code. All three situations return a human-readable response specific to the situation.","excerpt":"Don’t trust strangers.","slug":"authentication","type":"basic","title":"Authentication","__v":0,"childrenPages":[]}

Authentication

Don’t trust strangers.

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.

OAuth

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.

HTTP Basic Auth

To use HTTP Basic Auth, you must send your API key with every request to the PlanGrid API. Put your API key as the basic auth username and leave the password blank:

curl https://io.plangrid.com/projects -u [[app:key]]: -H "Accept: application/vnd.plangrid+json; version=1"

If your API key is missing, the API will respond with a 401 status code. When the provided key is wrong or deactivated, the API will respond with a 403 status code. All three situations return a human-readable response specific to the situation.

{"category":"58fe37462b628c0f0033a794","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7aa","next":{"pages":[],"description":""},"createdAt":"2015-09-10T23:44:47.701Z","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":8,"body":"PlanGrid API versioning follows [semantic versioning](http://semver.org/). Any PlanGrid API version will be of the form `MAJOR.MINOR.PATCH`. Given a version number `MAJOR.MINOR.PATCH`, we increment the:\n\n- `MAJOR` version when we make incompatible API changes,\n- `MINOR` version when we add functionality in a backwards-compatible manner, and\n- `PATCH` version when we make backwards-compatible bug fixes.\n\nYou can use any `MINOR` and `PATCH` versions without fear of breaking changes.\n\nYou must explicitely specify the `MAJOR` version of the PlanGrid API via the `Accept` header:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Accept: application/vnd.plangrid+json; version=[:MAJOR]\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nFor instance, with `curl`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://io.plangrid.com/... -H \\\"Accept: application/vnd.plangrid+json; version=1\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Version Support\"\n}\n[/block]\n`MAJOR` versions will be deprecated over time and you will have a 6 month grace period to migrate to a new `MAJOR` version. You will receive a notification via the account email when a `MAJOR` version is deprecated and each subsequent month you continue to use it. After the grace period, you will no longer have access to the deprecated version. \n\nWe will consider longer migration times for future `MAJOR` versions. Please [contact support](mailto:developers@plangrid.com) immediately if you cannot migrate to a newer `MAJOR` version in 6 months.","excerpt":"How we version the API.","slug":"api-versioning","type":"basic","title":"API Versioning","__v":0,"childrenPages":[]}

API Versioning

How we version the API.

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, and
  • PATCH version when we make backwards-compatible bug fixes.

You can use any MINOR and PATCH versions without fear of breaking changes.

You must explicitely specify the MAJOR version of the PlanGrid API via the Accept header:

Accept: application/vnd.plangrid+json; version=[:MAJOR]

For instance, with curl:

curl https://io.plangrid.com/... -H "Accept: application/vnd.plangrid+json; version=1"

Version Support

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.

{"category":"58fe37462b628c0f0033a794","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7ab","next":{"pages":[],"description":""},"createdAt":"2016-03-20T21:53:30.633Z","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":9,"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":"deleting-records","type":"basic","title":"Deleted Records","__v":0,"childrenPages":[]}

Deleted Records

"Dawn of the Deleted"

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.

{"category":"58fe37462b628c0f0033a794","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7ac","next":{"pages":[],"description":""},"createdAt":"2015-12-21T01:31:58.176Z","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":10,"body":"When adding records such as photos or attachments, 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 an attachment 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 attachment record:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"deleted\\\": false,\\n  \\\"created_at\\\": \\\"2015-12-22T06:11:56.849904+00:00\\\",\\n  \\\"name\\\": \\\"0001-060000-1.pdf\\\",\\n  \\\"uid\\\": \\\"ba65bfcf-a1fe-4dd4-9ef6-b381ac877174\\\",\\n  \\\"url\\\": \\\"https://attachments.s3.amazonaws.com/da48fcc3-7af1-4fd6-a083-70195468718a/ba65bfcf-a1fe-4dd4-9ef6-b381ac877174_0001-060000-1.pdf?Signature=xc10DykUH8z4rcYMo8x%2F4PiH294%3D&Expires=1450782716&AWSAccessKeyId=AKIAIWKPH7OCNIEE5GGQ&response-content-disposition=attachment%3B%20filename%3D%220001-060000-1.pdf%22\\\",\\n  \\\"created_by\\\": {\\n    \\\"email\\\": \\\"abhik@plangrid.com\\\",\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/da48fcc3-7af1-4fd6-a083-70195468718a/users/54ab24c10d1c74ff22ae4874\\\",\\n    \\\"uid\\\": \\\"54ab24c10d1c74ff22ae4874\\\"\\n  },\\n  \\\"folder\\\": \\\"Submittals\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"Give us your PDFs, your GIFs, your JPEGs yearning to be rendered.","slug":"file-uploads","type":"basic","title":"File Uploads","__v":0,"childrenPages":[]}

File Uploads

Give us your PDFs, your GIFs, your JPEGs yearning to be rendered.

When adding records such as photos or attachments, you'll need to upload the record's file to PlanGrid. This is a two to three step process with the PlanGrid API:

  1. 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).
  2. 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 URL
    • aws_post_form_arguments.fields are the key-value pairs for the POST form fields.
  3. 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 an attachment 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 attachment record:

{
  "deleted": false,
  "created_at": "2015-12-22T06:11:56.849904+00:00",
  "name": "0001-060000-1.pdf",
  "uid": "ba65bfcf-a1fe-4dd4-9ef6-b381ac877174",
  "url": "https://attachments.s3.amazonaws.com/da48fcc3-7af1-4fd6-a083-70195468718a/ba65bfcf-a1fe-4dd4-9ef6-b381ac877174_0001-060000-1.pdf?Signature=xc10DykUH8z4rcYMo8x%2F4PiH294%3D&Expires=1450782716&AWSAccessKeyId=AKIAIWKPH7OCNIEE5GGQ&response-content-disposition=attachment%3B%20filename%3D%220001-060000-1.pdf%22",
  "created_by": {
    "email": "abhik@plangrid.com",
    "url": "https://io.plangrid.com/projects/da48fcc3-7af1-4fd6-a083-70195468718a/users/54ab24c10d1c74ff22ae4874",
    "uid": "54ab24c10d1c74ff22ae4874"
  },
  "folder": "Submittals"
}
{"category":"58fe37462b628c0f0033a794","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7ad","next":{"pages":[],"description":""},"createdAt":"2015-10-23T22:33:46.706Z","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":11,"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), [attachments](doc:the-attachment-object)), users are referenced by email in PlanGrid's database. The email may not map to a real PlanGrid account, and the PlanGrid API will return a reference with `uid` and `url` set to `null`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"created_by\\\": {\\n    \\\"uid\\\": null,\\n    \\\"url\\\": null,\\n    \\\"email\\\": \\\"richard@subcontractor.com\\\"\\n  }\\n  ...\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"**uid**\\n`string`\",\n    \"0-1\": \"May be blank.\",\n    \"1-0\": \"**url**\\n`string`\",\n    \"1-1\": \"The URL to retrieve the user record's data. May be blank.\",\n    \"2-0\": \"**email**\\n`string`\",\n    \"2-1\": \"User’s account email. May not be a valid email. Never blank.\",\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\nWhen a collection of users is referenced, an array of user references is returned:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"assigned_to\\\": [\\n    {\\n      \\\"uid\\\": null,\\n      \\\"url\\\": null,\\n      \\\"email\\\": \\\"richard@subcontractor.com\\\"\\n    },\\n    {\\n      \\\"uid\\\": \\\"8510cfc9-2a82-4736-bf37-753c900d1c68\\\",\\n      \\\"url\\\": \\\"https://io.plangrid.com/projects/78128c72-5862-458a-9577-33eaa189a5c1/users/8510cfc9-2a82-4736-bf37-753c900d1c68\\\",\\n      \\\"email\\\": \\\"bob@subcontractor.com\\\"\\n    }\\n  ]\\n  ...\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"Easier than getting a work visa.","slug":"foreign-keys","type":"basic","title":"Foreign Keys","__v":0,"childrenPages":[]}

Foreign Keys

Easier than getting a work visa.

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

Reference to a Single Record

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"
  }
  ...
}
Attribute
Description

uid
string

Never blank.

url
string

The URL to retrieve the record's data. Never blank.

Reference to a Collection of Records

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"
  }
  ...
}
Attribute
Description

total_count
integer

Number of records in the collection. Never blank and greater than or equal to zero.

url
string

The URL to retrieve the collection of records. Blank if total_count is zero.

Reference to User(s)

References to users are a special case. On certain objects (issues, photos, attachments), 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.

{
  "created_by": {
    "uid": null,
    "url": null,
    "email": "richard@subcontractor.com"
  }
  ...
}
Attribute
Description

uid
string

May be blank.

url
string

The URL to retrieve the user record's data. May be blank.

email
string

User’s account email. May not be a valid email. Never blank.

When a collection of users is referenced, an array of user references is returned:

{
  "assigned_to": [
    {
      "uid": null,
      "url": null,
      "email": "richard@subcontractor.com"
    },
    {
      "uid": "8510cfc9-2a82-4736-bf37-753c900d1c68",
      "url": "https://io.plangrid.com/projects/78128c72-5862-458a-9577-33eaa189a5c1/users/8510cfc9-2a82-4736-bf37-753c900d1c68",
      "email": "bob@subcontractor.com"
    }
  ]
  ...
}
{"category":"58fe37462b628c0f0033a794","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7ae","next":{"pages":[],"description":""},"createdAt":"2015-09-03T00:28:30.618Z","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":12,"body":"Endpoints that return multiple records use offset based pagination which uses`?limit` and `?skip` query parameters. `?limit` indicates the maximum number of records to return, and `?skip` indicates the number of items to skip in the set of unpaginated records. If an endpoint returned 6 issues, setting `?skip` to 2 and `?limit` to 3 would retrieve the third, fourth, and fifth issue:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/X9uZVY8SSiSXe9g90tV8_image.png\",\n        \"image.png\",\n        \"975\",\n        \"451\",\n        \"#bbbbbb\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nThe default and maximum number for `?limit` is 50, but you can request less. The default `?skip` value starts from the beginning of unpaginated records and is 0.\n\nThe curl command below skips two records and returns a maximum of ten records:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://io.plangrid.com/projects?skip=2&limit=10 -u [[app:key]]: -H \\\"Accept: application/vnd.plangrid+json; version=1\\\"\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThe response to a request that returns multiple records is paginated and is always of the form:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"data\\\": [{}, {}, {}, {}, {}, {}, {}, {}, {}, {}],\\n  \\\"total_count\\\": 14,\\n  \\\"next_page_url\\\": \\\"https://io.plangrid.com/...?skip=12&limit=10\\\",\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n`data` is the array of records matched with `?skip` and `?limit`, `total_count` is the number of unpaginated records, and `next_page_url` is a url to the next page of records -- it will be `null` if you’ve reached the last page.\n\nIf `?limit` or `?skip` are not positive integers or 0, the PlanGrid API will return a 400 with an appropriate message.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Retrieving Records Created/Updated After a Specified Time\"\n}\n[/block]\nIf you're syncing PlanGrid with another system, you probably want to only retrieve records that have changed since your last sync. With the PlanGrid API you can achieve this with the `?updated_after` parameter. When added, the PlanGrid API only retrieves records created or updated after the specified UTC date and time (see [Timestamps and Timezones](doc:timestamps) for accepted date formats). It's supported on endpoints that have the potential to return large numbers of records (e.g. RFIs, issues, comments). For each endpoint you want to use the `?updated_after` parameter, check the endpoint's documentation to determine whether the parameter is supported.\n\nIt's important to note that the updated time of records with references (e.g. RFIs, issues) are updated when references change, but not when comments are added.","excerpt":"Bookmarks sold separately.","slug":"pagination","type":"basic","title":"Pagination","__v":0,"childrenPages":[]}

Pagination

Bookmarks sold separately.

Endpoints that return multiple records use offset based pagination which uses?limit and ?skip query parameters. ?limit indicates the maximum number of records to return, and ?skip indicates the number of items to skip in the set of unpaginated records. If an endpoint returned 6 issues, setting ?skip to 2 and ?limit to 3 would retrieve the third, fourth, and fifth issue:

The default and maximum number for ?limit is 50, but you can request less. The default ?skip value starts from the beginning of unpaginated records and is 0.

The curl command below skips two records and returns a maximum of ten records:

curl https://io.plangrid.com/projects?skip=2&limit=10 -u [[app:key]]: -H "Accept: application/vnd.plangrid+json; version=1"

The response to a request that returns multiple records is paginated and is always of the form:

{
  "data": [{}, {}, {}, {}, {}, {}, {}, {}, {}, {}],
  "total_count": 14,
  "next_page_url": "https://io.plangrid.com/...?skip=12&limit=10",
}

data is the array of records matched with ?skip and ?limit, total_count is the number of unpaginated records, and next_page_url is a url to the next page of records -- it will be null if you’ve reached the last page.

If ?limit or ?skip are not positive integers or 0, the PlanGrid API will return a 400 with an appropriate message.

Retrieving Records Created/Updated After a Specified Time

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.

{"category":"58fe37462b628c0f0033a794","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7af","next":{"pages":[],"description":""},"createdAt":"2015-09-03T00:21:02.109Z","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":13,"body":"PlanGrid API keys are attached to PlanGrid accounts. The API key has the same access privileges as the associated PlanGrid account: it can access all projects where the PlanGrid account is a team member and can perform actions allowed by the account’s project permissions. Access privileges for a PlanGrid account are described in detail in our [Help Center](https://help.plangrid.com/customer/portal/articles/1268049#understanding-permission-levels).\n\nTo use a PlanGrid API Key with all of your organization’s projects, add the PlanGrid account with the API key as a team member to each project. We strongly recommend establishing a policy that requires adding this PlanGrid account to every new project.\n\nIf you attempt an action outside your access privileges, the PlanGrid API will return a 403 with an appropriate message.","excerpt":"No access for you!","slug":"permissions","type":"basic","title":"Permissions","__v":0,"childrenPages":[]}

Permissions

No access for you!

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.

{"category":"58fe37462b628c0f0033a794","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7b0","next":{"pages":[],"description":""},"createdAt":"2015-09-03T00:50:00.634Z","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":14,"body":"To ensure quality of service, multiple rate limits are applied per API key that affect different time intervals (e.g. per second, per hour) and types of requests (e.g. reads, writes). You can determine the rate limit status of your API key by requesting [Retrieve Rate Limits](doc:retrieve-rate-limits). It returns a paginated list of [Rate Limit Objects](doc:the-rate-limit-object) that describe the different rate limits applied to your API key. Each [object](doc:the-rate-limit-object) contains information about the types of requests it applies to, the length of the interval, how many requests are remaining in the interval, and when the interval resets:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"data\\\": [\\n    {\\n      \\\"request_type\\\": \\\"all\\\",\\n      \\\"interval\\\": 1, \\n      \\\"limit\\\": 40,\\n      \\\"remaining\\\": 10,\\n      \\\"reset\\\": \\\"2013-05-17T02:30:22+00:00\\\"\\n    },\\n    {\\n      \\\"request_type\\\": \\\"all\\\",\\n      \\\"interval\\\": 86400, \\n      \\\"limit\\\": 10000,\\n      \\\"remaining\\\": 2398,\\n      \\\"reset\\\": \\\"2013-05-17T02:30:00+00:00\\\"\\n    },\\n    {\\n      \\\"request_type\\\": \\\"write\\\",\\n      \\\"interval\\\": 360, \\n      \\\"limit\\\": 2000,\\n      \\\"remaining\\\": 102,\\n      \\\"reset\\\": \\\"2013-05-17T04:30:22+00:00\\\"\\n    }    \\n  ],\\n  \\\"next_page_url\\\": null,\\n  \\\"total_count\\\": 3\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nCurrently, rate limits can be applied to the following types of requests:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Request type\",\n    \"h-1\": \"Applies to...\",\n    \"0-0\": \"`all`\",\n    \"1-0\": \"`write`\",\n    \"0-1\": \"All requests\",\n    \"1-1\": \"POST, PUT, PATCH, and DELETE requests\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]\nIf you're rate limited, the PlanGrid API returns a 429 with a JSON body that includes a [Rate Limit Object](doc:the-rate-limit-object) containing information about the rate limit that was hit:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"message\\\": \\\"API rate limit exceeded for developer cffe0ebb-2017-44d6-98d0-ddb0d48a3da8.\\\",\\n  \\\"rate_limit\\\": {\\n    \\\"request_type\\\": \\\"write\\\",\\n    \\\"interval\\\": 360, \\n    \\\"limit\\\": 2000,\\n    \\\"remaining\\\": 102,\\n    \\\"reset\\\": \\\"2013-05-17T04:30:22+00:00\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nYou can use the [Rate Limit Object](doc:the-rate-limit-object) to programmatically retry a rate limited request at the exact moment the rate limit resets. The example code below demonstrates this; it gets a list of all accessible projects and retries retrieval of a page of results if the request is rate limited:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import datetime\\nfrom time import sleep\\n\\nimport dateutil.parser\\nimport pytz\\nimport requests\\n\\napi_prefix = 'https://io.plangrid.com'\\napi_key = '[[app:key]]'\\nversion_headers = {'Accept': 'application/vnd.plangrid+json; version=1'}\\n\\ndef get_projects():\\n    # Get all of a user's projects from the API\\n    all_projects = []\\n    projects_url = '{}/projects'.format(api_prefix)\\n    while projects_url is not None:\\n        response = requests.get(projects_url, auth=(api_key, None), headers=version_headers)\\n\\n        if response.status_code == 200:\\n            # Save the projects that were successfully retrieved and go to the next page\\n            projects = response.json()['data']\\n            all_projects += projects\\n            projects_url = response.json()['next_page_url']\\n\\n        elif response.status_code == 429:\\n            # Sleep until the rate limit has expired, then retry the same request\\n            now = datetime.datetime.now(tz=pytz.utc)\\n            reset_iso_format = response.json()['rate_limit']['reset']\\n            reset = dateutil.parser.parse(reset_iso_format)\\n            seconds_to_sleep = (reset - now).total_seconds()\\n            sleep(seconds_to_sleep)\\n\\n    return all_projects\\n\\n# Example\\nprojects = get_projects()\\n\\nprint projects\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]\nIf you’re consistently rate limited, please [contact support](mailto:developers@plangrid.com) to see if your rate limits can be increased.","excerpt":"Happy responses come from happy servers.","slug":"rate-limiting","type":"basic","title":"Rate Limiting","__v":0,"childrenPages":[]}

Rate Limiting

Happy responses come from happy servers.

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:

Request type
Applies to...

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.

{"category":"58fe37462b628c0f0033a794","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7b1","next":{"pages":[],"description":""},"createdAt":"2016-09-22T07:02:52.834Z","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":15,"body":"Any timestamps contained in the JSON response are represented as strings in [ISO 8601](http://www.w3.org/TR/NOTE-datetime) format with timezone set to [UTC](https://en.wikipedia.org/wiki/Coordinated_Universal_Time):\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"YYYY-MM-DDThh:mm:SS+00:00\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nDates are of the form:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"YYYY-MM-DD\",\n      \"language\": \"text\"\n    }\n  ]\n}\n[/block]\nYou will need to perform timezone conversions in your client.","excerpt":"It's always tea-time.","slug":"timestamps-and-timezones","type":"basic","title":"Timestamps and Timezones","__v":0,"childrenPages":[]}

Timestamps and Timezones

It's always tea-time.

Any timestamps contained in the JSON response are represented as strings in ISO 8601 format with timezone set to UTC:

YYYY-MM-DDThh:mm:SS+00:00

Dates are of the form:

YYYY-MM-DD

You will need to perform timezone conversions in your client.

{"category":"58fe37462b628c0f0033a794","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7b2","next":{"pages":[],"description":""},"createdAt":"2015-11-06T04:05:12.386Z","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":16,"body":"Every record stored in PlanGrid is assigned a *universally*\\* unique identifier (`uid`) that will not change. UIDs are strings with four dashes between thirty-two alphanumeric characters: `“cce19790-2f7b-46fc-ade0-c932181c35d9”`. You can safely use the PlanGrid `uid` when mapping PlanGrid records with another system’s records.\n\n<sub>* The two exceptions are the [RFI status record](doc:the-rfi-status-object) and [permission role record](doc:the-role-object). For RFI status records, the unique identifiers are strings with 8 alphanumeric characters (`'4898bfd4'`). The unique identifiers for permission role records are strings with four dashes between thirty-two alphanumeric characters (`'17dce2c5-4931-47e7-8c98-84b35f00ba03'`) but are _not_ universally unique.</sub>","excerpt":"You're special.","slug":"unique-identifiers","type":"basic","title":"Unique Identifiers","__v":0,"childrenPages":[]}

Unique Identifiers

You're special.

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.

{"category":"58fe37462b628c0f0033a795","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7f6","next":{"pages":[],"description":""},"createdAt":"2015-12-21T01:31:10.928Z","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":17,"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. Attachment, Photo). Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n    \"4-1\": \"Once the file is uploaded, the URL to GET to complete creation of the record. Amazon S3 automatically redirects to this URL once the upload is complete.\",\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"1-0\": \"**aws_post_form_arguments**\\n`object`\",\n    \"1-1\": \"Necessary information to securely POST file to Amazon S3.\",\n    \"2-1\": \"The private URL to POST the file and security fields to.\",\n    \"2-0\": \"**aws_post_form_arguments.action**\\n`string`\",\n    \"3-0\": \"**aws_post_form_arguments.fields**\\n`array`\",\n    \"3-1\": \"An array of ordered key-value pairs for the POST form fields that authenticate you with Amazon S3.\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"  {\\n    \\\"uid\\\": \\\"022c132d-cdd0-48a1-8874-d4c9fd310ec8\\\",\\n    \\\"webhook_url\\\": \\\"https://io.plangrid.com/projects/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7/attachments/uploads/completions/8392cd3fbf2dfbf9fc539c8423a21201\\\",\\n    \\\"aws_post_form_arguments\\\": {\\n      \\\"action\\\": \\\"https://plangrid-attachments.s3.amazonaws.com/\\\",\\n      \\\"fields\\\": [\\n        {\\n          \\\"name\\\": \\\"key\\\",\\n          \\\"value\\\": \\\"4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\\\\/1ab29ace-adfe-4ff0-b4bd-267ca612df9a_ff\\\"\\n        },\\n        {\\n          \\\"name\\\": \\\"AWSAccessKeyId\\\",\\n          \\\"value\\\": \\\"AKIAIWKPH7OCNIEE5GGQ\\\"\\n        },\\n        {\\n          \\\"name\\\": \\\"success_action_redirect\\\",\\n          \\\"value\\\": \\\"https:\\\\/\\\\/plangrid-c-api-dispatcher-test.herokuapp.com\\\\/projects\\\\/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7\\\\/attachments\\\\/uploads\\\\/completions\\\\/1039b3921a93c7e74bdb3352779c2c6e\\\"\\n        },\\n        {\\n          \\\"name\\\": \\\"policy\\\",\\n          \\\"value\\\": \\\"eyJleHBpcmF0aW9uIjogIjIwMTUtMTItMjJUMjE6MTU6MTlaIiwKImNvbmRpdGlvbnMiOiBbeyJDb250ZW50LVR5cGUiOiAiYXBwbGljYXRpb24vcGRmIn0seyJidWNrZXQiOiAibG91cGUtdGVzdC1hdHRhY2gifSx7ImtleSI6ICI0ZDBmNGZmNi1iNGU3LWZiNDEtZWRiMi0xMzliMGZmZjllZjcvMWFiMjlhY2UtYWRmZS00ZmYwLWI0YmQtMjY3Y2E2MTJkZjlhX2ZmIn0seyJzdWNjZXNzX2FjdGlvbl9yZWRpcmVjdCI6ICJodHRwczovL3BsYW5ncmlkLWMtYXBpLWRpc3BhdGNoZXItdGVzdC5oZXJva3VhcHAuY29tL3YxL3Byb2plY3RzLzRkMGY0ZmY2LWI0ZTctZmI0MS1lZGIyLTEzOWIwZmZmOWVmNy9hdHRhY2htZW50cy91cGxvYWRzL2NvbXBsZXRpb25zLzEwMzliMzkyMWE5M2M3ZTc0YmRiMzM1Mjc3OWMyYzZlIn0seyJ4LWFtei1zdG9yYWdlLWNsYXNzIjogIlNUQU5EQVJEIn0seyJ4LWFtei1zZXJ2ZXItc2lkZS1lbmNyeXB0aW9uIjogIkFFUzI1NiJ9XX0=\\\"\\n        },\\n        {\\n          \\\"name\\\": \\\"signature\\\",\\n          \\\"value\\\": \\\"CztWq\\\\/9IU4hCaEiaw0P5IRYmh0g=\\\"\\n        },\\n        {\\n          \\\"name\\\": \\\"Content-Type\\\",\\n          \\\"value\\\": \\\"application\\\\/pdf\\\"\\n        },\\n        {\\n          \\\"name\\\": \\\"x-amz-storage-class\\\",\\n          \\\"value\\\": \\\"STANDARD\\\"\\n        },\\n        {\\n          \\\"name\\\": \\\"x-amz-server-side-encryption\\\",\\n          \\\"value\\\": \\\"AES256\\\"\\n        }\\n      ]\\n    }\\n  }\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-file-upload-object","type":"basic","title":"The File Upload Object","__v":0,"childrenPages":[]}

The File Upload Object


When uploading files via PlanGrid's API, this object is returned after the first step and contains information necessary for subsequent steps. See File Uploads for details.

Attribute
Description

uid
string

The unique identifier that will be assigned to the record associated with the file (e.g. Attachment, Photo). Never blank. See Unique Identifiers for details.

aws_post_form_arguments
object

Necessary information to securely POST file to Amazon S3.

aws_post_form_arguments.action
string

The private URL to POST the file and security fields to.

aws_post_form_arguments.fields
array

An array of ordered key-value pairs for the POST form fields that authenticate you with Amazon S3.

webhook_url
string

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"
        }
      ]
    }
  }
{"category":"58fe37462b628c0f0033a795","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":["57b32e995800cc0e00b3c035"],"_id":"58fe37472b628c0f0033a7f7","next":{"pages":[],"description":""},"createdAt":"2016-07-11T21:32:46.872Z","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":18,"body":"When generating a sheet packet, issue report, or any other shareable file, PlanGrid kicks off an asynchronous process to generate the file. To help you track when the file has been successfully generated, the PlanGrid API returns an object that gives you the current status and relevant URLs.\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"**uid**\\n`string`\",\n    \"0-1\": \"The unique identifier assigned to the shareable object. Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"1-0\": \"**file_url**\\n`string`\",\n    \"1-1\": \"URL to retrieve the shareable file.\",\n    \"3-0\": \"**status**\\n`string`\",\n    \"3-1\": \"Status of the shareable. Possible values are: \\\"incomplete\\\", \\\"complete\\\", \\\"errored\\\".\",\n    \"2-0\": \"**resource**\\n`object`\",\n    \"2-1\": \"Reference to itself (e.g. `this`, `self`). See [Foreign Keys](doc:foreign-keys) for attribute details.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"uid\\\": \\\"92cf7193-af0c-42fc-a3ab-7ef5149da720\\\",\\n  \\\"file_url\\\": \\\"https://packet-assets.plangrid.com/92cf7193-af0c-42fc-a3ab-7ef5149da720.pdf\\\",\\n  \\\"resource\\\": {\\n    \\\"uid\\\": \\\"92cf7193-af0c-42fc-a3ab-7ef5149da720\\\",\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/da48fcc3-7af1-4fd6-a083-70195468718a/sheets/packets/92cf7193-af0c-42fc-a3ab-7ef5149da720\\\"\\n  },\\n  \\\"status\\\": \\\"incomplete\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-shareable-object","type":"basic","title":"The Shareable Object","__v":0,"childrenPages":[]}

The Shareable Object


When generating a sheet packet, issue report, or any other shareable file, PlanGrid kicks off an asynchronous process to generate the file. To help you track when the file has been successfully generated, the PlanGrid API returns an object that gives you the current status and relevant URLs.

Attribute
Description

uid
string

The unique identifier assigned to the shareable object. Never blank. See Unique Identifiers for details.

file_url
string

URL to retrieve the shareable file.

resource
object

Reference to itself (e.g. this, self). See Foreign Keys for attribute details.

status
string

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"
}
{"category":"58fe37462b628c0f0033a796","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7e3","next":{"pages":[],"description":""},"createdAt":"2017-01-27T22:11:44.403Z","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":19,"body":"A batch request allows you to send multiple API requests at a single time. This can help you avoid rate limits for actions that need to be repeated multiple times. Examples of when you might want to use batch requests include: \n* adding multiple users at a time to a project\n* requesting issues from multiple projects\n* requesting records across multiple pages of an endpoint\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Formatting a batch request\"\n}\n[/block]\nTo make a batch request, you must provide an array of requests and `POST` it to the `/batch` endpoint. Each request inside the batch request contains its own `method` and `path`, as well as a JSON-encoded `body` if required. Each request in the batch uses the same `Authorization`, `Content-Type` and `Accept` headers from the batch request but can be overwritten within the headers of that request.\n\nThe example below shows a batched request to retrieve a specific project with UID `43b198bb-d4f9-c302-9173-271050e424b7` and also create a new project named `test_create`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[\\n  {\\n    \\\"method\\\": \\\"GET\\\",\\n    \\\"path\\\": \\\"/projects/43b198bb-d4f9-c302-9173-271050e424b7\\\" \\n  },\\n  {\\n    \\\"method\\\": \\\"POST\\\",\\n    \\\"path\\\": \\\"/projects\\\",\\n    \\\"headers\\\": [\\n      {\\n        \\\"name\\\": \\\"Content-Type\\\",\\n        \\\"value\\\": \\\"application/json\\\"\\n      }\\n    ],\\n    \\\"body\\\": \\\"{\\\\\\\"name\\\\\\\": \\\\\\\"test_create\\\\\\\"}\\\"\\n  },\\n  {\\n    \\\"method\\\": \\\"POST\\\",\\n    \\\"path\\\": \\\"/projects\\\",\\n    \\\"headers\\\": [\\n      {\\n        \\\"name\\\": \\\"Content-Type\\\",\\n        \\\"value\\\": \\\"application/json\\\"\\n      }\\n    ],\\n    \\\"body\\\": \\\"{}\\\"\\n  }\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Response from a batch request\"\n}\n[/block]\nOnce a batch request is successfully completed, you will receive a single response that contains the results for all requests (in the same order as the original request). Each response contains its own `status_code` and a JSON-encoded `body`. For instance, the example above yields the following response that includes both `200` and `400` responses.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"data\\\": [\\n    {\\n      \\\"status_code\\\": 200,\\n      \\\"headers\\\": [\\n        {\\n          \\\"name\\\": \\\"connection\\\",\\n          \\\"value\\\": \\\"close\\\",\\n        },\\n        {\\n          \\\"name\\\": \\\"content-type\\\",\\n          \\\"value\\\": \\\"application/json\\\"\\n        }\\n      ],\\n      \\\"body\\\": \\\"{\\\\\\\"uid\\\\\\\": \\\\\\\"43b198bb-d4f9-c302-9173-271050e424b7\\\\\\\", \\\\\\\"name\\\\\\\": \\\\\\\"1000 Issues\\\\\\\"}\\\"\\n    },\\n    {\\n      \\\"status_code\\\": 200,\\n      \\\"headers\\\": [\\n        {\\n          \\\"name\\\": \\\"connection\\\",\\n          \\\"value\\\": \\\"close\\\",\\n        },\\n        {\\n          \\\"name\\\": \\\"content-type\\\",\\n          \\\"value\\\": \\\"application/json\\\"\\n        }\\n      ],\\n      \\\"body\\\": \\\"{\\\\\\\"uid\\\\\\\": \\\\\\\"880597f4-c15b-4b95-8c32-0cdefdc1a091\\\\\\\", \\\\\\\"name\\\\\\\": \\\\\\\"test_create\\\\\\\"}\\\"\\n    },\\n    {\\n      \\\"status_code\\\": 400,\\n      \\\"headers\\\": [\\n        {\\n          \\\"name\\\": \\\"connection\\\",\\n          \\\"value\\\": \\\"close\\\",\\n        },\\n        {\\n          \\\"name\\\": \\\"content-type\\\",\\n          \\\"value\\\": \\\"application/json\\\"\\n        }\\n      ],\\n      \\\"body\\\": \\\"{\\\\\\\"message\\\\\\\": \\\\\\\"Fields must be in JSON body.\\\\\\\"}\\\"\\n    }\\n]\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\nPlease note that if you provide a malformed array, an array with too many requests, or an array with no requests, you will receive a `400` response for the batch request instead of a response like the one above. See the various errors in the [Send Batch Request](doc:send-batch-request) example.","excerpt":"","slug":"why-batch-requests","type":"basic","title":"Why Batch Requests?","__v":0,"childrenPages":[]}

Why Batch Requests?


A batch request allows you to send multiple API requests at a single time. This can help you avoid rate limits for actions that need to be repeated multiple times. Examples of when you might want to use batch requests include:

  • adding multiple users at a time to a project
  • requesting issues from multiple projects
  • requesting records across multiple pages of an endpoint

Formatting a batch request

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": "{}"
  }
]

Response from a batch request

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.

{"category":"58fe37462b628c0f0033a796","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7e4","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,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":20,"body":"[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"**status_code**\\n`integer`\",\n    \"1-0\": \"**headers**\\n`array`\",\n    \"4-0\": \"**body**\\n`string`\",\n    \"0-1\": \"The HTTP status code for this response.\",\n    \"1-1\": \"The headers for this response.\",\n    \"4-1\": \"The JSON-encoded body for this response.\",\n    \"2-0\": \"**headers.name**\\n`string`\",\n    \"2-1\": \"The name of the header.\",\n    \"3-0\": \"**headers.value**\\n`string`\",\n    \"3-1\": \"The value of the header.\",\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"status_code\\\": 200,\\n  \\\"headers\\\": [\\n    {\\n      \\\"name\\\": \\\"connection\\\",\\n      \\\"value\\\": \\\"close\\\",\\n    },\\n    {\\n      \\\"name\\\": \\\"content-type\\\",\\n      \\\"value\\\": \\\"application/json\\\"\\n    }\\n  ],\\n  \\\"body\\\": \\\"{\\\\\\\"uid\\\\\\\": \\\\\\\"43b198bb-d4f9-c302-9173-271050e424b7\\\\\\\", \\\\\\\"name\\\\\\\": \\\\\\\"1000 Issues\\\\\\\"}\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-batch-request-object","type":"basic","title":"The Batch Request Object","__v":0,"childrenPages":[]}

The Batch Request Object


Attribute
Description

status_code
integer

The HTTP status code for this response.

headers
array

The headers for this response.

headers.name
string

The name of the header.

headers.value
string

The value of the header.

body
string

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\"}"
}
{"category":"58fe37462b628c0f0033a796","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7e5","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":[{"name":"","code":"{\n  \"data\": [\n    {\n      \"status_code\": 200,\n      \"headers\": [\n        {\n          \"name\": \"connection\",\n          \"value\": \"close\",\n        },\n        {\n          \"name\": \"content-type\",\n          \"value\": \"application/json\"\n        }\n      ],\n      \"body\": \"{\\\"uid\\\": \\\"43b198bb-d4f9-c302-9173-271050e424b7\\\", \\\"name\\\": \\\"1000 Issues\\\"}\"\n    },\n    {\n      \"status_code\": 400,\n      \"headers\": [\n        {\n          \"name\": \"connection\",\n          \"value\": \"close\",\n        },\n        {\n          \"name\": \"content-type\",\n          \"value\": \"application/json\"\n        }\n      ],\n      \"body\": \"{\\\"message\\\": \\\"Request body must be a JSON encoded string.\\\"}\"\n    },\n    {\n      \"status_code\": 400,\n      \"headers\": [\n        {\n          \"name\": \"connection\",\n          \"value\": \"close\",\n        },\n        {\n          \"name\": \"content-type\",\n          \"value\": \"application/json\"\n        }\n      ],\n      \"body\": \"{\\\"message\\\": \\\"Request must contain at least one field.\\\"}\"\n    },\n    {\n      \"status_code\": 400,\n      \"headers\": [\n        {\n          \"name\": \"connection\",\n          \"value\": \"close\",\n        },\n        {\n          \"name\": \"content-type\",\n          \"value\": \"application/json\"\n        }\n      ],\n      \"body\": \"{\\\"message\\\": \\\"Unsupported fields are not allowed in request.\\\"}\"\n    },\n    {\n      \"status_code\": 400,\n      \"headers\": [\n        {\n          \"name\": \"connection\",\n          \"value\": \"close\",\n        },\n        {\n          \"name\": \"content-type\",\n          \"value\": \"application/json\"\n        }\n      ],\n      \"body\": \"{\\\"message\\\": \\\"Method required to send batch request.\\\"}\"\n    },\n    {\n      \"status_code\": 400,\n      \"headers\": [\n        {\n          \"name\": \"connection\",\n          \"value\": \"close\",\n        },\n        {\n          \"name\": \"content-type\",\n          \"value\": \"application/json\"\n        }\n      ],\n      \"body\": \"{\\\"message\\\": \\\"Path required to send batch request.\\\"}\"\n    },\n    {\n      \"status_code\": 400,\n      \"headers\": [\n        {\n          \"name\": \"connection\",\n          \"value\": \"close\",\n        },\n        {\n          \"name\": \"content-type\",\n          \"value\": \"application/json\"\n        }\n      ],\n      \"body\": \"{\\\"message\\\": \\\"Path must begin with a '/'.\\\"}\"\n    },\n    {\n      \"status_code\": 400,\n      \"headers\": [\n        {\n          \"name\": \"connection\",\n          \"value\": \"close\",\n        },\n        {\n          \"name\": \"content-type\",\n          \"value\": \"application/json\"\n        }\n      ],\n      \"body\": \"{\\\"message\\\": \\\"Headers must be an array of objects with 'name' and 'value'.\\\"}\"\n    },\n    {\n      \"status_code\": 400,\n      \"headers\": [\n        {\n          \"name\": \"connection\",\n          \"value\": \"close\",\n        },\n        {\n          \"name\": \"content-type\",\n          \"value\": \"application/json\"\n        }\n      ],\n      \"body\": \"{\\\"message\\\": \\\"Unsupported fields are not allowed in headers.\\\"}\"\n    },\n    {\n      \"status_code\": 500,\n      \"headers\": [\n        {\n          \"name\": \"connection\",\n          \"value\": \"close\",\n        },\n        {\n          \"name\": \"content-type\",\n          \"value\": \"application/json\"\n        }\n      ],\n      \"body\": \"{\\\"message\\\": \\\"Sorry, PlanGrid's system had an error and the team has been notified. If this happens again, please contact support@plangrid.com.\\\"}\"\n    }\n  ]\n}","language":"json","status":200},{"name":"No Requests","code":"{ \"message\": \"There must be at least one batch request.\" }","language":"json","status":400},{"code":"{ \"message\": \"The number of batch requests (:number_of_requests) must be less than or equal to 50.\" }","language":"json","status":400,"name":"Too Many Requests"},{"code":"{ \"message\": \"JSON body must be an array.\" }","language":"json","status":400,"name":"Not An Array"}]},"settings":"588bb90f33b1b337002e64e7","auth":"required","params":[],"url":"/batch"},"isReference":false,"order":21,"body":"The following example shows how to retrieve your projects and rate limits in one request.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -i https://io.plangrid.com/batch -u [[app:key]]: -H \\\"Content-Type: application/json\\\" -H 'Accept: application/vnd.plangrid+json; version=1' -d '[{\\\"method\\\": \\\"GET\\\", \\\"path\\\": \\\"/projects\\\"}, {\\\"method\\\": \\\"GET\\\", \\\"path\\\": \\\"/rate_limits\\\"}]' -v\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThe following example shows how to retrieve project data from multiple endpoints.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import requests\\n\\napi_prefix = 'https://io.plangrid.com'\\napi_key = '[[app:key]]'\\nversion_headers = {'Accept': 'application/vnd.plangrid+json; version=1'}\\n\\ndef get_first_project_uid():\\n    # Get the UID of the first project returned from the API\\n    projects_url = '{}/projects'.format(api_prefix)\\n    response = requests.get(projects_url, auth=(api_key, None), headers=version_headers)\\n    projects = response.json()['data']\\n    first_project_uid = projects[0]['uid']\\n    return first_project_uid\\n\\ndef get_project_data(project_uid):\\n    project_paths = [\\n        \\\"/projects/{}\\\".format(project_uid),\\n        \\\"/projects/{}/attachments\\\".format(project_uid),\\n        \\\"/projects/{}/comments\\\".format(project_uid),\\n        \\\"/projects/{}/issues\\\".format(project_uid),\\n        \\\"/projects/{}/photos\\\".format(project_uid),\\n        \\\"/projects/{}/rfis\\\".format(project_uid),\\n        \\\"/projects/{}/roles\\\".format(project_uid),\\n        \\\"/projects/{}/sheets\\\".format(project_uid),\\n        \\\"/projects/{}/snapshots\\\".format(project_uid),\\n        \\\"/projects/{}/users\\\".format(project_uid)\\n    ]\\n\\n    batch_requests = []\\n    for path in project_paths:\\n        batch_requests.append({\\n            \\\"method\\\": \\\"GET\\\",\\n            \\\"path\\\": path\\n        })\\n\\n    batch_url = '{}/batch'.format(api_prefix)\\n    response = requests.post(url=batch_url, auth=(api_key, None), headers=version_headers, json=batch_requests)\\n\\n    json_response = response.json()['data']\\n\\n    return json_response\\n\\n# Get a project_uid for the batch\\nproject_uid = get_first_project_uid()\\n\\n# Perform a batch request\\nproject_data = get_project_data(project_uid=project_uid)\\n\\nprint project_data\",\n      \"language\": \"python\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"send-batch-request","type":"post","title":"Send Batch Request","__v":0,"childrenPages":[]}

postSend Batch Request


The following example shows how to retrieve your projects and rate limits in one request.

curl -i https://io.plangrid.com/batch -u [[app:key]]: -H "Content-Type: application/json" -H 'Accept: application/vnd.plangrid+json; version=1' -d '[{"method": "GET", "path": "/projects"}, {"method": "GET", "path": "/rate_limits"}]' -v

The following example shows how to retrieve project data from multiple endpoints.

import requests

api_prefix = 'https://io.plangrid.com'
api_key = '[[app:key]]'
version_headers = {'Accept': 'application/vnd.plangrid+json; version=1'}

def get_first_project_uid():
    # Get the UID of the first project returned from the API
    projects_url = '{}/projects'.format(api_prefix)
    response = requests.get(projects_url, auth=(api_key, None), headers=version_headers)
    projects = response.json()['data']
    first_project_uid = projects[0]['uid']
    return first_project_uid

def get_project_data(project_uid):
    project_paths = [
        "/projects/{}".format(project_uid),
        "/projects/{}/attachments".format(project_uid),
        "/projects/{}/comments".format(project_uid),
        "/projects/{}/issues".format(project_uid),
        "/projects/{}/photos".format(project_uid),
        "/projects/{}/rfis".format(project_uid),
        "/projects/{}/roles".format(project_uid),
        "/projects/{}/sheets".format(project_uid),
        "/projects/{}/snapshots".format(project_uid),
        "/projects/{}/users".format(project_uid)
    ]

    batch_requests = []
    for path in project_paths:
        batch_requests.append({
            "method": "GET",
            "path": path
        })

    batch_url = '{}/batch'.format(api_prefix)
    response = requests.post(url=batch_url, auth=(api_key, None), headers=version_headers, json=batch_requests)

    json_response = response.json()['data']

    return json_response

# Get a project_uid for the batch
project_uid = get_first_project_uid()

# Perform a batch request
project_data = get_project_data(project_uid=project_uid)

print project_data

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "status_code": 200,
      "headers": [
        {
          "name": "connection",
          "value": "close",
        },
        {
          "name": "content-type",
          "value": "application/json"
        }
      ],
      "body": "{\"uid\": \"43b198bb-d4f9-c302-9173-271050e424b7\", \"name\": \"1000 Issues\"}"
    },
    {
      "status_code": 400,
      "headers": [
        {
          "name": "connection",
          "value": "close",
        },
        {
          "name": "content-type",
          "value": "application/json"
        }
      ],
      "body": "{\"message\": \"Request body must be a JSON encoded string.\"}"
    },
    {
      "status_code": 400,
      "headers": [
        {
          "name": "connection",
          "value": "close",
        },
        {
          "name": "content-type",
          "value": "application/json"
        }
      ],
      "body": "{\"message\": \"Request must contain at least one field.\"}"
    },
    {
      "status_code": 400,
      "headers": [
        {
          "name": "connection",
          "value": "close",
        },
        {
          "name": "content-type",
          "value": "application/json"
        }
      ],
      "body": "{\"message\": \"Unsupported fields are not allowed in request.\"}"
    },
    {
      "status_code": 400,
      "headers": [
        {
          "name": "connection",
          "value": "close",
        },
        {
          "name": "content-type",
          "value": "application/json"
        }
      ],
      "body": "{\"message\": \"Method required to send batch request.\"}"
    },
    {
      "status_code": 400,
      "headers": [
        {
          "name": "connection",
          "value": "close",
        },
        {
          "name": "content-type",
          "value": "application/json"
        }
      ],
      "body": "{\"message\": \"Path required to send batch request.\"}"
    },
    {
      "status_code": 400,
      "headers": [
        {
          "name": "connection",
          "value": "close",
        },
        {
          "name": "content-type",
          "value": "application/json"
        }
      ],
      "body": "{\"message\": \"Path must begin with a '/'.\"}"
    },
    {
      "status_code": 400,
      "headers": [
        {
          "name": "connection",
          "value": "close",
        },
        {
          "name": "content-type",
          "value": "application/json"
        }
      ],
      "body": "{\"message\": \"Headers must be an array of objects with 'name' and 'value'.\"}"
    },
    {
      "status_code": 400,
      "headers": [
        {
          "name": "connection",
          "value": "close",
        },
        {
          "name": "content-type",
          "value": "application/json"
        }
      ],
      "body": "{\"message\": \"Unsupported fields are not allowed in headers.\"}"
    },
    {
      "status_code": 500,
      "headers": [
        {
          "name": "connection",
          "value": "close",
        },
        {
          "name": "content-type",
          "value": "application/json"
        }
      ],
      "body": "{\"message\": \"Sorry, PlanGrid's system had an error and the team has been notified. If this happens again, please contact support@plangrid.com.\"}"
    }
  ]
}
{ "message": "There must be at least one batch request." }
{ "message": "The number of batch requests (:number_of_requests) must be less than or equal to 50." }
{ "message": "JSON body must be an array." }


{"__v":1,"_id":"58fe37472b628c0f0033a7f3","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"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\nThe following steps outline how your application can use OAuth 2.0 to obtain a PlanGrid user's authorization to perform API requests. \n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Before you begin\",\n  \"body\": \"You must register your application before you can start using OAuth with our API. If you are a developer looking to use OAuth, please [contact us](mailto:developers@plangrid.com) to register your application. You will need to provide the following information: application name, logo, and a list of redirect URIs.\"\n}\n[/block]\n\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 using a `GET` request with the 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    \"1-0\": \"**response_type**\\n`string`\\n*Required*\",\n    \"3-0\": \"**scope**\\n`string`\",\n    \"4-0\": \"**redirect_uri**\\n`string`\",\n    \"1-1\": \"Specify what grant type the endpoint returns. Currently the only type `code` is supported.\",\n    \"3-1\": \"Specify a group of resources an application can request access to. Currently the only supported value is `write:projects`, which provides access to all `/projects` endpoints.\",\n    \"2-0\": \"**state**\\n`string`\\n*Required*\",\n    \"2-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    \"4-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\": 5\n}\n[/block]\nAn example `GET` 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\",\n      \"language\": \"http\"\n    }\n  ]\n}\n[/block]\n\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 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*Required*\",\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    \"4-0\": \"**redirect_uri**\\n`string`\",\n    \"2-1\": \"Can be `authorization_code` or `refresh_token`.\",\n    \"3-1\": \"Depending on `grant_type`, can either be the authorization code or a refresh token value\",\n    \"4-1\": \"If a `redirect_uri` was provided when requesting user authorization, this must match that value.\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\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 `code` parameter. If successful, you will receive a new `access_token`.","category":"58fe37462b628c0f0033a797","createdAt":"2017-02-16T21:15:07.278Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","next":{"pages":[],"description":""},"order":22,"parentDoc":null,"project":"55d2023b3c74062300aee506","slug":"getting-started-with-oauth","sync_unique":"","title":"Getting Started with OAuth","type":"basic","updates":["5929fc5db1061c1900f8f0b4"],"user":"57db49de0678030e008a76f8","version":"58fe37462b628c0f0033a792","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.

The following steps outline how your application can use OAuth 2.0 to obtain a PlanGrid user's authorization to perform API requests.

Before you begin

You must register your application before you can start using OAuth with our API. If you are a developer looking to use OAuth, please contact us to register your application. You will need to provide the following information: application name, logo, and a list of redirect URIs.

1. Request user authorization

Direct your users to the /oauth/authorize endpoint using a GET request with the following parameters:

Name
Description

client_id
string
Required

A unique identifier for your application provided by PlanGrid.

response_type
string
Required

Specify what grant type the endpoint returns. Currently the only type code is supported.

state
string
Required

An arbitrary string that will be included in the response. This can be used to confirm that the request originated from your application.

scope
string

Specify a group of resources an application can request access to. Currently the only supported value is write:projects, which provides access to all /projects endpoints.

redirect_uri
string

Specify a URL where the response will be redirected. Must match a value in the whitelist for this client.

An example GET request would look like the following:

https://io.plangrid.com/oauth/authorize?response_type=code&client_id=MY_CLIENT_ID&state=SECURITY_TOKEN

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.

2. User authorizes application

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

3. Request access 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.

Name
Description

client_id
string
Required

A unique identifier for your application provided by PlanGrid.

client_secret
string
Required

A unique string for your application provided by PlanGrid.

grant_type
string
Required

Can be authorization_code or refresh_token.

code
string
Required

Depending on grant_type, can either be the authorization code or a refresh token value

redirect_uri
string

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
}

4. Using access token

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]]"

5. Refreshing accessing tokens

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 code parameter. If successful, you will receive a new access_token.

{"category":"58fe37462b628c0f0033a797","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"57db49de0678030e008a76f8","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7f4","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":[{"language":"text","code":""}]},"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. Currently the only type `code` is supported.","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. Currently the only supported value is `write:projects`, which provides access to all `/projects` endpoints.","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":23,"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 required parameter is missing or any parameters are repeated, the user-agent will be redirected to the `redirect_uri` with the query parameter `error=invalid_request`.\\n\\nIf a `response_type` other than `code` is used,  the user-agent will be redirected to the `redirect_uri` with the query parameter `error=unsupported_response_type`.\\n\\nIf a `scope` other than `write:projects` is used, the user-agent will be redirected to the `redirect_uri` with the query parameter `error = invalid_scope`.\\n\\nIf an uncaught exception occurs on the approval page, the user-agent will be redirected to the `redirect_uri` with the query parameter `error = server_error`.\",\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 code will be provided that will be used to generate an access code.","slug":"retrieve-authorization-code","type":"get","title":"Retrieve Authorization Code","__v":0,"childrenPages":[]}

getRetrieve Authorization Code

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 code will be provided that will be used to generate an access code.

Query Params

client_id:
required
string
A unique identifier for your application provided by PlanGrid.
response_type:
required
string
Specify what grant type the endpoint returns. Currently the only type `code` is supported.
state:
required
string
An arbitrary string that will be included in the response. This can be used to confirm that the request originated from your application.
scope:
string
Specify a group of resources an application can request access to. Currently the only supported value is `write:projects`, which provides access to all `/projects` endpoints.
redirect_uri:
string
Specify a URL where the response will be redirected. Must match a value in the whitelist for this client.

Definition

{{ api_url }}{{ page_api_url }}


Errors

If any required parameter is missing or any parameters are repeated, the user-agent will be redirected to the redirect_uri with the query parameter error=invalid_request.

If a response_type other than code is used, the user-agent will be redirected to the redirect_uri with the query parameter error=unsupported_response_type.

If a scope other than write:projects is used, the user-agent will be redirected to the redirect_uri with the query parameter error = invalid_scope.

If an uncaught exception occurs on the approval page, the user-agent will be redirected to the redirect_uri with the query parameter error = server_error.

{"__v":0,"_id":"58fe37472b628c0f0033a7f5","api":{"auth":"required","examples":{"codes":[]},"method":"post","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"}],"results":{"codes":[{"name":"","code":"{\n  \"refresh_token\": \"a95b3fadb31941fe9b0a74cb71b721d\",\n  \"access_token\": \"oauth_8107f78b473e46dab2406cd4db3bb366\",\n  \"token_type\": \"Bearer\",\n  \"expires_in\":  604800,\n  \"scope\": \"write:projects\"\n}","language":"json","status":200}]},"settings":"58a619d52cb5710f0070d0de","url":"/oauth/token"},"body":"","category":"58fe37462b628c0f0033a797","createdAt":"2017-02-17T15:43:19.404Z","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.","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","next":{"pages":[],"description":""},"order":24,"parentDoc":null,"project":"55d2023b3c74062300aee506","slug":"retrieve-access-token","sync_unique":"","title":"Retrieve Access Token","type":"post","updates":[],"user":"57db49de0678030e008a76f8","version":"58fe37462b628c0f0033a792","childrenPages":[]}

postRetrieve Access Token

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.

Query Params

client_id:
required
string
A unique identifier for your application provided by PlanGrid.
client_secret:
required
string
A unique string for your application provided by PlanGrid.
grant_type:
required
string
Type of request. Can be either `authorization_code` or `refresh_token`.
code:
string
Required if `grant_type` is set to `authorization_code`. Must be the authorization code acquired from the `/oauth/authorize` endpoint.
refresh_token:
string
Required if `grant_type` is set to `refresh_token`. Must be the `refresh_token` provided with access token.
redirect_uri:
string
If a `redirect_uri` was provided when requesting user authorization, this must match that value.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "refresh_token": "a95b3fadb31941fe9b0a74cb71b721d",
  "access_token": "oauth_8107f78b473e46dab2406cd4db3bb366",
  "token_type": "Bearer",
  "expires_in":  604800,
  "scope": "write:projects"
}


{"category":"58fe37462b628c0f0033a798","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7cc","next":{"pages":[],"description":""},"createdAt":"2015-09-23T23:56:21.103Z","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":25,"body":"[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"**uid**\\n`string`\",\n    \"0-1\": \"Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n    \"1-0\": \"**name**\\n`string`\",\n    \"1-1\": \"Project name.\",\n    \"2-0\": \"**custom_id**\\n`string`\",\n    \"2-1\": \"Project code.\",\n    \"3-0\": \"**type**\\n`string`\",\n    \"3-1\": \"Project type with possible values of `general`, `manufacturing`, `power`, `water-sewer-waste`, `industrial-petroleum`, `transportation`, `hazardous-waste`, `telecom`, `education-k-12`, `education-higher`, `gov-federal`, `gov-state-local`, or `other`.\",\n    \"4-0\": \"**status**\\n`string`\",\n    \"4-1\": \"Project status.\",\n    \"5-0\": \"**owner**\\n`string`\",\n    \"5-1\": \"Project owner.\",\n    \"6-0\": \"**start_date**\\n`string`\",\n    \"6-1\": \"Project start date. ISO-8601 date format (YYYY-MM-DD).\",\n    \"7-0\": \"**end_date**\\n`string`\",\n    \"7-1\": \"Project end date. ISO-8601 date format (YYYY-MM-DD).\",\n    \"8-0\": \"**street_1**\\n`string`\",\n    \"8-1\": \"Project address, street line 1.\",\n    \"9-0\": \"**street_2**\\n`string`\",\n    \"9-1\": \"Project address, street line 2.\",\n    \"10-0\": \"**city**\\n`string`\",\n    \"10-1\": \"Project address town or city.\",\n    \"11-0\": \"**region**\\n`string`\",\n    \"11-1\": \"Project address state, province, or region.\",\n    \"12-0\": \"**postal_code**\\n`string`\",\n    \"12-1\": \"Project address zip or postal code.\",\n    \"13-0\": \"**country**\\n`string`\",\n    \"13-1\": \"Project address country in 2-letter ISO 3166 code.\"\n  },\n  \"cols\": 2,\n  \"rows\": 14\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"uid\\\": \\\"8510cfc9-2a82-4736-bf37-753c900d1c68\\\",\\n  \\\"name\\\": \\\"LA Natural History Museum\\\",\\n  \\\"custom_id\\\": \\\"5678\\\",\\n  \\\"type\\\": \\\"general\\\",\\n  \\\"status\\\": \\\"completed\\\",\\n  \\\"owner\\\": \\\"ACME\\\",\\n  \\\"start_date\\\": \\\"2001-10-01\\\",\\n  \\\"end_date\\\": \\\"2050-10-01\\\",\\n  \\\"street_1\\\": \\\"900 Exposition Blvd\\\",\\n  \\\"street_2\\\": null,\\n  \\\"city\\\": \\\"Los Angeles\\\",\\n  \\\"region\\\": \\\"California\\\",\\n  \\\"postal_code\\\": \\\"90007\\\",\\n  \\\"country\\\": \\\"US\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-project-object","type":"basic","title":"The Project Object","__v":0,"childrenPages":[]}

The Project Object


Attribute
Description

uid
string

Never blank. See Unique Identifiers for details.

name
string

Project name.

custom_id
string

Project code.

type
string

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.

status
string

Project status.

owner
string

Project owner.

start_date
string

Project start date. ISO-8601 date format (YYYY-MM-DD).

end_date
string

Project end date. ISO-8601 date format (YYYY-MM-DD).

street_1
string

Project address, street line 1.

street_2
string

Project address, street line 2.

city
string

Project address town or city.

region
string

Project address state, province, or region.

postal_code
string

Project address zip or postal code.

country
string

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"
}
{"category":"58fe37462b628c0f0033a798","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7cd","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":[{"language":"json","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","name":"Success","status":201},{"language":"json","code":"{\n  \"message\": \"Project name required to create a project.\"\n}\n","name":"Name Missing","status":400},{"language":"json","code":"{\n  \"message\": \"Project name must be at least one character long.\"\n}\n","name":"Name Blank","status":400},{"code":"{\n  \"message\": \"Custom ID must be null or a string at least one character long.\"\n}","language":"json","status":400,"name":"Invalid Custom ID"},{"code":"{\n  \"message\": \"Type (2) must be a valid project type.\"\n}","language":"json","status":400,"name":"Invalid Type"},{"code":"{\n  \"message\": \"Status must be null or a string at least one character long.\"\n}","language":"json","status":400,"name":"Invalid Status"},{"code":"{\n  \"message\": \"Owner must be null or a string at least one character long.\"\n}","language":"json","status":400,"name":"Invalid Owner"},{"code":"{\n  \"message\": \"Start date (1234) must be null or a date string in ISO-8601 format (YYYY-MM-DD).\"\n}","language":"json","status":400,"name":"Invalid Start Date"},{"code":"{\n  \"message\": \"End date (1234) must be null or a date string in ISO-8601 format (YYYY-MM-DD).\"\n}","language":"json","status":400,"name":"Invalid End Date"},{"code":"{\n  \"message\": \"Street 1 must be null or a string at least one character long.\"\n}","language":"json","status":400,"name":"Invalid Street 1"},{"code":"{\n  \"message\": \"Street 2 must be null or a string at least one character long.\"\n}","language":"json","status":400,"name":"Invalid Street 2"},{"code":"{\n  \"message\": \"City must be null or a string at least one character long.\"\n}","language":"json","status":400,"name":"Invalid City"},{"code":"{\n  \"message\": \"Postal code must be null or a string at least one character long.\"\n}","language":"json","status":400,"name":"Invalid Region"},{"name":"Invalid Country","status":400,"language":"json","code":"{\n  \"message\": \"Country must be an ISO 3166 two letter country code.\"\n}"}]},"settings":"","auth":"required","params":[{"_id":"56cf1ed65267d70b00494c04","ref":"","in":"body","required":true,"desc":"Name of the project. Must be at least one character long.","default":"","type":"string","name":"name"},{"_id":"58ee7efdb4f0dd390087363f","ref":"","in":"body","required":false,"desc":"Project code.","default":"null","type":"string","name":"custom_id"},{"_id":"58ee7efdb4f0dd390087363e","ref":"","in":"body","required":false,"desc":"Project type with possible values of `general`, `manufacturing`, `power`, `water-sewer-waste`, `industrial-petroleum`, `transportation`, `hazardous-waste`, `telecom`, `education-k-12`, `education-higher`, `gov-federal`, `gov-state-local`, or `other`.","default":"null","type":"string","name":"type"},{"_id":"58ee7efdb4f0dd390087363d","ref":"","in":"body","required":false,"desc":"Project status.","default":"null","type":"string","name":"status"},{"_id":"58ee7efdb4f0dd390087363c","ref":"","in":"body","required":false,"desc":"Project owner.","default":"null","type":"string","name":"owner"},{"_id":"58ee7efdb4f0dd390087363b","ref":"","in":"body","required":false,"desc":"Project start date. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"null","type":"string","name":"start_date"},{"_id":"58ee7efdb4f0dd390087363a","ref":"","in":"body","required":false,"desc":"Project end date. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"null","type":"string","name":"end_date"},{"_id":"58ee7efdb4f0dd3900873639","ref":"","in":"body","required":false,"desc":"Project address, street line 1.","default":"null","type":"string","name":"street_1"},{"_id":"58ee7efdb4f0dd3900873638","ref":"","in":"body","required":false,"desc":"Project address, street line 2.","default":"null","type":"string","name":"street_2"},{"_id":"58ee7efdb4f0dd3900873637","ref":"","in":"body","required":false,"desc":"Project address town or city.","default":"null","type":"string","name":"city"},{"_id":"58ee7efdb4f0dd3900873636","ref":"","in":"body","required":false,"desc":"Project address state, province, or region.","default":"null","type":"string","name":"region"},{"_id":"58ee7efdb4f0dd3900873635","ref":"","in":"body","required":false,"desc":"Project address zip or postal code.","default":"null","type":"string","name":"postal_code"},{"_id":"58ee7efdb4f0dd3900873634","ref":"","in":"body","required":false,"desc":"Project address country in 2-letter ISO 3166 code.","default":"null","type":"string","name":"country"}],"url":"/projects"},"isReference":false,"order":26,"body":"","excerpt":"Create a new PlanGrid project. The PlanGrid account associated with the API key is added as an admin to the project team.","slug":"create-project","type":"post","title":"Create Project","__v":0,"childrenPages":[]}

postCreate Project

Create a new PlanGrid project. The PlanGrid account associated with the API key is added as an admin to the project team.

Body Params

name:
required
string
Name of the project. Must be at least one character long.
custom_id:
stringnull
Project code.
type:
stringnull
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`.
status:
stringnull
Project status.
owner:
stringnull
Project owner.
start_date:
stringnull
Project start date. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.
end_date:
stringnull
Project end date. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.
street_1:
stringnull
Project address, street line 1.
street_2:
stringnull
Project address, street line 2.
city:
stringnull
Project address town or city.
region:
stringnull
Project address state, province, or region.
postal_code:
stringnull
Project address zip or postal code.
country:
stringnull
Project address country in 2-letter ISO 3166 code.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

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


{"category":"58fe37462b628c0f0033a798","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7ce","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":[{"language":"json","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","name":"Success","status":200}]},"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":27,"body":"","excerpt":"Get a list of projects where the PlanGrid account is a team member. Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"list-all-projects","type":"get","title":"List All Projects","__v":0,"childrenPages":[]}

getList All Projects

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.

Query Params

limit:
integer50
Number of projects to retrieve. Maximum value of 50.
skip:
integer0
Number of projects to skip in the set of results.
updated_after:
datetime
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.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

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


{"category":"58fe37462b628c0f0033a798","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7cf","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","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","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\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","name":"No Access","status":403}]},"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":28,"body":"","excerpt":"Get a specific project by unique identifier.","slug":"retrieve-a-project","type":"get","title":"Retrieve a Project","__v":0,"childrenPages":[]}

getRetrieve a Project

Get a specific project by unique identifier.

Path Params

project_uid:
required
string
Unique identifier of project to retrieve.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

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


{"category":"58fe37462b628c0f0033a798","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7d0","next":{"pages":[],"description":""},"createdAt":"2016-03-19T19:38:02.478Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"patch","results":{"codes":[{"status":200,"language":"json","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}","name":""},{"status":400,"language":"json","code":"{\n  \"message\": \"Name (0) must be a string at least one character long.\"\n}","name":"Invalid Name"},{"status":400,"language":"json","code":"{\n  \"message\": \"Custom ID must be null or a string at least one character long.\"\n}","name":"Invalid Custom ID"},{"code":"{\n  \"message\": \"Type (2) must be a valid project type.\"\n}","language":"json","status":400,"name":"Invalid Type"},{"code":"{\n  \"message\": \"Status must be null or a string at least one character long.\"\n}","language":"json","status":400,"name":"Invalid Status"},{"code":"{\n  \"message\": \"Owner must be null or a string at least one character long.\"\n}","language":"json","name":"Invalid Owner","status":400},{"code":"{\n  \"message\": \"Start date (1234) must be null or a date string in ISO-8601 format (YYYY-MM-DD).\"\n}","language":"json","name":"Invalid Start Date","status":400},{"code":"{\n  \"message\": \"End date (1234) must be null or a date string in ISO-8601 format (YYYY-MM-DD).\"\n}","language":"json","name":"Invalid End Date","status":400},{"status":400,"name":"Invalid Street 1","language":"json","code":"{\n  \"message\": \"Street 1 must be null or a string at least one character long.\"\n}"},{"status":400,"name":"Invalid Street 2","language":"json","code":"{\n  \"message\": \"Street 2 must be null or a string at least one character long.\"\n}"},{"status":400,"name":"Invalid City","language":"json","code":"{\n  \"message\": \"City must be null or a string at least one character long.\"\n}"},{"status":400,"name":"Invalid Region","language":"json","code":"{\n  \"message\": \"Region must be null or a string at least one character long.\"\n}"},{"status":400,"name":"Invalid Postal Code","language":"json","code":"{\n  \"message\": \"Postal code must be null or a string at least one character long.\"\n}"},{"code":"{\n  \"message\": \"Country must be an ISO 3166 two letter country code.\"\n}","language":"json","name":"Invalid Country","status":400},{"code":"{\n  \"message\": \"Insufficient permissions to update project fields (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","language":"json","status":403,"name":"Insufficient Permissions"}]},"settings":"","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":29,"body":"","excerpt":"Update a PlanGrid project","slug":"update-project","type":"patch","title":"Update Project","__v":0,"childrenPages":[]}

patchUpdate Project

Update a PlanGrid project

Path Params

project_uid:
string
Unique identifier of the project.

Body Params

name:
string
New name of the project. Must be at least one character long.
custom_id:
string
Project code.
type:
string
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`.
status:
string
Project status.
owner:
string
Project owner.
start_date:
string
Project start date. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.
end_date:
string
Project end date. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.
street_1:
string
Project address, street line 1
street_2:
string
Project address, street line 2
city:
string
Project address town or city.
region:
string
Project address state, province, or region.
postal_code:
string
Project address zip or postal code.
country:
string
Project address country in 2-letter ISO 3166 code.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

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)."
}


{"__v":0,"_id":"58fe37462b628c0f0033a7c1","api":{"results":{"codes":[{"name":"","code":"{}","language":"json","status":200},{"name":"","code":"{}","language":"json","status":400}]},"settings":"","auth":"required","params":[],"url":""},"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]","category":"58fe37462b628c0f0033a799","createdAt":"2017-01-12T19:19:52.839Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","next":{"pages":[],"description":""},"order":30,"parentDoc":null,"project":"55d2023b3c74062300aee506","slug":"the-annotation-object","sync_unique":"","title":"The Annotation Object","type":"basic","updates":[],"user":"57db49de0678030e008a76f8","version":"58fe37462b628c0f0033a792","childrenPages":[]}

The Annotation Object


Attribute
Description

uid
string

Unique identifier of the annotation. Never blank. See Unique Identifiers for details.

color
string

Color of the annotation in hexadecimal format.

stamp
string

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.

visibility
string

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.

deleted
boolean

Whether the annotation has been deleted. Never blank.

sheet
object

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"
    }
}
{"__v":0,"_id":"58fe37462b628c0f0033a7c2","api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"name":"","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}","language":"json","status":200},{"status":404,"language":"json","code":"{ \"message\": \"Project (0d0f2b52-17e4-4a38-8cc4-eb22997e8a36) does not exist.\" }"},{"status":403,"language":"json","code":"{ \"message\": \"Project (0d0f2b52-17e4-4a38-8cc4-eb22997e8a36) does not exist.\" }"}]},"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"},"body":"","category":"58fe37462b628c0f0033a799","createdAt":"2017-01-12T19:21:28.127Z","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.","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","next":{"pages":[],"description":""},"order":31,"parentDoc":null,"project":"55d2023b3c74062300aee506","slug":"retrieve-annotations-in-a-project","sync_unique":"","title":"Retrieve Annotations in a Project","type":"get","updates":[],"user":"57db49de0678030e008a76f8","version":"58fe37462b628c0f0033a792","childrenPages":[]}

getRetrieve Annotations in a Project

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.

Path Params

project_uid:
required
string
Unique identifier of project.

Query Params

limit:
integer50
Number of annotations to retrieve. Maximum value of 50.
skip:
integer0
Number of annotations to skip in the set of results.
updated_after:
datetime
Only retrieve annotations created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

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


{"category":"58fe37462b628c0f0033a79a","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7b3","next":{"pages":[],"description":""},"createdAt":"2015-10-23T22:54:15.916Z","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":32,"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 attachment. 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 attachment 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 attachment has been deleted. Never blank.\",\n    \"3-0\": \"**url**\\n`string`\",\n    \"3-1\": \"URL to retrieve attachment file.\",\n    \"2-0\": \"**folder**\\n`string`\",\n    \"2-1\": \"Case-sensitive.\"\n  },\n  \"cols\": 2,\n  \"rows\": 7\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"uid\\\": \\\"78128c72-5862-458a-9577-33eaa189a5c1\\\",\\n  \\\"name\\\": \\\"Submittal.4.2.pdf\\\",\\n  \\\"folder\\\": \\\"Submittals\\\",\\n  \\\"url\\\": \\\"https://attachment-assets.plangrid.com/78128c72-5862-458a-9577-33eaa189a5c1.pdf\\\",\\n  \\\"created_at\\\": \\\"2015-10-12T16:22:54+00:00\\\",\\n  \\\"created_by\\\": {\\n    \\\"uid\\\": \\\"d3bade89-01bf-4ea0-889e-d5dad2f56e7e\\\",\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d3bade89-01bf-4ea0-889e-d5dad2f56e7e\\\",\\n    \\\"email\\\": \\\"patrick.peterson@subcontractor.com\\\"    \\n  },\\n  \\\"deleted\\\": false\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-attachment-object","type":"basic","title":"The Attachment Object","__v":0,"childrenPages":[]}

The Attachment Object


Attribute
Description

uid
string

Never blank. See Unique Identifiers for details.

name
string

-

folder
string

Case-sensitive.

url
string

URL to retrieve attachment file.

created_at
string

When the attachment was created by a client application. UTC date and time in ISO-8601 format.

created_by
object

Reference to PlanGrid user that created the attachment. In rare cases, this may not map to a real user. See Foreign Keys for attribute details.

deleted
boolean

Whether the attachment has been deleted. Never blank.

{
  "uid": "78128c72-5862-458a-9577-33eaa189a5c1",
  "name": "Submittal.4.2.pdf",
  "folder": "Submittals",
  "url": "https://attachment-assets.plangrid.com/78128c72-5862-458a-9577-33eaa189a5c1.pdf",
  "created_at": "2015-10-12T16:22:54+00:00",
  "created_by": {
    "uid": "d3bade89-01bf-4ea0-889e-d5dad2f56e7e",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d3bade89-01bf-4ea0-889e-d5dad2f56e7e",
    "email": "patrick.peterson@subcontractor.com"    
  },
  "deleted": false
}
{"category":"58fe37462b628c0f0033a79a","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55fc7da63c21291900e7e0a5","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7b4","next":{"pages":[],"description":""},"createdAt":"2017-04-13T20:42:13.382Z","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":33,"body":"The following table lists the various file types supported as attachments.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Type of document\",\n    \"h-1\": \"File extension\",\n    \"0-0\": \"Image\",\n    \"0-1\": \".png\\n.jpeg\\n.jpg\\n.gif\\n.bmp\",\n    \"1-0\": \"Spreadsheet\",\n    \"1-1\": \".xlsx\\n.xls\",\n    \"2-0\": \"Open Document\",\n    \"2-1\": \".rtf\\n.doc\\n.docx\\n.txt\\n.odf\",\n    \"3-0\": \"Video\",\n    \"3-1\": \".webm\\n.mpg\\n.mov\\n.f4v\\n.avi\\n.mp4\\n.wmv\",\n    \"4-0\": \"Design\",\n    \"4-1\": \".rvt\\n.dwg\\n.dxf\\n.dgn\\n.dwf\\n.dwfx\",\n    \"5-0\": \"Google Earth\",\n    \"5-1\": \".kmz\\n.kml\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]","excerpt":"","slug":"supported-file-types","type":"basic","title":"Supported File Types","__v":0,"childrenPages":[]}

Supported File Types


The following table lists the various file types supported as attachments.

Type of document
File extension

Image

.png
.jpeg
.jpg
.gif
.bmp

Spreadsheet

.xlsx
.xls

Open Document

.rtf
.doc
.docx
.txt
.odf

Video

.webm
.mpg
.mov
.f4v
.avi
.mp4
.wmv

Design

.rvt
.dwg
.dxf
.dgn
.dwf
.dwfx

Google Earth

.kmz
.kml

{"category":"58fe37462b628c0f0033a79a","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7b5","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,"name":"Success","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","language":"json"},{"status":400,"name":"Unsupported Content Type","code":"{\n  \"message\": \"Content type (application/msword) is not supported.\"\n}\n","language":"json"},{"status":400,"name":"Content Type Missing","code":"{\n  \"message\": \"Content type (application/msword) is not supported.\"\n}\n","language":"json"},{"status":400,"name":"Invalid Name","code":"{\n  \"message\": \"Name (null) must be a string at least one character long.\"\n}\n","language":"json"},{"status":400,"name":"Invalid Folder","code":"{\n  \"message\": \"Folder (2) must be null or a string at least one character long.\"\n}\n","language":"json"},{"status":403,"name":"Insufficient Permissions","code":"{\n  \"message\": \"Insufficient permissions to upload attachments to 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"}]},"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 attachment's file.","default":"","type":"string","name":"content_type"},{"_id":"56cf1ec95267d70b00494b95","ref":"","in":"body","required":true,"desc":"Name of the attachment.","default":"","type":"string","name":"name"},{"_id":"56cf1ec95267d70b00494b94","ref":"","in":"body","required":false,"desc":"Folder in project to place the attachment in (case-sensitive).","default":"","type":"string","name":"folder"}],"url":"/projects/:project_uid/attachments/uploads"},"isReference":false,"order":34,"body":"","excerpt":"First of three step process for uploading an attachment to a project. On success, necessary information for step two and three is returned. The attachment 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 Attachment to Project","__v":0,"childrenPages":[]}

postUpload Attachment to Project

First of three step process for uploading an attachment to a project. On success, necessary information for step two and three is returned. The attachment record is not created until all three steps are completed. See [File Uploads](doc:file-uploads) for details.

Path Params

project_uid:
required
string
Unique identifier of project.

Body Params

content_type:
required
string
Content type of the attachment's file.
name:
required
string
Name of the attachment.
folder:
string
Folder in project to place the attachment in (case-sensitive).

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

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


{"category":"58fe37462b628c0f0033a79a","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7b6","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":[{"status":201,"name":"Success","code":"{\n  \"uid\": \"147a420e-a182-4312-8fa5-4d10064d2f1a\",\n  \"name\": \"Bender\",\n  \"folder\": \"Specifications\",\n  \"url\": \"https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf\",\n  \"created_at\": \"2013-05-17T02:30:22+00:00\",\n  \"created_by\": {\n    \"uid\": null,\n    \"url\": null,\n    \"email\": \"nick@subcontractor.com\"\n  },\n  \"deleted\": false\n}\n","language":"json"},{"status":400,"name":"File Missing","code":"{\n  \"message\": \"File associated with upload token (8392cd3fbf2dfbf9fc539c8423a21201) is missing.\"\n}\n","language":"json"},{"status":404,"name":"Upload Token Missing","code":"{\n  \"message\": \"Attachment for upload token (8392cd3fbf2dfbf9fc539c8423a21201) does not exist\"\n}\n","language":"json"},{"status":410,"name":"Upload Token Expired","code":"{\n  \"message\": \"Upload token (8392cd3fbf2dfbf9fc539c8423a21201) expired.\"\n}","language":"json"},{"status":500,"name":"Server Error","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","language":"json"},{"status":409,"language":"json","code":"{\n  \"message\": \"Upload token (8392cd3fbf2dfbf9fc539c8423a21201) consumed.\"\n}"}]},"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":35,"body":"","excerpt":"Last of three step process for uploading an attachment to a project. On success, the new attachment 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 Attachment Upload to Project","__v":0,"childrenPages":[]}

getComplete Attachment Upload to Project

Last of three step process for uploading an attachment to a project. On success, the new attachment record is created and returned. This step is handled automatically with appropriate configuration. See [File Uploads](doc:file-uploads) for details.

Path Params

project_uid:
required
string
Unique identifier of project.
upload_token:
required
string
Token that uniquely identifies the upload.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "uid": "147a420e-a182-4312-8fa5-4d10064d2f1a",
  "name": "Bender",
  "folder": "Specifications",
  "url": "https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf",
  "created_at": "2013-05-17T02:30:22+00:00",
  "created_by": {
    "uid": null,
    "url": null,
    "email": "nick@subcontractor.com"
  },
  "deleted": false
}
{
  "message": "File associated with upload token (8392cd3fbf2dfbf9fc539c8423a21201) is missing."
}
{
  "message": "Attachment for upload token (8392cd3fbf2dfbf9fc539c8423a21201) does not exist"
}
{
  "message": "Upload token (8392cd3fbf2dfbf9fc539c8423a21201) expired."
}
{
  "message": "Sorry, PlanGrid was unable to complete the upload. Use the url included with this message to try again."
  "url": "https://io.plangrid.com/v1/projects/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7/attachments/uploads/completions/8392cd3fbf2dfbf9fc539c8423a21201"
}
{
  "message": "Upload token (8392cd3fbf2dfbf9fc539c8423a21201) consumed."
}


{"category":"58fe37462b628c0f0033a79a","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7b7","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":[{"language":"json","code":"{\n  \"data\": [\n    {\n      \"uid\": \"147a420e-a182-4312-8fa5-4d10064d2f1a\",\n      \"name\": \"Bender\",\n      \"folder\": \"Specifications\",\n      \"url\": \"https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf\",\n      \"created_at\": \"2013-05-17T02:30:22+00:00\",\n      \"created_by\": {\n        \"uid\": null,\n        \"url\": null,\n        \"email\": \"nick@subcontractor.com\"\n      },\n      \"deleted\": false\n    },\n    {\n      \"uid\": \"40f38b8b-019e-44d8-8cb8-86454c327fb5\",\n      \"name\": \"Cement\",\n      \"folder\": \"Submittals\",\n      \"url\": \"https://attachment-assets.plangrid.com/40f38b8b-019e-44d8-8cb8-86454c327fb5.pdf\",\n      \"created_at\": \"2013-05-13T04:30:22+00:00\",\n      \"created_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"betty@construction.com\"\n      },\n      \"deleted\": true\n    }\n  ],\n  \"total_count\": 14,\n  \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/attachments?skip=2&limit=2\"\n}\n","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\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","name":"No Project Access","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 attachments where folder is `null` or `\"\"`.","default":"","type":"string","name":"folder"},{"_id":"56cf1ec95267d70b00494b91","ref":"","in":"query","required":false,"desc":"Number of attachments to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ec95267d70b00494b90","ref":"","in":"query","required":false,"desc":"Number of attachments to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"56edba05949cc2320083727b","ref":"","in":"query","required":false,"desc":"Only retrieve attachments 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":36,"body":"","excerpt":"Get a list of attachments in a project optionally filtered by folder. Results return deleted attachments 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 Attachments in a Project","__v":0,"childrenPages":[]}

getRetrieve Attachments in a Project

Get a list of attachments in a project optionally filtered by folder. Results return deleted attachments and are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.

Path Params

project_uid:
required
string
Unique identifier of project.

Query Params

folder:
string
Folder to filter results by (case-sensitive). Empty string retrieves all attachments where folder is `null` or `""`.
limit:
integer50
Number of attachments to retrieve. Maximum value of 50.
skip:
integer0
Number of attachments to skip in the set of results.
updated_after:
datetime
Only retrieve attachments created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "uid": "147a420e-a182-4312-8fa5-4d10064d2f1a",
      "name": "Bender",
      "folder": "Specifications",
      "url": "https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf",
      "created_at": "2013-05-17T02:30:22+00:00",
      "created_by": {
        "uid": null,
        "url": null,
        "email": "nick@subcontractor.com"
      },
      "deleted": false
    },
    {
      "uid": "40f38b8b-019e-44d8-8cb8-86454c327fb5",
      "name": "Cement",
      "folder": "Submittals",
      "url": "https://attachment-assets.plangrid.com/40f38b8b-019e-44d8-8cb8-86454c327fb5.pdf",
      "created_at": "2013-05-13T04:30:22+00:00",
      "created_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "betty@construction.com"
      },
      "deleted": true
    }
  ],
  "total_count": 14,
  "next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/attachments?skip=2&limit=2"
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}


{"category":"58fe37462b628c0f0033a79a","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7b8","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":[{"language":"json","code":"{\n  \"uid\": \"147a420e-a182-4312-8fa5-4d10064d2f1a\",\n  \"name\": \"Bender\",\n  \"folder\": \"Specifications\",\n  \"url\": \"https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf\",\n  \"created_at\": \"2013-05-17T02:30:22+00:00\",\n  \"created_by\": {\n    \"uid\": null,\n    \"url\": null,\n    \"email\": \"nick@subcontractor.com\"\n  },\n  \"deleted\": false\n}\n","name":"Success","status":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\": \"Attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"Attachment 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}]},"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 attachment.","default":"","type":"string","name":"attachment_uid"}],"url":"/projects/:project_uid/attachments/:attachment_uid"},"isReference":false,"order":37,"body":"","excerpt":"Get an attachment in a project.","slug":"retrieve-attachment-in-a-project","type":"get","title":"Retrieve Attachment in a Project","__v":0,"childrenPages":[]}

getRetrieve Attachment in a Project

Get an attachment in a project.

Path Params

project_uid:
required
string
Unique identifier of project.
attachment_uid:
required
string
Unique identifier of attachment.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "uid": "147a420e-a182-4312-8fa5-4d10064d2f1a",
  "name": "Bender",
  "folder": "Specifications",
  "url": "https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf",
  "created_at": "2013-05-17T02:30:22+00:00",
  "created_by": {
    "uid": null,
    "url": null,
    "email": "nick@subcontractor.com"
  },
  "deleted": false
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "Attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}


{"category":"58fe37462b628c0f0033a79a","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7b9","next":{"pages":[],"description":""},"createdAt":"2016-03-20T22:42:40.912Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"patch","results":{"codes":[{"language":"json","code":"{\n  \"uid\": \"147a420e-a182-4312-8fa5-4d10064d2f1a\",\n  \"name\": \"Bender\",\n  \"folder\": \"Specifications\",\n  \"url\": \"https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf\",\n  \"created_at\": \"2013-05-17T02:30:22+00:00\",\n  \"created_by\": {\n    \"uid\": null,\n    \"url\": null,\n    \"email\": \"nick@subcontractor.com\"\n  },\n  \"deleted\": false\n}\n","name":"Success","status":200},{"language":"json","code":"{\n  \"message\": \"Name (null) must be a string at least one character long.\"\n}","name":"Invalid Name","status":400},{"language":"json","code":"{\n  \"message\": \"Folder (2) must be null or a string at least one character long.\"\n}","name":"Invalid Folder","status":400},{"language":"json","code":"{\n  \"message\": \"Insufficient permissions to update attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) in project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","name":"Insufficient Permissions","status":403},{"language":"json","code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}","name":"No Access","status":403},{"status":400,"language":"json","code":"{\n  \"message\": \"Attachment (baa813cf-fd44-4a9c-be2b-62669958cc9a) is deleted and cannot be updated.\"\n}"},{"name":"Attachment Missing","status":404,"language":"json","code":"{\n  \"message\": \"Attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) was not found in project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}"},{"code":"{\n  \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}","language":"json","name":"Project Missing","status":404}]},"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":"Unique identifier of attachment","default":"","type":"string","name":"attachmend_uid"},{"_id":"56cf1ec95267d70b00494b95","ref":"","in":"body","required":false,"desc":"New name of the attachment.","default":"","type":"string","name":"name"},{"_id":"56cf1ec95267d70b00494b94","ref":"","in":"body","required":false,"desc":"New folder in project to place the attachment in (case-sensitive).","default":"","type":"string","name":"folder"}],"url":"/projects/:project_uid/attachments/:attachment_uid"},"isReference":false,"order":38,"body":"","excerpt":"Update an attachment's metadata. If you want to change the attachment's file, you'll need to delete the photo and upload a new one.","slug":"update-attachment-in-a-project","type":"patch","title":"Update Attachment in a Project","__v":0,"childrenPages":[]}

patchUpdate Attachment in a Project

Update an attachment's metadata. If you want to change the attachment's file, you'll need to delete the photo and upload a new one.

Path Params

project_uid:
required
string
Unique identifier of project.

Body Params

attachmend_uid:
required
string
Unique identifier of attachment
name:
string
New name of the attachment.
folder:
string
New folder in project to place the attachment in (case-sensitive).

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "uid": "147a420e-a182-4312-8fa5-4d10064d2f1a",
  "name": "Bender",
  "folder": "Specifications",
  "url": "https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf",
  "created_at": "2013-05-17T02:30:22+00:00",
  "created_by": {
    "uid": null,
    "url": null,
    "email": "nick@subcontractor.com"
  },
  "deleted": false
}
{
  "message": "Name (null) must be a string at least one character long."
}
{
  "message": "Folder (2) must be null or a string at least one character long."
}
{
  "message": "Insufficient permissions to update attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) in project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{
  "message": "Attachment (baa813cf-fd44-4a9c-be2b-62669958cc9a) is deleted and cannot be updated."
}
{
  "message": "Attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) was not found in project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}


{"category":"58fe37462b628c0f0033a79a","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7ba","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":[{"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\": \"Attachment (87658a3f-8ee0-4188-9c55-b06a203fa9e7) was not found in project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","status":404,"name":"Attachment Missing"},{"name":"No Project Access","status":403,"language":"json","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 attachment.","default":"","type":"string","name":"attachment_uid"}],"url":"/projects/:project_uid/attachments/:attachment_uid"},"isReference":false,"order":39,"body":"","excerpt":"Removes an attachment from a project. If attachment 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 Attachment from Project","__v":0,"childrenPages":[]}

deleteRemove Attachment from Project

Removes an attachment from a project. If attachment has already been removed, a `204` is still returned. See [Deleted Records](doc:deleted-records) for details on deleted records.

Path Params

project_uid:
required
string
Unique identifier of project.
attachment_uid:
required
string
Unique identifier of attachment.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}


{"category":"58fe37462b628c0f0033a79b","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7c6","next":{"pages":[],"description":""},"createdAt":"2016-08-14T21:07:05.673Z","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":40,"body":"[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"**uid**\\n`string`\",\n    \"3-0\": \"**created_by**\\n`object`\",\n    \"0-1\": \"Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n    \"3-1\": \"Reference to PlanGrid user that created issue. Will always map to a real user. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"1-0\": \"**text**\\n`string`\",\n    \"1-1\": \"-\",\n    \"2-1\": \"When the comment was created by a client application. UTC date and time in ISO-8601 format.\",\n    \"2-0\": \"**created_at**\\n`string`\",\n    \"4-0\": \"**record_type***\\n`string`\",\n    \"4-1\": \"Type of record the comment is for. Possible values are `project`, `issue`, `rfi`, and `sheet`.\",\n    \"5-0\": \"**record**\\n`object`\",\n    \"5-1\": \"Reference to record comment is for. See [Foreign Keys](doc:foreign-keys) for attribute details.\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"uid\\\": \\\"8510cfc9-2a82-4736-bf37-753c900d1c68\\\",\\n  \\\"text\\\": \\\"You looking at me?\\\",\\n  \\\"created_at\\\": \\\"2015-10-12T14:17:27+00:00\\\",\\n  \\\"created_by\\\": {\\n    \\\"uid\\\": \\\"10dd6d24-cbe2-4639-9647-f9d0cc4aaee8\\\",\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/10dd6d24-cbe2-4639-9647-f9d0cc4aaee8\\\",\\n    \\\"email\\\": \\\"travis@subcontractor.com\\\"    \\n  },\\n  \\\"record_type\\\": \\\"project\\\",\\n  \\\"record\\\": {\\n    \\\"uid\\\": \\\"bafce976-8f33-437f-9c52-fb274456940f\\\",\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f\\\",\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-comment-object","type":"basic","title":"The Comment Object","__v":0,"childrenPages":[]}

The Comment Object


Attribute
Description

uid
string

Never blank. See Unique Identifiers for details.

text
string

-

created_at
string

When the comment was created by a client application. UTC date and time in ISO-8601 format.

created_by
object

Reference to PlanGrid user that created issue. Will always map to a real user. See Foreign Keys for attribute details.

record_type*
string

Type of record the comment is for. Possible values are project, issue, rfi, and sheet.

record
object

Reference to record comment is for. See Foreign Keys for attribute details.

{
  "uid": "8510cfc9-2a82-4736-bf37-753c900d1c68",
  "text": "You looking at me?",
  "created_at": "2015-10-12T14:17:27+00:00",
  "created_by": {
    "uid": "10dd6d24-cbe2-4639-9647-f9d0cc4aaee8",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/10dd6d24-cbe2-4639-9647-f9d0cc4aaee8",
    "email": "travis@subcontractor.com"    
  },
  "record_type": "project",
  "record": {
    "uid": "bafce976-8f33-437f-9c52-fb274456940f",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f",
  }
}
{"category":"58fe37462b628c0f0033a79b","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7c7","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":[{"name":"Success","code":"{\n  \"data\": [\n    {\n      \"uid\": \"87658a3f-8ee0-4188-9c55-b06a203fa9e7\",\n      \"text\": \"Great Scott!\",\n      \"created_at\": \"2013-05-17t02:30:22z\",\n      \"created_by\": {\n        \"uid\": \"deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n        \"email\": \"doc@subcontractor.com\"\n      },\n      \"record_type\": \"project\",\n      \"record\": {\n        \"uid\": \"bafce976-8f33-437f-9c52-fb274456940f\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f\"\n      }\n    },\n    {\n      \"uid\": \"465abf98-accb-42cd-bd54-16f29e8447f2\",\n      \"text\": \"Jesus, George, it was a wonder I was even born.\",\n      \"created_at\": \"2013-05-15t18:54:22z\",\n      \"created_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"marty@construction.com\"\n      },\n      \"record_type\": \"issue\",\n      \"record\": {\n        \"uid\": \"b9876ac1-369f-401b-8ca0-6f152b533895\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895\"\n      }\n    },\n    {\n      \"uid\": \"08ea8b05-a99c-40a7-a312-fee360ad432a\",\n      \"text\": \"I'm sure that in 1985, plutonium is available in every corner drugstore, but in 1955, it's a little hard to come by.\",\n      \"created_at\": \"2013-05-14t8:30:56z\",\n      \"created_by\": {\n        \"uid\": \"deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n        \"email\": \"doc@subcontractor.com\"\n      },\n      \"record_type\": \"rfi\",\n      \"record\": {\n        \"uid\": \"c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\"\n      }\n    },\n    {\n      \"uid\": \"68839690-e0aa-4751-aedf-e630b921e91e\",\n      \"text\": \"Look, Marvin, you gotta play. See, that's where they kiss for the first time on the dance floor. And if there's no music, they can't dance. If they can't dance, they can't kiss. If they can't kiss they can't fall in love, and I'm history.\",\n      \"created_at\": \"2013-05-13t11:22:56z\",\n      \"created_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"marty@construction.com\"\n      },\n      \"record_type\": \"rfi\",\n      \"record\": {\n        \"uid\": \"c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\"\n      }\n    }\n  ],\n  \"total_count\": 6,\n  \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/comments?skip=4&limit=4\"\n}","language":"json","status":200},{"name":"Project Missing","code":"{\n  \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}","language":"json","status":404},{"language":"json","code":"{\n  \"message\": \"Record type (1) must be a valid record type.\"\n}","status":400,"name":"Invalid Record Type"},{"name":"No Project Access","status":403,"language":"json","code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}"}]},"settings":"","auth":"required","params":[{"_id":"57b0e1de9ee0960e00440bbe","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"57b0e1de9ee0960e00440bbd","ref":"","in":"query","required":false,"desc":"Number of comments to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"57b0e1de9ee0960e00440bbc","ref":"","in":"query","required":false,"desc":"Number of comments to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"57b0e1de9ee0960e00440bbb","ref":"","in":"query","required":false,"desc":"Only retrieve comments created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"datetime","name":"updated_after"},{"_id":"57b0e2889ee0960e00440bbf","ref":"","in":"query","required":false,"desc":"Comma separate list of record types. Possible values are `project`, `issue`, `rfi`, `sheet`. Case insensitive and removes duplicates.","default":"","type":"string","name":"record_types"}],"url":"/projects/:project_uid/comments"},"isReference":false,"order":41,"body":"","excerpt":"Get a list of comments across all records in a project (most recently created first).  Results are paginated and can optionally be filtered by record type, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-comments-in-a-project","type":"get","title":"Retrieve Comments in a Project","__v":0,"childrenPages":[]}

getRetrieve Comments in a Project

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.

Path Params

project_uid:
required
string
Unique identifier of project.

Query Params

limit:
integer50
Number of comments to retrieve. Maximum value of 50.
skip:
integer0
Number of comments to skip in the set of results.
updated_after:
datetime
Only retrieve comments created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.
record_types:
string
Comma separate list of record types. Possible values are `project`, `issue`, `rfi`, `sheet`. Case insensitive and removes duplicates.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "uid": "87658a3f-8ee0-4188-9c55-b06a203fa9e7",
      "text": "Great Scott!",
      "created_at": "2013-05-17t02:30:22z",
      "created_by": {
        "uid": "deae0b56-81c7-4a05-8e8b-410fd17a01f0",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0",
        "email": "doc@subcontractor.com"
      },
      "record_type": "project",
      "record": {
        "uid": "bafce976-8f33-437f-9c52-fb274456940f",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f"
      }
    },
    {
      "uid": "465abf98-accb-42cd-bd54-16f29e8447f2",
      "text": "Jesus, George, it was a wonder I was even born.",
      "created_at": "2013-05-15t18:54:22z",
      "created_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "marty@construction.com"
      },
      "record_type": "issue",
      "record": {
        "uid": "b9876ac1-369f-401b-8ca0-6f152b533895",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895"
      }
    },
    {
      "uid": "08ea8b05-a99c-40a7-a312-fee360ad432a",
      "text": "I'm sure that in 1985, plutonium is available in every corner drugstore, but in 1955, it's a little hard to come by.",
      "created_at": "2013-05-14t8:30:56z",
      "created_by": {
        "uid": "deae0b56-81c7-4a05-8e8b-410fd17a01f0",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0",
        "email": "doc@subcontractor.com"
      },
      "record_type": "rfi",
      "record": {
        "uid": "c62d6a09-1e7c-4aa0-b60b-86249eba7e5b",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b"
      }
    },
    {
      "uid": "68839690-e0aa-4751-aedf-e630b921e91e",
      "text": "Look, Marvin, you gotta play. See, that's where they kiss for the first time on the dance floor. And if there's no music, they can't dance. If they can't dance, they can't kiss. If they can't kiss they can't fall in love, and I'm history.",
      "created_at": "2013-05-13t11:22:56z",
      "created_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "marty@construction.com"
      },
      "record_type": "rfi",
      "record": {
        "uid": "c62d6a09-1e7c-4aa0-b60b-86249eba7e5b",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b"
      }
    }
  ],
  "total_count": 6,
  "next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/comments?skip=4&limit=4"
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "Record type (1) must be a valid record type."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}


{"category":"58fe37462b628c0f0033a79c","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7f8","next":{"pages":[],"description":""},"createdAt":"2015-09-28T06:57:39.713Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":42,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Sheet Versions & Annotations\"\n}\n[/block]\nMultiple versions of the same sheet can exist in PlanGrid. As new versions of a sheet are uploaded, the annotations on old versions are copied to the newer version. We’ll illustrate how this is represented in PlanGrid’s data model via a simple example. Say you upload the first version of a sheet (“Version 1”); a Sheet record is created in PlanGrid with `sheet.version_name` set to “Version 1”:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/CdUUaxKQwi24DmpR6KjD_1.png\",\n        \"1.png\",\n        \"2438\",\n        \"451\",\n        \"#c7c7c7\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nSometime later you upload the second version of a sheet (“Version 2”). A second Sheet record is created in PlanGrid with `sheet.version_name` set to “Version 2”:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/QVxkrdfxQGy9ILZd7kSL_2.png\",\n        \"2.png\",\n        \"2438\",\n        \"451\",\n        \"#cdcdcd\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nYou add an annotation to the second version of the sheet. This creates an Annotation record that points to the second version Sheet record (via a foreign key for the Sheet `uid`):\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/fiqwlVJoS4iWroprHM9R_3.png\",\n        \"3.png\",\n        \"2438\",\n        \"451\",\n        \"#9c9c9c\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nWhen you upload the third version of a sheet (“Version 3”), the annotation is copied from “Version 2”. In our data model, a new Sheet record is created (with `sheet.version_name` set to “Version 3”), the Annotation record is copied, and the copy points to the third version Sheet Record:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/EbQKdX80SkC6REHl0Nrq_4.png\",\n        \"4.png\",\n        \"2438\",\n        \"451\",\n        \"#9e9e9e\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Issues and Annotations\"\n}\n[/block]\nWhen an issue is placed on a sheet, the PlanGrid data model creates an Issue record *and* an Annotation record. The annotation stores information on where and how to display the issue on the sheet. As new versions of a sheet are uploaded, multiple annotations are created:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/YVK4B3p1TIqcHDNkvp4F_5.png\",\n        \"5.png\",\n        \"1313\",\n        \"392\",\n        \"#c7c7c7\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\nAs a convenience, we include the most current annotation on any issue record returned through the PlanGrid API.","excerpt":"","slug":"sheet-versions-annotations","type":"basic","title":"Background","__v":0,"childrenPages":[]}

Background


Sheet Versions & Annotations

Multiple versions of the same sheet can exist in PlanGrid. As new versions of a sheet are uploaded, the annotations on old versions are copied to the newer version. We’ll illustrate how this is represented in PlanGrid’s data model via a simple example. Say you upload the first version of a sheet (“Version 1”); a Sheet record is created in PlanGrid with sheet.version_name set to “Version 1”:

Sometime later you upload the second version of a sheet (“Version 2”). A second Sheet record is created in PlanGrid with sheet.version_name set to “Version 2”:

You add an annotation to the second version of the sheet. This creates an Annotation record that points to the second version Sheet record (via a foreign key for the Sheet uid):

When you upload the third version of a sheet (“Version 3”), the annotation is copied from “Version 2”. In our data model, a new Sheet record is created (with sheet.version_name set to “Version 3”), the Annotation record is copied, and the copy points to the third version Sheet Record:

Issues and Annotations

When an issue is placed on a sheet, the PlanGrid data model creates an Issue record and an Annotation record. The annotation stores information on where and how to display the issue on the sheet. As new versions of a sheet are uploaded, multiple annotations are created:

As a convenience, we include the most current annotation on any issue record returned through the PlanGrid API.

{"__v":0,"_id":"58fe37472b628c0f0033a7f9","api":{"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"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\": \"**current_annotation**\\n`object`\",\n    \"3-0\": \"**current_annotation.uid**\\n`string`\",\n    \"4-0\": \"**current_annotation.color**\\n`string`\",\n    \"5-0\": \"**current_annotation.stamp**\\n`string`\",\n    \"6-0\": \"**current_annotation.visibility**\\n`string`\",\n    \"7-0\": \"**current_annotation.deleted**\\n`boolean`\",\n    \"8-0\": \"**current_annotation.sheet**\\n`object`\",\n    \"9-0\": \"**room**\\n`string`\",\n    \"11-0\": \"**description**\\n`string`\",\n    \"12-0\": \"**assigned_to**\\n`array`\",\n    \"13-0\": \"**status**\\n`string`\",\n    \"14-0\": \"**created_at**\\n`string`\",\n    \"15-0\": \"**created_by**\\n`object`\",\n    \"16-0\": \"**updated_at**\\n`string`\",\n    \"17-0\": \"**updated_by**\\n`object`\",\n    \"26-0\": \"**deleted**\\n`boolean`\",\n    \"1-1\": \"Issue number assigned by PlanGrid. May not be unique. Never blank.\",\n    \"2-1\": \"Associated annotation that exists on most recent version. May not be current set. In rare cases, may be blank.\",\n    \"3-1\": \"Unique identifier of the annotation. Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n    \"4-1\": \"Color of the annotation in [hexadecimal format](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet).\",\n    \"5-1\": \"One to two character stamp associated with issue. Usually indicates type of issue or trade associated with issue.\",\n    \"6-1\": \"Visibility level of issue. Can be either `user` or `master`. `User` indicates a team member (or former team member) has not published the issue to the project. Never blank.\",\n    \"7-1\": \"Whether the annotation has been deleted. Never blank.\",\n    \"8-1\": \"Reference to sheet the current annotation is located on. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n    \"9-1\": \"Room or location of issue.\",\n    \"11-1\": \"-\",\n    \"12-1\": \"An array of users that the issue is assigned to. Currently only supports one user. Does not have to be a real PlanGrid user. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n    \"13-1\": \"Current status of issue. Possible values are \\\"open\\\", \\\"in_review\\\", \\\"pending\\\", \\\"closed\\\".\",\n    \"14-1\": \"When the issue was created by a client application. UTC date and time in ISO-8601 format.\",\n    \"15-1\": \"Reference to PlanGrid user that created issue. In rare cases, this may not map to a real user. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n    \"16-1\": \"When the issue was updated by a PlanGrid client. Publishing, moving issue on sheet, modifying photos, or adding comments *will not affect* updated_at. UTC date and time in ISO-8601 format.\",\n    \"17-1\": \"Reference to PlanGrid user that last updated issue. In rare cases, this may not map to a real user. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n    \"26-1\": \"Whether the issue has been deleted. Never blank.\",\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"18-0\": \"**photos**\\n`object`\",\n    \"19-0\": \"**comments**\\n`object`\",\n    \"18-1\": \"Reference to collection of photos on issue. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n    \"19-1\": \"Reference to collection of comments on issue. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n    \"10-0\": \"**title**\\n`string`\",\n    \"10-1\": \"-\",\n    \"20-0\": \"**due_at**\\n`string`\",\n    \"20-1\": \"When the Issue is due. UTC date and time in ISO-8601 format. May be `null`.\",\n    \"21-0\": \"**has_cost_impact**\\n`boolean`\",\n    \"21-1\": \"Whether the Issue has a cost impact. Never blank.\",\n    \"22-0\": \"**cost_impact**\\n`decimal`\",\n    \"22-1\": \"What the Issue's cost impact with accuracy to hundredths of a cent. May be `null`.\",\n    \"23-0\": \"**currency_code**\\n`string`\",\n    \"23-1\": \"The ISO-4217 currency code of the `cost_impact`. Currently only supports `USD`. May be `null` if `cost_impact` is not specified.\",\n    \"24-0\": \"**has_schedule_impact**\\n`boolean`\",\n    \"24-1\": \"Whether the Issue has a schedule impact. Never blank.\",\n    \"25-0\": \"**schedule_impact**\\n`integer`\",\n    \"25-1\": \"What the Issue's schedule impact is in seconds. May be `null`.\"\n  },\n  \"cols\": 2,\n  \"rows\": 27\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"uid\\\": \\\"22f3530a-a00b-42f9-8139-3a7554c77c27\\\",\\n  \\\"number\\\": 1,\\n  \\\"current_annotation\\\": {\\n    \\\"uid\\\": \\\"6994b73b-c3b4-4aa3-a985-fd973e599526\\\",\\n    \\\"color\\\": \\\"#F38109\\\",\\n    \\\"stamp\\\": \\\"E\\\",\\n    \\\"visibility\\\": \\\"master\\\",\\n    \\\"deleted\\\": false,\\n    \\\"sheet\\\": {\\n      \\\"uid\\\": \\\"f3718ded-9919-4667-a746-969fda1cfe26\\\",\\n      \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26\\\"\\n    }\\n  },\\n  \\\"title\\\": \\\"Electrical\\\",\\n  \\\"room\\\": \\\"M100\\\",\\n  \\\"description\\\": \\\"Missing wall outlets.\\\",\\n  \\\"assigned_to\\\": [{\\n    \\\"uid\\\": \\\"80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",                \\n    \\\"email\\\": \\\"bob@subcontractor.com\\\"\\n  }],\\n  \\\"status\\\": \\\"open\\\",\\n  \\\"created_at\\\": \\\"2015-06-08T18:04:02+00:00\\\",\\n  \\\"created_by\\\": {\\n    \\\"uid\\\": null,\\n    \\\"url\\\": null,\\n    \\\"email\\\": \\\"alfred@architect.com\\\"\\n  },\\n  \\\"updated_at\\\": \\\"2013-05-23T19:22:56+00:00\\\",\\n  \\\"updated_by\\\": {\\n    \\\"uid\\\": null,\\n    \\\"url\\\": null,\\n    \\\"email\\\": \\\"betty@construction.com\\\"\\n  },\\n  \\\"photos\\\": {\\n    \\\"total_count\\\": 1,\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/22f3530a-a00b-42f9-8139-3a7554c77c27/photos\\\"\\n  },\\n  \\\"comments\\\": {\\n    \\\"total_count\\\": 0,\\n    \\\"url\\\": null\\n  },\\n  \\\"due_at\\\": \\\"2016-10-31T15:32:26+00:00\\\",\\n  \\\"has_cost_impact\\\": true,\\n  \\\"cost_impact\\\": 25850.10,\\n  \\\"currency_code\\\": \\\"USD\\\",\\n  \\\"has_schedule_impact\\\": true,\\n  \\\"schedule_impact\\\": 186400,\\n  \\\"deleted\\\": false\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Archived Issues\"\n}\n[/block]\nWhen an issue is archived through the PlanGrid client apps, it is hidden on the sheet but visible in the issue log. An issue is represented through the PlanGrid API as an issue whose `deleted` value is `false` and whose `current_annotation.deleted` is `true`.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"deleted\\\": false,\\n  \\\"current_annotation\\\": {\\n    \\\"deleted\\\": true,\\n    \\\"sheet\\\": {\\n      ...\\n    }\\n    ...\\n  },\\n  ...\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","category":"58fe37462b628c0f0033a79c","createdAt":"2015-09-27T22:03:27.758Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","next":{"pages":[],"description":""},"order":43,"parentDoc":null,"project":"55d2023b3c74062300aee506","slug":"the-issue-object","sync_unique":"","title":"The Issue Object","type":"basic","updates":[],"user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","childrenPages":[]}

The Issue Object


Attribute
Description

uid
string

Never blank. See Unique Identifiers for details.

number
integer

Issue number assigned by PlanGrid. May not be unique. Never blank.

current_annotation
object

Associated annotation that exists on most recent version. May not be current set. In rare cases, may be blank.

current_annotation.uid
string

Unique identifier of the annotation. Never blank. See Unique Identifiers for details.

current_annotation.color
string

Color of the annotation in hexadecimal format.

current_annotation.stamp
string

One to two character stamp associated with issue. Usually indicates type of issue or trade associated with issue.

current_annotation.visibility
string

Visibility level of issue. Can be either user or master. User indicates a team member (or former team member) has not published the issue to the project. Never blank.

current_annotation.deleted
boolean

Whether the annotation has been deleted. Never blank.

current_annotation.sheet
object

Reference to sheet the current annotation is located on. See Foreign Keys for attribute details.

room
string

Room or location of issue.

title
string

-

description
string

-

assigned_to
array

An array of users that the issue is assigned to. Currently only supports one user. Does not have to be a real PlanGrid user. See Foreign Keys for attribute details.

status
string

Current status of issue. Possible values are "open", "in_review", "pending", "closed".

created_at
string

When the issue was created by a client application. UTC date and time in ISO-8601 format.

created_by
object

Reference to PlanGrid user that created issue. In rare cases, this may not map to a real user. See Foreign Keys for attribute details.

updated_at
string

When the issue was updated by a PlanGrid client. Publishing, moving issue on sheet, modifying photos, or adding comments will not affect updated_at. UTC date and time in ISO-8601 format.

updated_by
object

Reference to PlanGrid user that last updated issue. In rare cases, this may not map to a real user. See Foreign Keys for attribute details.

photos
object

Reference to collection of photos on issue. See Foreign Keys for attribute details.

comments
object

Reference to collection of comments on issue. See Foreign Keys for attribute details.

due_at
string

When the Issue is due. UTC date and time in ISO-8601 format. May be null.

has_cost_impact
boolean

Whether the Issue has a cost impact. Never blank.

cost_impact
decimal

What the Issue's cost impact with accuracy to hundredths of a cent. May be null.

currency_code
string

The ISO-4217 currency code of the cost_impact. Currently only supports USD. May be null if cost_impact is not specified.

has_schedule_impact
boolean

Whether the Issue has a schedule impact. Never blank.

schedule_impact
integer

What the Issue's schedule impact is in seconds. May be null.

deleted
boolean

Whether the issue has been deleted. Never blank.

Archived Issues

When an issue is archived through the PlanGrid client apps, it is hidden on the sheet but visible in the issue log. An issue is represented through the PlanGrid API as an issue whose deleted value is false and whose current_annotation.deleted is true.

{
  "deleted": false,
  "current_annotation": {
    "deleted": true,
    "sheet": {
      ...
    }
    ...
  },
  ...
}
{
  "uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
  "number": 1,
  "current_annotation": {
    "uid": "6994b73b-c3b4-4aa3-a985-fd973e599526",
    "color": "#F38109",
    "stamp": "E",
    "visibility": "master",
    "deleted": false,
    "sheet": {
      "uid": "f3718ded-9919-4667-a746-969fda1cfe26",
      "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26"
    }
  },
  "title": "Electrical",
  "room": "M100",
  "description": "Missing wall outlets.",
  "assigned_to": [{
    "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",                
    "email": "bob@subcontractor.com"
  }],
  "status": "open",
  "created_at": "2015-06-08T18:04:02+00:00",
  "created_by": {
    "uid": null,
    "url": null,
    "email": "alfred@architect.com"
  },
  "updated_at": "2013-05-23T19:22:56+00:00",
  "updated_by": {
    "uid": null,
    "url": null,
    "email": "betty@construction.com"
  },
  "photos": {
    "total_count": 1,
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/22f3530a-a00b-42f9-8139-3a7554c77c27/photos"
  },
  "comments": {
    "total_count": 0,
    "url": null
  },
  "due_at": "2016-10-31T15:32:26+00:00",
  "has_cost_impact": true,
  "cost_impact": 25850.10,
  "currency_code": "USD",
  "has_schedule_impact": true,
  "schedule_impact": 186400,
  "deleted": false
}
{"category":"58fe37462b628c0f0033a79c","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7fa","next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:05:36.806Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"status":200,"name":"Success","code":"{\n  \"data\": [\n    {\n      \"uid\": \"22f3530a-a00b-42f9-8139-3a7554c77c27\",\n      \"number\": 1,\n      \"current_annotation\": {\n        \"uid\": \"6994b73b-c3b4-4aa3-a985-fd973e599526\",\n        \"color\": \"#F38109\",\n        \"stamp\": \"E\",\n        \"visibility\": \"master\",\n        \"deleted\": false,\n        \"sheet\": {\n          \"uid\": \"f3718ded-9919-4667-a746-969fda1cfe26\",\n          \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26\"\n        }\n      },\n      \"title\": \"Electrical\",\n      \"room\": \"M100\",\n      \"description\": \"Missing wall outlets.\",\n      \"assigned_to\": [{\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"bob@subcontractor.com\"\n      }],\n      \"status\": \"open\",\n      \"created_at\": \"2015-06-08T18:04:02+00:00\",\n      \"created_by\": {\n        \"uid\": null,\n        \"url\": null,\n        \"email\": \"alfred@architect.com\"\n      },\n      \"updated_at\": \"2013-05-23T19:22:56+00:00\",\n      \"updated_by\": {\n        \"uid\": null,\n        \"url\": null,\n        \"email\": \"betty@construction.com\"\n      },\n      \"photos\": {\n        \"total_count\": 0,\n        \"url\": null\n      },\n      \"comments\": {\n        \"total_count\": 2,\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/22f3530a-a00b-42f9-8139-3a7554c77c27/comments\"\n      },\n      \"due_at\": \"2016-11-02T10:12:28+00:00\",\n      \"has_cost_impact\": true,\n      \"cost_impact\": 1800.00,\n      \"currency_code\": \"USD\",\n      \"has_schedule_impact\": false,\n      \"schedule_impact\": null,\n      \"deleted\": false\n    },\n    {\n      \"uid\": \"51cb7310-6feb-47ae-8ad9-a89ac6101294\",\n      \"number\": 2,\n      \"current_annotation\": {\n        \"uid\": \"6994b73b-c3b4-4aa3-a985-fd973e599526\",\n        \"color\": \"#F38109\",\n        \"stamp\": \"CN\",\n        \"visibility\": \"master\",\n        \"deleted\": false,\n        \"sheet\": {\n          \"uid\": \"f3718ded-9919-4667-a746-969fda1cfe26\",\n          \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26\"\n        }\n      },\n      \"title\": \"Cleaning Needed\",\n      \"room\": \"M101\",\n      \"description\": \"Clean paint and drywall mud from fire alarm.\",\n      \"assigned_to\": [{\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"bob@subcontractor.com\"\n      }],\n      \"status\": \"open\",\n      \"created_at\": \"2015-06-08T18:04:02+00:00\",\n      \"created_by\": {\n        \"uid\": null,\n        \"url\": null,\n        \"email\": \"alfred@architect.com\"\n      },\n      \"updated_at\": \"2013-05-23T19:22:56+00:00\",\n      \"updated_by\": {\n        \"uid\": null,\n        \"url\": null,\n        \"email\": \"betty@construction.com\"\n      },\n      \"photos\": {\n        \"total_count\": 1,\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos\"\n      },\n      \"comments\": {\n        \"total_count\": 2,\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments\"\n      },\n      \"due_at\": null,\n      \"has_cost_impact\": false,\n      \"cost_impact\": null,\n      \"currency_code\": null,\n      \"has_schedule_impact\": true,\n      \"schedule_impact\": 259200,\n      \"deleted\": false\n    }\n  ],\n  \"total_count\": 50,\n  \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues?skip=2&limit=2\"\n}\n","language":"json"},{"status":200,"name":"Archived Issue","code":"{\n  \"data\": [\n    {\n      \"uid\": \"22f3530a-a00b-42f9-8139-3a7554c77c27\",\n      \"number\": 1,\n      \"current_annotation\": {\n        \"uid\": \"6994b73b-c3b4-4aa3-a985-fd973e599526\",\n        \"color\": \"#F38109\",\n        \"stamp\": \"E\",\n        \"visibility\": \"master\",\n        \"deleted\": true,\n        \"sheet\": {\n          \"uid\": \"f3718ded-9919-4667-a746-969fda1cfe26\",\n          \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26\"\n        }\n      },\n      \"title\": \"Electrical\",\n      \"description\": \"Missing wall outlets.\",\n      \"assigned_to\": [{\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"bob@subcontractor.com\"\n      }],\n      \"status\": \"open\",\n      \"created_at\": \"2015-06-08T18:04:02Z\",\n      \"created_by\": {\n        \"uid\": null,\n        \"url\": null,\n        \"email\": \"alfred@architect.com\"\n      },\n      \"updated_at\": \"2013-05-23T19:22:56Z\",\n      \"room\": \"S20\",\n      \"updated_by\": {\n        \"uid\": null,\n        \"url\": null,\n        \"email\": \"betty@construction.com\"\n      },\n      \"deleted\": false,\n      \"photos\": {\n        \"total_count\": 0,\n        \"url\": null\n      },\n      \"comments\": {\n        \"total_count\": 2,\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/22f3530a-a00b-42f9-8139-3a7554c77c27/comments\"\n      }\n    },\n  ],\n  \"total_count\": 10,\n  \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues?skip=1&limit=1\"\n}\n","language":"json"},{"status":404,"name":"Project Missing","code":"{\n  \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\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":"56cf1eca5267d70b00494ba2","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1eca5267d70b00494ba1","ref":"","in":"query","required":false,"desc":"Number of issues to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1eca5267d70b00494ba0","ref":"","in":"query","required":false,"desc":"Number of issues to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"56edbf5efc1410200082dc72","ref":"","in":"query","required":false,"desc":"Only retrieve issues created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"datetime","name":"updated_after"}],"url":"/projects/:project_uid/issues"},"isReference":false,"order":44,"body":"","excerpt":"Get a list of issues in a project. _All issues_ inside a project are returned, including deleted, archived, and personal issues across all team members. Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-issues-in-a-project","type":"get","title":"Retrieve Issues in a Project","__v":0,"childrenPages":[]}

getRetrieve Issues in a Project

Get a list of issues in a project. _All issues_ inside a project are returned, including deleted, archived, and personal issues across all team members. Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.

Path Params

project_uid:
required
string
Unique identifier of project.

Query Params

limit:
integer50
Number of issues to retrieve. Maximum value of 50.
skip:
integer0
Number of issues to skip in the set of results.
updated_after:
datetime
Only retrieve issues created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
      "number": 1,
      "current_annotation": {
        "uid": "6994b73b-c3b4-4aa3-a985-fd973e599526",
        "color": "#F38109",
        "stamp": "E",
        "visibility": "master",
        "deleted": false,
        "sheet": {
          "uid": "f3718ded-9919-4667-a746-969fda1cfe26",
          "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26"
        }
      },
      "title": "Electrical",
      "room": "M100",
      "description": "Missing wall outlets.",
      "assigned_to": [{
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "bob@subcontractor.com"
      }],
      "status": "open",
      "created_at": "2015-06-08T18:04:02+00:00",
      "created_by": {
        "uid": null,
        "url": null,
        "email": "alfred@architect.com"
      },
      "updated_at": "2013-05-23T19:22:56+00:00",
      "updated_by": {
        "uid": null,
        "url": null,
        "email": "betty@construction.com"
      },
      "photos": {
        "total_count": 0,
        "url": null
      },
      "comments": {
        "total_count": 2,
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/22f3530a-a00b-42f9-8139-3a7554c77c27/comments"
      },
      "due_at": "2016-11-02T10:12:28+00:00",
      "has_cost_impact": true,
      "cost_impact": 1800.00,
      "currency_code": "USD",
      "has_schedule_impact": false,
      "schedule_impact": null,
      "deleted": false
    },
    {
      "uid": "51cb7310-6feb-47ae-8ad9-a89ac6101294",
      "number": 2,
      "current_annotation": {
        "uid": "6994b73b-c3b4-4aa3-a985-fd973e599526",
        "color": "#F38109",
        "stamp": "CN",
        "visibility": "master",
        "deleted": false,
        "sheet": {
          "uid": "f3718ded-9919-4667-a746-969fda1cfe26",
          "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26"
        }
      },
      "title": "Cleaning Needed",
      "room": "M101",
      "description": "Clean paint and drywall mud from fire alarm.",
      "assigned_to": [{
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "bob@subcontractor.com"
      }],
      "status": "open",
      "created_at": "2015-06-08T18:04:02+00:00",
      "created_by": {
        "uid": null,
        "url": null,
        "email": "alfred@architect.com"
      },
      "updated_at": "2013-05-23T19:22:56+00:00",
      "updated_by": {
        "uid": null,
        "url": null,
        "email": "betty@construction.com"
      },
      "photos": {
        "total_count": 1,
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos"
      },
      "comments": {
        "total_count": 2,
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments"
      },
      "due_at": null,
      "has_cost_impact": false,
      "cost_impact": null,
      "currency_code": null,
      "has_schedule_impact": true,
      "schedule_impact": 259200,
      "deleted": false
    }
  ],
  "total_count": 50,
  "next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues?skip=2&limit=2"
}
{
  "data": [
    {
      "uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
      "number": 1,
      "current_annotation": {
        "uid": "6994b73b-c3b4-4aa3-a985-fd973e599526",
        "color": "#F38109",
        "stamp": "E",
        "visibility": "master",
        "deleted": true,
        "sheet": {
          "uid": "f3718ded-9919-4667-a746-969fda1cfe26",
          "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26"
        }
      },
      "title": "Electrical",
      "description": "Missing wall outlets.",
      "assigned_to": [{
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "bob@subcontractor.com"
      }],
      "status": "open",
      "created_at": "2015-06-08T18:04:02Z",
      "created_by": {
        "uid": null,
        "url": null,
        "email": "alfred@architect.com"
      },
      "updated_at": "2013-05-23T19:22:56Z",
      "room": "S20",
      "updated_by": {
        "uid": null,
        "url": null,
        "email": "betty@construction.com"
      },
      "deleted": false,
      "photos": {
        "total_count": 0,
        "url": null
      },
      "comments": {
        "total_count": 2,
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/22f3530a-a00b-42f9-8139-3a7554c77c27/comments"
      }
    },
  ],
  "total_count": 10,
  "next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues?skip=1&limit=1"
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}


{"category":"58fe37462b628c0f0033a79c","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7fb","next":{"pages":[],"description":""},"createdAt":"2016-08-14T20:58:00.971Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"name":"","code":"{\n  \"uid\": \"51cb7310-6feb-47ae-8ad9-a89ac6101294\",\n  \"number\": 2,\n  \"current_annotation\": {\n    \"uid\": \"6994b73b-c3b4-4aa3-a985-fd973e599526\",\n    \"color\": \"#F38109\",\n    \"stamp\": \"CN\",\n    \"visibility\": \"master\",\n    \"deleted\": false,\n    \"sheet\": {\n      \"uid\": \"f3718ded-9919-4667-a746-969fda1cfe26\",\n      \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26\"\n    }\n  },\n  \"title\": \"Cleaning Needed\",\n  \"room\": \"M101\",\n  \"description\": \"Clean paint and drywall mud from fire alarm.\",\n  \"assigned_to\": [{\n    \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n    \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n    \"email\": \"bob@subcontractor.com\"\n  }],\n  \"status\": \"open\",\n  \"created_at\": \"2015-06-08T18:04:02+00:00\",\n  \"created_by\": {\n    \"uid\": null,\n    \"url\": null,\n    \"email\": \"alfred@architect.com\"\n  },\n  \"updated_at\": \"2013-05-23T19:22:56+00:00\",\n  \"updated_by\": {\n    \"uid\": null,\n    \"url\": null,\n    \"email\": \"betty@construction.com\"\n  },\n  \"photos\": {\n    \"total_count\": 1,\n    \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos\"\n  },\n  \"comments\": {\n    \"total_count\": 2,\n    \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments\"\n  },\n  \"due_at\": false,\n  \"has_cost_impact\": false,\n  \"cost_impact\": null,\n  \"currency_code\": null,\n  \"has_schedule_impact\": false,\n  \"schedule_impact\": null,\n  \"deleted\": false\n}","language":"json","status":200},{"name":"Project Missing","code":"{\n  \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}","language":"json","status":404},{"name":"Issue Missing","code":"{\n  \"message\": \"Issue (ee28dd97-bb68-4108-8cea-fb4a1cbccff8) does not exist.\"\n}","language":"json","status":404},{"name":"No Project Access","status":403,"language":"json","code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}"}]},"settings":"","auth":"required","params":[{"_id":"57b0dc21430b3d0e00703a5f","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"57b0dc21430b3d0e00703a5e","ref":"","in":"path","required":true,"desc":"Unique identifier of issue","default":"","type":"string","name":"issue_uid"}],"url":"/projects/:project_uid/issues/:issue_uid"},"isReference":false,"order":45,"body":"","excerpt":"Get an issue in a project.","slug":"retrieve-issue-in-a-project","type":"get","title":"Retrieve Issue in a Project","__v":0,"childrenPages":[]}

getRetrieve Issue in a Project

Get an issue in a project.

Path Params

project_uid:
required
string
Unique identifier of project.
issue_uid:
required
string
Unique identifier of issue

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "uid": "51cb7310-6feb-47ae-8ad9-a89ac6101294",
  "number": 2,
  "current_annotation": {
    "uid": "6994b73b-c3b4-4aa3-a985-fd973e599526",
    "color": "#F38109",
    "stamp": "CN",
    "visibility": "master",
    "deleted": false,
    "sheet": {
      "uid": "f3718ded-9919-4667-a746-969fda1cfe26",
      "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/sheets/f3718ded-9919-4667-a746-969fda1cfe26"
    }
  },
  "title": "Cleaning Needed",
  "room": "M101",
  "description": "Clean paint and drywall mud from fire alarm.",
  "assigned_to": [{
    "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
    "email": "bob@subcontractor.com"
  }],
  "status": "open",
  "created_at": "2015-06-08T18:04:02+00:00",
  "created_by": {
    "uid": null,
    "url": null,
    "email": "alfred@architect.com"
  },
  "updated_at": "2013-05-23T19:22:56+00:00",
  "updated_by": {
    "uid": null,
    "url": null,
    "email": "betty@construction.com"
  },
  "photos": {
    "total_count": 1,
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos"
  },
  "comments": {
    "total_count": 2,
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments"
  },
  "due_at": false,
  "has_cost_impact": false,
  "cost_impact": null,
  "currency_code": null,
  "has_schedule_impact": false,
  "schedule_impact": null,
  "deleted": false
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "Issue (ee28dd97-bb68-4108-8cea-fb4a1cbccff8) does not exist."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}


{"category":"58fe37462b628c0f0033a79c","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7fc","next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:09:53.175Z","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\": \"there's that word again. \\\"heavy\\\". why are things so heavy in the future? is there a problem with the earth's gravitational pull?\",\n      \"created_at\": \"2013-05-17t02:30:22z\",\n      \"created_by\": {\n        \"uid\": \"deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n        \"email\": \"doc@subcontractor.com\"\n      },\n      \"record_type\": \"issue\",\n      \"record\": {\n        \"uid\": \"b9876ac1-369f-401b-8ca0-6f152b533895\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895\"\n      }\n    },\n    {\n      \"uid\": \"465abf98-accb-42cd-bd54-16f29e8447f2\",\n      \"text\": \"woh. this is heavy!\",\n      \"created_at\": \"2013-05-15t18:54:22+00:00\",\n      \"created_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"marty@construction.com\"\n      },\n      \"record_type\": \"issue\",\n      \"record\": {\n        \"uid\": \"b9876ac1-369f-401b-8ca0-6f152b533895\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895\"\n      }\n    },\n    {\n      \"uid\": \"08ea8b05-a99c-40a7-a312-fee360ad432a\",\n      \"text\": \"precisely.\",\n      \"created_at\": \"2013-05-14t8:30:56+00:00\",\n      \"created_by\": {\n        \"uid\": \"deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n        \"email\": \"doc@subcontractor.com\"\n      },\n      \"record_type\": \"issue\",\n      \"record\": {\n        \"uid\": \"b9876ac1-369f-401b-8ca0-6f152b533895\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895\"\n      }\n    },\n    {\n      \"uid\": \"68839690-e0aa-4751-aedf-e630b921e91e\",\n      \"text\": \"wait a minute, Doc, are you trying to tell me that my mother has got the hots for me?\",\n      \"created_at\": \"2013-05-13t11:22:56+00:00\",\n      \"created_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"marty@construction.com\"\n      },\n      \"record_type\": \"issue\",\n      \"record\": {\n        \"uid\": \"b9876ac1-369f-401b-8ca0-6f152b533895\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895\"\n      }\n    }\n  ],\n  \"total_count\": 6,\n  \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments?skip=4&limit=4\"\n}\n","language":"json"},{"status":404,"name":"Project Missing","code":"{\n  \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}","language":"json"},{"status":404,"name":"Issue Missing","code":"{\n  \"message\": \"Issue (68839690-e0aa-4751-aedf-e630b921e91e) 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) is prohibited.\"\n}\n","language":"json"}]},"settings":"","auth":"required","params":[{"_id":"56cf1ec95267d70b00494b9b","ref":"","in":"path","required":true,"desc":"Unique identifier for issue's project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ec95267d70b00494b9a","ref":"","in":"path","required":true,"desc":"Unique identifier of issue.","default":"","type":"string","name":"issue_uid"},{"_id":"56cf1ec95267d70b00494b99","ref":"","in":"query","required":false,"desc":"Number of comments to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ec95267d70b00494b98","ref":"","in":"query","required":false,"desc":"Number of comments to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"56edc058c3628a170081f008","ref":"","in":"query","required":false,"desc":"Only retrieve comments created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"datetime","name":"updated_after"}],"url":"/projects/:project_uid/issues/:issue_uid/comments"},"isReference":false,"order":46,"body":"","excerpt":"Get a list of comments on an issue. Comment data is described in [The Comment Object](doc:the-comment-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-comments-on-an-issue","type":"get","title":"Retrieve Comments on an Issue","__v":0,"childrenPages":[]}

getRetrieve Comments on an Issue

Get a list of comments on an issue. Comment data is described in [The Comment Object](doc:the-comment-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.

Path Params

project_uid:
required
string
Unique identifier for issue's project.
issue_uid:
required
string
Unique identifier of issue.

Query Params

limit:
integer50
Number of comments to retrieve. Maximum value of 50.
skip:
integer0
Number of comments to skip in the set of results.
updated_after:
datetime
Only retrieve comments created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "uid": "87658a3f-8ee0-4188-9c55-b06a203fa9e7",
      "text": "there's that word again. \"heavy\". why are things so heavy in the future? is there a problem with the earth's gravitational pull?",
      "created_at": "2013-05-17t02:30:22z",
      "created_by": {
        "uid": "deae0b56-81c7-4a05-8e8b-410fd17a01f0",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0",
        "email": "doc@subcontractor.com"
      },
      "record_type": "issue",
      "record": {
        "uid": "b9876ac1-369f-401b-8ca0-6f152b533895",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895"
      }
    },
    {
      "uid": "465abf98-accb-42cd-bd54-16f29e8447f2",
      "text": "woh. this is heavy!",
      "created_at": "2013-05-15t18:54:22+00:00",
      "created_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "marty@construction.com"
      },
      "record_type": "issue",
      "record": {
        "uid": "b9876ac1-369f-401b-8ca0-6f152b533895",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895"
      }
    },
    {
      "uid": "08ea8b05-a99c-40a7-a312-fee360ad432a",
      "text": "precisely.",
      "created_at": "2013-05-14t8:30:56+00:00",
      "created_by": {
        "uid": "deae0b56-81c7-4a05-8e8b-410fd17a01f0",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0",
        "email": "doc@subcontractor.com"
      },
      "record_type": "issue",
      "record": {
        "uid": "b9876ac1-369f-401b-8ca0-6f152b533895",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895"
      }
    },
    {
      "uid": "68839690-e0aa-4751-aedf-e630b921e91e",
      "text": "wait a minute, Doc, are you trying to tell me that my mother has got the hots for me?",
      "created_at": "2013-05-13t11:22:56+00:00",
      "created_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "marty@construction.com"
      },
      "record_type": "issue",
      "record": {
        "uid": "b9876ac1-369f-401b-8ca0-6f152b533895",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/b9876ac1-369f-401b-8ca0-6f152b533895"
      }
    }
  ],
  "total_count": 6,
  "next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments?skip=4&limit=4"
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "Issue (68839690-e0aa-4751-aedf-e630b921e91e) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}


{"category":"58fe37462b628c0f0033a79c","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7fd","next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:11:37.361Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"status":200,"name":"Success","code":"{\n  \"data\": [\n    {\n      \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n      \"title\": \"Bongo Drums\",\n      \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n      \"created_at\": \"2013-05-17T02:30:22+00:00\",\n      \"created_by\": {\n        \"uid\": null,\n        \"url\": null,\n        \"email\": \"nick@subcontractor.com\"\n      },\n      \"deleted\": false\n    },\n    {\n      \"uid\": \"9acc66f0-b704-4469-99fa-c13ce2b0bf0a\",\n      \"title\": \"Bass Guitar\",\n      \"url\": \"https://photo-assets.plangrid.com/9acc66f0-b704-4469-99fa-c13ce2b0bf0a.jpg\",\n      \"created_at\": \"2013-05-13T04:30:22+00:00\",\n      \"created_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"betty@construction.com\"\n      },\n      \"deleted\": false\n    }\n  ],\n  \"total_count\": 14,\n  \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/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":"Issue Missing","code":"{\n  \"message\": \"Issue (87658a3f-8ee0-4188-9c55-b06a203fa9e7) 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) is prohibited.\"\n}\n","language":"json"}]},"settings":"","auth":"required","params":[{"_id":"56cf1eca5267d70b00494b9f","ref":"","in":"path","required":true,"desc":"Unique identifier for issue's project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1eca5267d70b00494b9e","ref":"","in":"path","required":true,"desc":"Unique identifier of issue.","default":"","type":"string","name":"issue_uid"},{"_id":"56cf1eca5267d70b00494b9d","ref":"","in":"query","required":false,"desc":"Number of photos to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1eca5267d70b00494b9c","ref":"","in":"query","required":false,"desc":"Number of photos to skip in the set of results.","default":"0","type":"int","name":"skip"},{"_id":"56edc390fc1410200082dc7b","ref":"","in":"query","required":false,"desc":"Only retrieve photos created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"datetime","name":"updated_after"}],"url":"/projects/:project_uid/issues/:issue_uid/photos"},"isReference":false,"order":47,"body":"","excerpt":"Get a list of photos added to an issue. Photo data is described in [The Photo Object](doc:the-photo-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-photos-on-an-issue","type":"get","title":"Retrieve Photos on an Issue","__v":0,"childrenPages":[]}

getRetrieve Photos on an Issue

Get a list of photos added to an issue. Photo data is described in [The Photo Object](doc:the-photo-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.

Path Params

project_uid:
required
string
Unique identifier for issue's project.
issue_uid:
required
string
Unique identifier of issue.

Query Params

limit:
integer50
Number of photos to retrieve. Maximum value of 50.
skip:
integer0
Number of photos to skip in the set of results.
updated_after:
datetime
Only retrieve photos created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
      "title": "Bongo Drums",
      "url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
      "created_at": "2013-05-17T02:30:22+00:00",
      "created_by": {
        "uid": null,
        "url": null,
        "email": "nick@subcontractor.com"
      },
      "deleted": false
    },
    {
      "uid": "9acc66f0-b704-4469-99fa-c13ce2b0bf0a",
      "title": "Bass Guitar",
      "url": "https://photo-assets.plangrid.com/9acc66f0-b704-4469-99fa-c13ce2b0bf0a.jpg",
      "created_at": "2013-05-13T04:30:22+00:00",
      "created_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "betty@construction.com"
      },
      "deleted": false
    }
  ],
  "total_count": 14,
  "next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/issues/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos?skip=2&limit=2"
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "Issue (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}


{"category":"58fe37462b628c0f0033a79d","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7e6","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,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":48,"body":"[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"**uid**\\n`string`\",\n    \"4-0\": \"**created_by**\\n`object`\",\n    \"0-1\": \"Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n    \"4-1\": \"Reference to PlanGrid user that created the photo. In rare cases, this may not map to a real user. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"1-0\": \"**title**\\n`string`\",\n    \"1-1\": \"-\",\n    \"3-1\": \"When the photo was created by a client application. UTC date and time in ISO-8601 format.\",\n    \"3-0\": \"**created_at**\\n`string`\",\n    \"5-0\": \"**deleted**\\n`boolean`\",\n    \"5-1\": \"Whether the photo has been deleted. Never blank.\",\n    \"2-0\": \"**url**\\n`string`\",\n    \"2-1\": \"URL to retrieve image file.\"\n  },\n  \"cols\": 2,\n  \"rows\": 6\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"uid\\\": \\\"319ec8e8-7ad8-4173-aa69-de55a5a259c0\\\",\\n  \\\"title\\\": \\\"Selfie\\\",\\n  \\\"url\\\": \\\"https://photo-assets.plangrid.com/319ec8e8-7ad8-4173-aa69-de55a5a259c0.jpg\\\",\\n  \\\"created_at\\\": \\\"2015-10-12T16:22:54Z\\\",\\n  \\\"created_by\\\": {\\n    \\\"uid\\\": \\\"d3bade89-01bf-4ea0-889e-d5dad2f56e7e\\\",\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d3bade89-01bf-4ea0-889e-d5dad2f56e7e\\\",\\n    \\\"email\\\": \\\"patrick.peterson@subcontractor.com\\\"    \\n  },\\n  \\\"deleted\\\": false\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-photo-object","type":"basic","title":"The Photo Object","__v":0,"childrenPages":[]}

The Photo Object


Attribute
Description

uid
string

Never blank. See Unique Identifiers for details.

title
string

-

url
string

URL to retrieve image file.

created_at
string

When the photo was created by a client application. UTC date and time in ISO-8601 format.

created_by
object

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.

deleted
boolean

Whether the photo has been deleted. Never blank.

{
  "uid": "319ec8e8-7ad8-4173-aa69-de55a5a259c0",
  "title": "Selfie",
  "url": "https://photo-assets.plangrid.com/319ec8e8-7ad8-4173-aa69-de55a5a259c0.jpg",
  "created_at": "2015-10-12T16:22:54Z",
  "created_by": {
    "uid": "d3bade89-01bf-4ea0-889e-d5dad2f56e7e",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d3bade89-01bf-4ea0-889e-d5dad2f56e7e",
    "email": "patrick.peterson@subcontractor.com"    
  },
  "deleted": false
}
{"category":"58fe37462b628c0f0033a79d","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7e7","next":{"pages":[],"description":""},"createdAt":"2016-03-19T20:40:37.886Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"post","results":{"codes":[{"status":201,"name":"Success","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"},{"status":400,"name":"Unsupported Content Type","code":"{\n  \"message\": \"Content type (application/msword) is not supported.\"\n}\n","language":"json"},{"status":400,"name":"Content Type Missing","code":"{\n  \"message\": \"Content type (application/msword) is not supported.\"\n}\n","language":"json"},{"status":400,"name":"Invalid Title","code":"{\n  \"message\": \"Title (null) must be a string at least one character long.\"\n}\n","language":"json"},{"status":403,"name":"Insufficient Permissions","code":"{\n  \"message\": \"Insufficient permissions to upload photos to 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"}]},"settings":"","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":49,"body":"","excerpt":"First of three step process for uploading a photo to a project. On success, necessary information for step two and three is returned. The photo record is not created until all three steps are completed. See [File Uploads](doc:file-uploads) for details. Currently, only PNGs and JPEGs are supported.","slug":"upload-photo-to-project","type":"post","title":"Upload Photo to Project","__v":0,"childrenPages":[]}

postUpload Photo to Project

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.

Path Params

project_uid:
required
string
Unique identifier of project.

Body Params

content_type:
required
string
Content type of the photo's file.
title:
required
string
Title of the photo.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

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


{"category":"58fe37462b628c0f0033a79d","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7e8","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":[{"status":201,"name":"Success","code":"{\n  \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n  \"title\": \"Bongo Drums\",\n  \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n  \"created_at\": \"2013-05-17T02:30:22+00:00\",\n  \"created_by\": {\n    \"uid\": null,\n    \"url\": null,\n    \"email\": \"nick@subcontractor.com\"\n  },\n  \"deleted\": false\n}\n","language":"json"},{"status":400,"name":"File Missing","code":"{\n  \"message\": \"File associated with upload token (8392cd3fbf2dfbf9fc539c8423a21201) is missing.\"\n}\n","language":"json"},{"status":404,"name":"Upload Token Missing","code":"{\n  \"message\": \"Attachment for upload token (8392cd3fbf2dfbf9fc539c8423a21201) does not exist\"\n}\n","language":"json"},{"status":410,"name":"Upload Token Expired","code":"{\n  \"message\": \"Upload token (8392cd3fbf2dfbf9fc539c8423a21201) expired.\"\n}\n","language":"json"},{"status":500,"name":"Server Error","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","language":"json"},{"status":409,"language":"json","code":"{\n  \"message\": \"Upload token (8392cd3fbf2dfbf9fc539c8423a21201) consumed.\"\n}"}]},"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":50,"body":"","excerpt":"Last of three step process for uploading a photo to a project. On success, the new photo record is created and returned. This step is handled automatically with appropriate configuration. See [File Uploads](doc:file-uploads) for details.","slug":"complete-photo-upload-to-project","type":"get","title":"Complete Photo Upload to Project","__v":0,"childrenPages":[]}

getComplete Photo Upload to Project

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.

Path Params

project_uid:
required
string
Unique identifier of project.
upload_token:
required
string
Token that uniquely identifies the upload.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
  "title": "Bongo Drums",
  "url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
  "created_at": "2013-05-17T02:30:22+00:00",
  "created_by": {
    "uid": null,
    "url": null,
    "email": "nick@subcontractor.com"
  },
  "deleted": false
}
{
  "message": "File associated with upload token (8392cd3fbf2dfbf9fc539c8423a21201) is missing."
}
{
  "message": "Attachment for upload token (8392cd3fbf2dfbf9fc539c8423a21201) does not exist"
}
{
  "message": "Upload token (8392cd3fbf2dfbf9fc539c8423a21201) expired."
}
{
  "message": "Sorry, PlanGrid was unable to complete the upload. Use the url included with this message to try again."
  "url": "https://io.plangrid.com/v1/projects/4d0f4ff6-b4e7-fb41-edb2-139b0fff9ef7/photos/uploads/completions/8392cd3fbf2dfbf9fc539c8423a21201"
}
{
  "message": "Upload token (8392cd3fbf2dfbf9fc539c8423a21201) consumed."
}


{"category":"58fe37462b628c0f0033a79d","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7e9","next":{"pages":[],"description":""},"createdAt":"2016-03-19T20:32:04.072Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"language":"json","code":"{\n  \"data\": [\n    {\n      \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n      \"title\": \"Bongo Drums\",\n      \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n      \"created_at\": \"2013-05-17T02:30:22Z\",\n      \"created_by\": {\n        \"uid\": null,\n        \"url\": null,\n        \"email\": \"nick@subcontractor.com\"\n      },\n      \"deleted\": false\n    },\n    {\n      \"uid\": \"9acc66f0-b704-4469-99fa-c13ce2b0bf0a\",\n      \"title\": \"Bass Guitar\",\n      \"url\": \"https://photo-assets.plangrid.com/9acc66f0-b704-4469-99fa-c13ce2b0bf0a.jpg\",\n      \"created_at\": \"2013-05-13T04:30:22Z\",\n      \"created_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"betty@construction.com\"\n      },\n      \"deleted\": false\n    }\n  ],\n  \"total_count\": 14,\n  \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/photos?skip=2&limit=2\"\n}\n","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\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","name":"No Project Access","status":403}]},"settings":"","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":51,"body":"","excerpt":"Get a list of photos in a project optionally filtered by folder. Results return deleted photos and are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-photos-in-a-project","type":"get","title":"Retrieve Photos in a Project","__v":0,"childrenPages":[]}

getRetrieve Photos in a Project

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.

Path Params

project_uid:
required
string
Unique identifier of project.

Query Params

limit:
integer50
Number of photos to retrieve. Maximum value of 50.
skip:
integer0
Number of photos to skip in the set of results.
updated_after:
datetime
Only retrieve photos created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
      "title": "Bongo Drums",
      "url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
      "created_at": "2013-05-17T02:30:22Z",
      "created_by": {
        "uid": null,
        "url": null,
        "email": "nick@subcontractor.com"
      },
      "deleted": false
    },
    {
      "uid": "9acc66f0-b704-4469-99fa-c13ce2b0bf0a",
      "title": "Bass Guitar",
      "url": "https://photo-assets.plangrid.com/9acc66f0-b704-4469-99fa-c13ce2b0bf0a.jpg",
      "created_at": "2013-05-13T04:30:22Z",
      "created_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "betty@construction.com"
      },
      "deleted": false
    }
  ],
  "total_count": 14,
  "next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/photos?skip=2&limit=2"
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}


{"category":"58fe37462b628c0f0033a79d","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7ea","next":{"pages":[],"description":""},"createdAt":"2016-03-19T20:39:44.322Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"language":"json","code":"{\n  \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n  \"title\": \"Bongo Drums\",\n  \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n  \"created_at\": \"2013-05-17T02:30:22+00:00\",\n  \"created_by\": {\n    \"uid\": null,\n    \"url\": null,\n    \"email\": \"nick@subcontractor.com\"\n  },\n  \"deleted\": false\n}\n","name":"Success","status":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}]},"settings":"","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":52,"body":"","excerpt":"Get a photo in a project.","slug":"retrieve-photo-in-a-project","type":"get","title":"Retrieve Photo in a Project","__v":0,"childrenPages":[]}

getRetrieve Photo in a Project

Get a photo in a project.

Path Params

project_uid:
required
string
Unique identifier of project.
photo_uid:
required
string
Unique identifier of photo.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
  "title": "Bongo Drums",
  "url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
  "created_at": "2013-05-17T02:30:22+00:00",
  "created_by": {
    "uid": null,
    "url": null,
    "email": "nick@subcontractor.com"
  },
  "deleted": false
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "Photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}


{"category":"58fe37462b628c0f0033a79d","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7eb","next":{"pages":[],"description":""},"createdAt":"2016-03-20T22:34:36.424Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"patch","results":{"codes":[{"status":200,"name":"Success","code":"{\n  \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n  \"title\": \"Bongo Drums\",\n  \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n  \"created_at\": \"2013-05-17T02:30:22+00:00\",\n  \"created_by\": {\n    \"uid\": null,\n    \"url\": null,\n    \"email\": \"nick@subcontractor.com\"\n  },\n  \"deleted\": false\n}\n","language":"json"},{"status":404,"name":"Project Missing","code":"{\n  \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","language":"json"},{"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"},{"name":"Insufficient Permissions","status":403,"language":"json","code":"{\n  \"message\": \"Insufficient permissions to update photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) in project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}"},{"code":"{\n  \"message\": \"Title (2) must be a string at least one character long.\"\n}","language":"json","status":400,"name":"Invalid Title"},{"status":400,"language":"json","code":"{\n  \"message\": \"Photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) is deleted and cannot be updated.\"\n}","name":"Photo Deleted"}]},"settings":"","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":53,"body":"","excerpt":"Update a photo's metadata. If you want to change the photo's file, you'll need to delete the photo and upload a new one.","slug":"update-photo-in-a-project","type":"patch","title":"Update Photo in a Project","__v":0,"childrenPages":[]}

patchUpdate Photo in a Project

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.

Path Params

project_uid:
required
string
Unique identifier of project.
photo_uid:
required
string
Unique identifier of photo.

Body Params

title:
string
New title of the photo.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
  "title": "Bongo Drums",
  "url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
  "created_at": "2013-05-17T02:30:22+00:00",
  "created_by": {
    "uid": null,
    "url": null,
    "email": "nick@subcontractor.com"
  },
  "deleted": false
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "Photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}
{
  "message": "Insufficient permissions to update photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) in project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Title (2) must be a string at least one character long."
}
{
  "message": "Photo (baa813cf-fd44-4a9c-be2b-62669958cc9a) is deleted and cannot be updated."
}


{"category":"58fe37462b628c0f0033a79d","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7ec","next":{"pages":[],"description":""},"createdAt":"2016-03-20T21:52:22.949Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"delete","results":{"codes":[{"name":"","code":"","language":"json","status":204},{"name":"Project Missing","code":"{\n  \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}","language":"json","status":404},{"name":"Photo Missing","status":404,"code":"{\n  \"message\": \"Photo (87658a3f-8ee0-4188-9c55-b06a203fa9e7) was not found in project (bafce976-8f33-437f-9c58-fb274456940f).\"\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":"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":54,"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":0,"childrenPages":[]}

deleteRemove Photo from Project

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.

Path Params

project_uid:
required
string
Unique identifier of project.
photo_uid:
required
string
Unique identifier of photo.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7d1","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,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":55,"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 attachments on RFI. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n    \"17-0\": \"**comments**\\n`object`\",\n    \"17-1\": \"Reference to collection of comments on RFI. See [Foreign Keys](doc:foreign-keys) for attribute details.\"\n  },\n  \"cols\": 2,\n  \"rows\": 18\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"uid\\\": \\\"22f3530a-a00b-42f9-8139-3a7554c77c27\\\",\\n  \\\"number\\\": 1,\\n  \\\"status\\\": {\\n    \\\"uid\\\": \\\"4898bfd4\\\",\\n    \\\"label\\\": \\\"closed\\\",\\n    \\\"color\\\": \\\"#000000\\\"\\n  },\\n  \\\"sent_at\\\": \\\"2015-10-20T19:22:56+00:00\\\",\\n  \\\"due_at\\\": \\\"2015-10-24T19:22:56+00:00\\\",\\n  \\\"locked\\\": true,\\n  \\\"title\\\": \\\"Door heights do not match.\\\",\\n  \\\"question\\\": \\\"Door heights on A1.01 and A2.02 do not match each other.\\\",\\n  \\\"answer\\\": \\\"Door height is 100' high.\\\",\\n  \\\"assigned_to\\\": [\\n    {\\n      \\\"uid\\\": \\\"80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n      \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",                \\n      \\\"email\\\": \\\"bob@subcontractor.com\\\"\\n    },\\n    {\\n      \\\"uid\\\": \\\"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\\\",\\n      \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\\\",\\n      \\\"email\\\": \\\"alfred@architect.com\\\"\\n    }\\n  ],\\n  \\\"created_at\\\": \\\"2015-06-08T18:04:02+00:00\\\",\\n  \\\"created_by\\\": {\\n    \\\"uid\\\": \\\"73ec5368-48aa-4dba-ba55-7e438a01b8d2\\\",\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2\\\",\\n    \\\"email\\\": \\\"betty@construction.com\\\"\\n  },\\n  \\\"updated_at\\\": \\\"2013-05-23T19:22:56+00:00\\\",\\n  \\\"updated_by\\\": {\\n    \\\"uid\\\": \\\"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\\\",\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\\\",\\n    \\\"email\\\": \\\"alfred@architect.com\\\"\\n  },\\n  \\\"photos\\\": {\\n    \\\"total_count\\\": 0,\\n    \\\"url\\\": null\\n  },\\n  \\\"attachments\\\": {\\n    \\\"total_count\\\": 4,\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/attachments\\\"\\n  },\\n  \\\"snapshots\\\": {\\n    \\\"total_count\\\": 2,\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots\\\"\\n  },\\n  \\\"comments\\\": {\\n    \\\"total_count\\\": 2,\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-rfi-object","type":"basic","title":"The RFI Object","__v":0,"childrenPages":[]}

The RFI Object


Attribute
Description

uid
string

Never blank. See Unique Identifiers for details.

number
integer

RFI number assigned by PlanGrid. May not be unique. Never blank.

status
object

An RFI status. See The RFI Status Object for attribute details. Never blank.

locked
boolean

Whether the RFI is locked. Never blank.

title
string

Cannot exceed 200 characters.

question
string

Cannot exceed 10,000 characters.

answer
string

Cannot exceed 10,000 characters.

assigned_to
array

An array of references to PlanGrid users RFI is assigned to. See Foreign Keys for attribute details.

sent_at
string

When the RFI was sent. UTC date and time in ISO-8601 format.

due_at
string

When the RFI is due. UTC date and time in ISO-8601 format.

created_at
string

When the RFI was created by a client application. UTC date and time in ISO-8601 format.

created_by
object

Reference to PlanGrid user that created RFI. See Foreign Keys for attribute details.

updated_at
string

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_by
object

Reference to PlanGrid user that last updated RFI. See Foreign Keys for attribute details.

photos
object

Reference to collection of photos on RFI. See Foreign Keys for attribute details.

snapshots
object

Reference to collection of snapshots on RFI. See Foreign Keys for attribute details.

attachments
object

Reference to collection of attachments on RFI. See Foreign Keys for attribute details.

comments
object

Reference to collection of comments on RFI. See Foreign Keys for attribute details.

{
  "uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
  "number": 1,
  "status": {
    "uid": "4898bfd4",
    "label": "closed",
    "color": "#000000"
  },
  "sent_at": "2015-10-20T19:22:56+00:00",
  "due_at": "2015-10-24T19:22:56+00:00",
  "locked": true,
  "title": "Door heights do not match.",
  "question": "Door heights on A1.01 and A2.02 do not match each other.",
  "answer": "Door height is 100' high.",
  "assigned_to": [
    {
      "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
      "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",                
      "email": "bob@subcontractor.com"
    },
    {
      "uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
      "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
      "email": "alfred@architect.com"
    }
  ],
  "created_at": "2015-06-08T18:04:02+00:00",
  "created_by": {
    "uid": "73ec5368-48aa-4dba-ba55-7e438a01b8d2",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2",
    "email": "betty@construction.com"
  },
  "updated_at": "2013-05-23T19:22:56+00:00",
  "updated_by": {
    "uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
    "email": "alfred@architect.com"
  },
  "photos": {
    "total_count": 0,
    "url": null
  },
  "attachments": {
    "total_count": 4,
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/attachments"
  },
  "snapshots": {
    "total_count": 2,
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots"
  },
  "comments": {
    "total_count": 2,
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments"
  }
}
{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7d2","next":{"pages":[],"description":""},"createdAt":"2016-02-02T01:49:35.778Z","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":56,"body":"[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"**field**\\n`string`\",\n    \"0-1\": \"Field that was updated. Adding a photo, attachment, or snapshot as a references results in a `field` value of `photos`, `attachments`, or `snapshots`, respectively.\",\n    \"1-0\": \"**old_value**\\n`string`, `array`, `object`, `null`\",\n    \"1-1\": \"The previous value before this update. When `status` is changed, `old_value` is a [RFI Status Object](doc:the-rfi-status-object). When `assigned_to` is changed, `old_value` is an array of UserPointers. When references are changed, `old_value` is an array of Pointers. See [Foreign Keys](doc:foreign-keys) for more on UserPointers and Pointers.\",\n    \"4-0\": \"**updated_by**\\n`object`\",\n    \"4-1\": \"Reference to PlanGrid user that made this update. See [Foreign Keys](doc:foreign-keys) for attribute details.\",\n    \"3-0\": \"**updated_at**\\n`string`\",\n    \"3-1\": \"When the RFI was updated by a PlanGrid client. UTC date and time in ISO-8601 format.\",\n    \"2-0\": \"**new_value**\\n`string`, `array`, `object`, `null`\",\n    \"2-1\": \"The new value after this update. When `status` is changed, `new_value` is a [RFI Status Object](doc:the-rfi-status-object). When `assigned_to` is changed, `new_value` is an array of UserPointers. When references are changed, `new_value` is an array of Pointers. See [Foreign Keys](doc:foreign-keys) for more on UserPointers and Pointers.\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"field\\\": \\\"assigned_to\\\",\\n  \\\"old_value\\\": [\\n    {\\n      \\\"uid\\\": \\\"80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n      \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n      \\\"email\\\": \\\"bob@subcontractor.com\\\"\\n    }\\n  ],\\n  \\\"new_value\\\": [\\n    {\\n      \\\"uid\\\": \\\"80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n      \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n      \\\"email\\\": \\\"bob@subcontractor.com\\\"\\n    },\\n    {\\n      \\\"uid\\\": \\\"80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n      \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n      \\\"email\\\": \\\"betty@construction.com\\\"\\n    }\\n  ],\\n  \\\"updated_at\\\": \\\"2013-05-11T05:25:11+00:00\\\",\\n  \\\"updated_by\\\": {\\n    \\\"uid\\\": \\\"80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n    \\\"url\\\": \\\"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\\\",\\n    \\\"email\\\": \\\"betty@construction.com\\\"\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-rfi-history-object","type":"basic","title":"The RFI History Object","__v":0,"childrenPages":[]}

The RFI History Object


Attribute
Description

field
string

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_value
string, 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_value
string, 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_at
string

When the RFI was updated by a PlanGrid client. UTC date and time in ISO-8601 format.

updated_by
object

Reference to PlanGrid user that made this update. See Foreign Keys for attribute details.

{
  "field": "assigned_to",
  "old_value": [
    {
      "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
      "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
      "email": "bob@subcontractor.com"
    }
  ],
  "new_value": [
    {
      "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
      "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
      "email": "bob@subcontractor.com"
    },
    {
      "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
      "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
      "email": "betty@construction.com"
    }
  ],
  "updated_at": "2013-05-11T05:25:11+00:00",
  "updated_by": {
    "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
    "email": "betty@construction.com"
  }
}
{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7d3","next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:38:33.841Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"post","results":{"codes":[{"name":"","code":"{\n  \"uid\": \"22f3530a-a00b-42f9-8139-3a7554c77c27\",\n  \"number\": 1,\n  \"status\": {\n    \"uid\": \"4898bfd4\",\n    \"label\": \"closed\",\n    \"color\": \"#000000\"\n  },\n  \"locked\": true,\n  \"title\": \"Door heights do not match.\",\n  \"question\": \"Door heights on A1.01 and A2.02 do not match each other.\",\n  \"answer\": \"Door height is 100' high.\",\n  \"sent_at\": \"2015-10-20T18:04:02+00:00\",\n  \"due_at\": \"2015-10-24T18:04:02+00:00\",\n  \"assigned_to\": [\n    {\n      \"uid\": \"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n      \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n      \"email\": \"alfred@architect.com\"\n    }\n  ],\n  \"updated_at\": \"2015-06-08T18:04:02+00:00\",\n  \"updated_by\": {\n    \"uid\": \"73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n    \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n    \"email\": \"betty@construction.com\"\n  },\n  \"created_at\": \"2015-06-08T18:04:02+00:00\",\n  \"created_by\": {\n    \"uid\": \"73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n    \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n    \"email\": \"betty@construction.com\"\n  },\n  \"photos\": {\n    \"total_count\": 0,\n    \"url\": null\n  },\n  \"attachments\": {\n    \"total_count\": 0,\n    \"url\": null\n  },\n  \"snapshots\": {\n    \"total_count\": 0,\n    \"url\": null\n  },\n  \"comments\": {\n    \"total_count\": 0,\n    \"url\": null\n  }\n}","language":"json","status":200},{"code":"{\n  \"message\": \"Status (4898bfd4) must be a valid RFI status on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","language":"json","status":400,"name":"Invalid Status"},{"code":"{\n  \"message\": \"Locked must be a boolean.\"\n}","language":"json","name":"Invalid Locked","status":400},{"code":"{\n  \"message\": \"Title (2) must be null or a string.\"\n}","language":"json","status":400,"name":"Invalid Title"},{"code":"{\n  \"message\": \"RFI title cannot exceed 200 characters.\"\n}","language":"json","status":400,"name":"Title Length"},{"name":"Invalid Question","code":"{\n  \"message\": \"Question (10) must be null or a string.\"\n}","language":"json","status":400},{"name":"Question Length","status":400,"code":"{\n  \"message\": \"RFI question cannot exceed 10000 characters.\"\n}","language":"json"},{"name":"Invalid Answer","code":"{\n  \"message\": \"Answer (3) must be null or a string.\"\n}","language":"json","status":400},{"name":"Answer Length","status":400,"code":"{\n  \"message\": \"RFI answer cannot exceed 10000 characters.\"\n}","language":"json"},{"name":"Invalid Sent At","code":"{\n  \"message\": \"Sent at (2015-9-2) must be null or a datetime in ISO-8601 format.\"\n}","language":"json","status":400},{"name":"Invalid Due At","status":400,"code":"{\n  \"message\": \"Due date (2015-9-2) must be null or a datetime in ISO-8601 format.\"\n}","language":"json"},{"name":"Invalid Assigned To","status":400,"language":"json","code":"{\n  \"message\": \"Assignees ([0, bb29c783-bfb7-4664-8362-ba2ca716cade]) must be an array of UIDs of users on project.\"\n}"},{"name":"Assignee Missing","code":"{\n  \"message\": \"Assignee (9003a891-8a49-4c91-9682-668b1a8a4241) is not on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","language":"json","status":400},{"status":403,"name":"No Access","language":"text","code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}"}]},"settings":"","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":57,"body":"","excerpt":"Creates an RFI on a project and sends appropriate notifications (e.g. to assignees). At least one field must be provided to successfully create an RFI.","slug":"create-rfi-in-a-project","type":"post","title":"Create RFI in a Project","__v":0,"childrenPages":[]}

postCreate RFI in a Project

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.

Path Params

project_uid:
required
string
Unique identifier of project.

Body Params

status:
string
Unique identifier of the RFI's initial status. Defaults to the first RFI status in the project.
locked:
booleanfalse
Whether the RFI is locked.
title:
stringnull
The RFI title.
question:
stringnull
The RFI question.
answer:
stringnull
The RFI answer.
sent_at:
datetimenull
Date when the RFI was sent. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.
due_at:
datetimenull
Date when the RFI is due. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.
assigned_to_uids:
array of stringsnull
Array of unique identifiers of users who are RFI assignees.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
  "number": 1,
  "status": {
    "uid": "4898bfd4",
    "label": "closed",
    "color": "#000000"
  },
  "locked": true,
  "title": "Door heights do not match.",
  "question": "Door heights on A1.01 and A2.02 do not match each other.",
  "answer": "Door height is 100' high.",
  "sent_at": "2015-10-20T18:04:02+00:00",
  "due_at": "2015-10-24T18:04:02+00:00",
  "assigned_to": [
    {
      "uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
      "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
      "email": "alfred@architect.com"
    }
  ],
  "updated_at": "2015-06-08T18:04:02+00:00",
  "updated_by": {
    "uid": "73ec5368-48aa-4dba-ba55-7e438a01b8d2",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2",
    "email": "betty@construction.com"
  },
  "created_at": "2015-06-08T18:04:02+00:00",
  "created_by": {
    "uid": "73ec5368-48aa-4dba-ba55-7e438a01b8d2",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2",
    "email": "betty@construction.com"
  },
  "photos": {
    "total_count": 0,
    "url": null
  },
  "attachments": {
    "total_count": 0,
    "url": null
  },
  "snapshots": {
    "total_count": 0,
    "url": null
  },
  "comments": {
    "total_count": 0,
    "url": null
  }
}
{
  "message": "Status (4898bfd4) must be a valid RFI status on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Locked must be a boolean."
}
{
  "message": "Title (2) must be null or a string."
}
{
  "message": "RFI title cannot exceed 200 characters."
}
{
  "message": "Question (10) must be null or a string."
}
{
  "message": "RFI question cannot exceed 10000 characters."
}
{
  "message": "Answer (3) must be null or a string."
}
{
  "message": "RFI answer cannot exceed 10000 characters."
}
{
  "message": "Sent at (2015-9-2) must be null or a datetime in ISO-8601 format."
}
{
  "message": "Due date (2015-9-2) must be null or a datetime in ISO-8601 format."
}
{
  "message": "Assignees ([0, bb29c783-bfb7-4664-8362-ba2ca716cade]) must be an array of UIDs of users on project."
}
{
  "message": "Assignee (9003a891-8a49-4c91-9682-668b1a8a4241) is not on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7d4","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","code":"{\n  \"data\": [\n    {\n      \"uid\": \"22f3530a-a00b-42f9-8139-3a7554c77c27\",\n      \"number\": 1,\n      \"status\": {\n        \"uid\": \"4898bfd4\",\n        \"label\": \"closed\",\n        \"color\": \"#000000\"\n      },\n      \"locked\": true,\n      \"title\": \"Door heights do not match.\",\n      \"question\": \"Door heights on A1.01 and A2.02 do not match each other.\",\n      \"answer\": \"Door height is 100' high.\",\n      \"sent_at\": \"2015-10-20T19:22:56+00:00\",\n      \"due_at\": \"2015-10-24T19:22:56+00:00\",\n      \"assigned_to\": [\n        {\n          \"uid\": \"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n          \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n          \"email\": \"alfred@architect.com\"\n        }\n      ],\n      \"updated_at\": \"2013-05-23T19:22:56+00:00\",\n      \"updated_by\": {\n        \"uid\": \"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n        \"email\": \"alfred@architect.com\"\n      },\n      \"created_at\": \"2015-06-08T18:04:02+00:00\",\n      \"created_by\": {\n        \"uid\": \"73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n        \"email\": \"betty@construction.com\"\n      },\n      \"photos\": {\n        \"total_count\": 0,\n        \"url\": null\n      },\n      \"attachments\": {\n        \"total_count\": 1,\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/attachments\"\n      },\n      \"snapshots\": {\n        \"total_count\": 1,\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots\"\n      },\n      \"comments\": {\n        \"total_count\": 2,\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments\"\n      }\n    },\n    {\n      \"uid\": \"51cb7310-6feb-47ae-8ad9-a89ac6101294\",\n      \"number\": 2,\n      \"status\": {\n        \"uid\": \"0a83939c\",\n        \"label\": \"open\",\n        \"color\": \"#FF0000\"\n      },\n      \"title\": \"Toilet won't fit\",\n      \"question\": \"Toilet will not fit with current dimensions of bathroom\",\n      \"answer\": null,\n      \"sent_at\": \"2015-9-12T19:22:56+00:00\",\n      \"due_at\": \"2015-9-14T19:22:56+00:00\",\n      \"assigned_to\": [\n        {\n          \"uid\": \"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n          \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n          \"email\": \"bob@subcontractor.com\"\n        },\n        {\n          \"uid\": \"e5eb1338-e8c0-4a1a-8191-bcc082a8bc96\",\n          \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/e5eb1338-e8c0-4a1a-8191-bcc082a8bc96\",\n          \"email\": \"stacy@civilengineer.com\"\n        }\n      ],\n      \"updated_at\": \"2013-05-23T19:22:56+00:00\",\n      \"updated_by\": {\n        \"uid\": \"e5eb1338-e8c0-4a1a-8191-bcc082a8bc96\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/e5eb1338-e8c0-4a1a-8191-bcc082a8bc96\",\n        \"email\": \"stacy@civilengineer.com\"\n      },\n      \"created_at\": \"2015-06-08T18:04:02+00:00\",\n      \"created_by\": {\n        \"uid\": \"73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n        \"email\": \"betty@construction.com\"\n      },\n      \"photos\": {\n        \"total_count\": 1,\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/photos\"\n      },\n      \"attachments\": {\n        \"total_count\": 0,\n        \"url\": null\n      },\n      \"snapshots\": {\n        \"total_count\": 1,\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots\"\n      },\n      \"comments\": {\n        \"total_count\": 2,\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments\"\n      }\n    }\n  ],\n  \"total_count\": 50,\n  \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis?skip=2&limit=2\"\n}\n","name":"Success","status":200},{"language":"json","code":"{\n  \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","name":"Missing","status":404},{"language":"json","code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","name":"No Access","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":58,"body":"","excerpt":"Get a list of RFIs in a project. Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-rfis-in-a-project","type":"get","title":"Retrieve RFIs in a Project","__v":0,"childrenPages":[]}

getRetrieve RFIs in a Project

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.

Path Params

project_uid:
required
string
Unique identifier of project.

Query Params

limit:
integer50
Number of RFIs to retrieve. Maximum value of 50.
skip:
integer0
Number of RFIs to skip in the set of results.
updated_after:
timestamp
Only retrieve RFIs created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
      "number": 1,
      "status": {
        "uid": "4898bfd4",
        "label": "closed",
        "color": "#000000"
      },
      "locked": true,
      "title": "Door heights do not match.",
      "question": "Door heights on A1.01 and A2.02 do not match each other.",
      "answer": "Door height is 100' high.",
      "sent_at": "2015-10-20T19:22:56+00:00",
      "due_at": "2015-10-24T19:22:56+00:00",
      "assigned_to": [
        {
          "uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
          "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
          "email": "alfred@architect.com"
        }
      ],
      "updated_at": "2013-05-23T19:22:56+00:00",
      "updated_by": {
        "uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
        "email": "alfred@architect.com"
      },
      "created_at": "2015-06-08T18:04:02+00:00",
      "created_by": {
        "uid": "73ec5368-48aa-4dba-ba55-7e438a01b8d2",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2",
        "email": "betty@construction.com"
      },
      "photos": {
        "total_count": 0,
        "url": null
      },
      "attachments": {
        "total_count": 1,
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/attachments"
      },
      "snapshots": {
        "total_count": 1,
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots"
      },
      "comments": {
        "total_count": 2,
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments"
      }
    },
    {
      "uid": "51cb7310-6feb-47ae-8ad9-a89ac6101294",
      "number": 2,
      "status": {
        "uid": "0a83939c",
        "label": "open",
        "color": "#FF0000"
      },
      "title": "Toilet won't fit",
      "question": "Toilet will not fit with current dimensions of bathroom",
      "answer": null,
      "sent_at": "2015-9-12T19:22:56+00:00",
      "due_at": "2015-9-14T19:22:56+00:00",
      "assigned_to": [
        {
          "uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
          "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
          "email": "bob@subcontractor.com"
        },
        {
          "uid": "e5eb1338-e8c0-4a1a-8191-bcc082a8bc96",
          "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/e5eb1338-e8c0-4a1a-8191-bcc082a8bc96",
          "email": "stacy@civilengineer.com"
        }
      ],
      "updated_at": "2013-05-23T19:22:56+00:00",
      "updated_by": {
        "uid": "e5eb1338-e8c0-4a1a-8191-bcc082a8bc96",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/e5eb1338-e8c0-4a1a-8191-bcc082a8bc96",
        "email": "stacy@civilengineer.com"
      },
      "created_at": "2015-06-08T18:04:02+00:00",
      "created_by": {
        "uid": "73ec5368-48aa-4dba-ba55-7e438a01b8d2",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2",
        "email": "betty@construction.com"
      },
      "photos": {
        "total_count": 1,
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/photos"
      },
      "attachments": {
        "total_count": 0,
        "url": null
      },
      "snapshots": {
        "total_count": 1,
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots"
      },
      "comments": {
        "total_count": 2,
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments"
      }
    }
  ],
  "total_count": 50,
  "next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis?skip=2&limit=2"
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7d5","next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:15:08.934Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"get","results":{"codes":[{"status":200,"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\": \"alfred@architect.com\"\n    }\n  ],\n  \"updated_at\": \"2013-05-23T19:22:56+00:00\",\n  \"updated_by\": {\n    \"uid\": \"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n    \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n    \"email\": \"alfred@architect.com\"\n  },\n  \"created_at\": \"2015-06-08T18:04:02+00:00\",\n  \"created_by\": {\n    \"uid\": \"73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n    \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n    \"email\": \"betty@construction.com\"\n  },\n  \"photos\": {\n    \"total_count\": 0,\n    \"url\": null\n  },\n  \"attachments\": {\n    \"total_count\": 1,\n    \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/attachments\"\n  },\n  \"snapshots\": {\n    \"total_count\": 1,\n    \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots\"\n  },\n  \"comments\": {\n    \"total_count\": 2,\n    \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments\"\n  }\n}\n","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"},{"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":"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":59,"body":"","excerpt":"Get an RFI in a project.","slug":"retrieve-rfi-in-a-project","type":"get","title":"Retrieve RFI in a Project","__v":0,"childrenPages":[]}

getRetrieve RFI in a Project

Get an RFI in a project.

Path Params

project_uid:
required
string
Unique identifier of project.
rfi_uid:
required
string
Unique identifier of RFI to retrieve.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
  "number": 1,
  "status": {
    "uid": "4898bfd4",
    "label": "closed",
    "color": "#000000"
  },
  "locked": true,
  "title": "Door heights do not match.",
  "question": "Door heights on A1.01 and A2.02 do not match each other.",
  "answer": "Door height is 100' high.",
  "sent_at": "2015-10-20T19:22:56+00:00",
  "due_at": "2015-10-24T19:22:56+00:00",
  "assigned_to": [
    {
      "uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
      "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
      "email": "alfred@architect.com"
    }
  ],
  "updated_at": "2013-05-23T19:22:56+00:00",
  "updated_by": {
    "uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
    "email": "alfred@architect.com"
  },
  "created_at": "2015-06-08T18:04:02+00:00",
  "created_by": {
    "uid": "73ec5368-48aa-4dba-ba55-7e438a01b8d2",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2",
    "email": "betty@construction.com"
  },
  "photos": {
    "total_count": 0,
    "url": null
  },
  "attachments": {
    "total_count": 1,
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/attachments"
  },
  "snapshots": {
    "total_count": 1,
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/snapshots"
  },
  "comments": {
    "total_count": 2,
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/22f3530a-a00b-42f9-8139-3a7554c77c27/comments"
  }
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7d6","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":[{"language":"json","code":"{\n  \"data\": [\n    {\n      \"uid\": \"147a420e-a182-4312-8fa5-4d10064d2f1a\",\n      \"name\": \"Bender\",\n      \"folder\": \"Specifications\",\n      \"url\": \"https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf\",\n      \"created_at\": \"2013-05-17T02:30:22+00:00\",\n      \"created_by\": {\n        \"uid\": null,\n        \"url\": null,\n        \"email\": \"nick@subcontractor.com\"\n      },\n      \"deleted\": false\n    },\n    {\n      \"uid\": \"40f38b8b-019e-44d8-8cb8-86454c327fb5\",\n      \"name\": \"Cement\",\n      \"folder\": \"Submittals\",\n      \"url\": \"https://attachment-assets.plangrid.com/40f38b8b-019e-44d8-8cb8-86454c327fb5.pdf\",\n      \"created_at\": \"2013-05-13T04:30:22+00:00\",\n      \"created_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"betty@construction.com\"\n      },\n      \"deleted\": true\n    }\n  ],\n  \"total_count\": 14,\n  \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/attachments?skip=2&limit=2\"\n}\n","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\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"RFI Missing","status":404},{"language":"json","code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}\n","name":"No Project Access","status":403}]},"settings":"","auth":"required","params":[{"_id":"56cf1ece5267d70b00494bc1","ref":"","in":"path","required":true,"desc":"Unique identifier for RFI's project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ece5267d70b00494bc0","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI.","default":"","type":"string","name":"rfi_uid"},{"_id":"56cf1ece5267d70b00494bbf","ref":"","in":"query","required":false,"desc":"Number of attachments to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ece5267d70b00494bbe","ref":"","in":"query","required":false,"desc":"Number of attachments to skip in the set of results.","default":"0","type":"int","name":"skip"}],"url":"/projects/:project_uid/rfis/:rfi_uid/attachments"},"isReference":false,"order":60,"body":"","excerpt":"Get a list of attachments referenced in an RFI. Attachment data is described in [The Attachment 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 Attachments Referenced in RFI","__v":0,"childrenPages":[]}

getRetrieve Attachments Referenced in RFI

Get a list of attachments referenced in an RFI. Attachment data is described in [The Attachment Object](doc:the-attachment-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.

Path Params

project_uid:
required
string
Unique identifier for RFI's project.
rfi_uid:
required
string
Unique identifier of RFI.

Query Params

limit:
integer50
Number of attachments to retrieve. Maximum value of 50.
skip:
integer0
Number of attachments to skip in the set of results.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "uid": "147a420e-a182-4312-8fa5-4d10064d2f1a",
      "name": "Bender",
      "folder": "Specifications",
      "url": "https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf",
      "created_at": "2013-05-17T02:30:22+00:00",
      "created_by": {
        "uid": null,
        "url": null,
        "email": "nick@subcontractor.com"
      },
      "deleted": false
    },
    {
      "uid": "40f38b8b-019e-44d8-8cb8-86454c327fb5",
      "name": "Cement",
      "folder": "Submittals",
      "url": "https://attachment-assets.plangrid.com/40f38b8b-019e-44d8-8cb8-86454c327fb5.pdf",
      "created_at": "2013-05-13T04:30:22+00:00",
      "created_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "betty@construction.com"
      },
      "deleted": true
    }
  ],
  "total_count": 14,
  "next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/attachments?skip=2&limit=2"
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7d7","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":[{"language":"json","code":"{\n  \"data\": [\n    {\n      \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n      \"title\": \"Bongo Drums\",\n      \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n      \"created_at\": \"2013-05-17T02:30:22+00:00\",\n      \"created_by\": {\n        \"uid\": null,\n        \"url\": null,\n        \"email\": \"nick@subcontractor.com\"\n      },\n      \"deleted\": false\n    },\n    {\n      \"uid\": \"9acc66f0-b704-4469-99fa-c13ce2b0bf0a\",\n      \"title\": \"Bass Guitar\",\n      \"url\": \"https://photo-assets.plangrid.com/9acc66f0-b704-4469-99fa-c13ce2b0bf0a.jpg\",\n      \"created_at\": \"2013-05-13T04:30:22+00:00\",\n      \"created_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"betty@construction.com\"\n      },\n      \"deleted\": false\n    }\n  ],\n  \"total_count\": 14,\n  \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos?skip=2&limit=2\"\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\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"RFI Missing","status":404},{"language":"json","code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}\n","name":"No Project Access","status":403}]},"settings":"","auth":"required","params":[{"_id":"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":61,"body":"","excerpt":"Get a list of photos referenced in an RFI. Photo data is described in [The Photo Object](doc:the-photo-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-photos-referenced-in-rfi","type":"get","title":"Retrieve Photos Referenced in RFI","__v":0,"childrenPages":[]}

getRetrieve Photos Referenced in RFI

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.

Path Params

project_uid:
required
string
Unique identifier for RFI's project.
rfi_uid:
required
string
Unique identifier of RFI.

Query Params

limit:
integer50
Number of photos to retrieve. Maximum value of 50.
skip:
integer0
Number of photos to skip in the set of results.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
      "title": "Bongo Drums",
      "url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
      "created_at": "2013-05-17T02:30:22+00:00",
      "created_by": {
        "uid": null,
        "url": null,
        "email": "nick@subcontractor.com"
      },
      "deleted": false
    },
    {
      "uid": "9acc66f0-b704-4469-99fa-c13ce2b0bf0a",
      "title": "Bass Guitar",
      "url": "https://photo-assets.plangrid.com/9acc66f0-b704-4469-99fa-c13ce2b0bf0a.jpg",
      "created_at": "2013-05-13T04:30:22+00:00",
      "created_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "betty@construction.com"
      },
      "deleted": false
    }
  ],
  "total_count": 14,
  "next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/photos?skip=2&limit=2"
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7d8","next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:21:32.510Z","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\": \"ee131be1-c1b1-4b81-93f6-6363516186f3\",\n      \"title\": \"Area where toilet doesn't fit\",\n      \"url\": \"https://snapshot-assets.plangrid.com/ee131be1-c1b1-4b81-93f6-6363516186f3.jpg\",\n      \"created_at\": \"2013-05-17T02:30:22+00:00\",\n      \"created_by\": {\n        \"uid\": null,\n        \"url\": null,\n        \"email\": \"nick@subcontractor.com\"\n      },\n      \"deleted\": false\n    },\n    {\n      \"uid\": \"154f1ab0-0b31-4854-87d9-dbb772f5f388\",\n      \"title\": \"Another area where toilet doesn't fit\",\n      \"url\": \"https://snapshot-assets.plangrid.com/154f1ab0-0b31-4854-87d9-dbb772f5f388.jpg\",\n      \"created_at\": \"2013-05-13T04:30:22+00:00\",\n      \"created_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"betty@construction.com\"\n      },\n      \"deleted\": true\n    }\n  ],\n  \"total_count\": 14,\n  \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/snapshots?skip=2&limit=2\"\n}\n","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"},{"status":403,"name":"No Project Access","code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}\n","language":"json"}]},"settings":"","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":62,"body":"","excerpt":"Get a list of snapshots referenced in an RFI. Snapshot data is described in [The Snapshot Object](doc:the-snapshot-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-snapshots-referenced-in-rfi","type":"get","title":"Retrieve Snapshots Referenced in RFI","__v":0,"childrenPages":[]}

getRetrieve Snapshots Referenced in RFI

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.

Path Params

project_uid:
required
string
Unique identifier for RFI's project.
rfi_uid:
required
string
Unique identifier of RFI.

Query Params

limit:
integer50
Number of snapshots to retrieve. Maximum value of 50.
skip:
integer0
Number of snapshots to skip in the set of results.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "uid": "ee131be1-c1b1-4b81-93f6-6363516186f3",
      "title": "Area where toilet doesn't fit",
      "url": "https://snapshot-assets.plangrid.com/ee131be1-c1b1-4b81-93f6-6363516186f3.jpg",
      "created_at": "2013-05-17T02:30:22+00:00",
      "created_by": {
        "uid": null,
        "url": null,
        "email": "nick@subcontractor.com"
      },
      "deleted": false
    },
    {
      "uid": "154f1ab0-0b31-4854-87d9-dbb772f5f388",
      "title": "Another area where toilet doesn't fit",
      "url": "https://snapshot-assets.plangrid.com/154f1ab0-0b31-4854-87d9-dbb772f5f388.jpg",
      "created_at": "2013-05-13T04:30:22+00:00",
      "created_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "betty@construction.com"
      },
      "deleted": true
    }
  ],
  "total_count": 14,
  "next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/snapshots?skip=2&limit=2"
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7d9","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":[{"language":"json","code":"{\n  \"data\": [\n    {\n      \"uid\": \"87658a3f-8ee0-4188-9c55-b06a203fa9e7\",\n      \"text\": \"Those people are trying to kill us!\",\n      \"created_at\": \"2013-05-17T02:30:22+00:00\",\n      \"created_by\": {\n        \"uid\": \"deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n        \"email\": \"henry.jones@oxford.edu\"\n      },\n      \"record_type\": \"rfi\",\n      \"record\": {\n        \"uid\": \"c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\"\n      }\n    },\n    {\n      \"uid\": \"465abf98-accb-42cd-bd54-16f29e8447f2\",\n      \"text\": \"I know, Dad!\",\n      \"created_at\": \"2013-05-15T18:54:22+00:00\",\n      \"created_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"indiana.jones@marshallcollege.edu\"\n      },\n      \"record_type\": \"rfi\",\n      \"record\": {\n        \"uid\": \"c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\"\n      }\n    },\n    {\n      \"uid\": \"08ea8b05-a99c-40a7-a312-fee360ad432a\",\n      \"text\": \"This is a new experience for me.\",\n      \"created_at\": \"2013-05-14T8:30:56+00:00\",\n      \"created_by\": {\n        \"uid\": \"deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0\",\n        \"email\": \"henry.jones@oxford.edu\"\n      },\n      \"record_type\": \"rfi\",\n      \"record\": {\n        \"uid\": \"c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\"\n      }\n    },\n    {\n      \"uid\": \"68839690-e0aa-4751-aedf-e630b921e91e\",\n      \"text\": \"It happens to me all the time.\",\n      \"created_at\": \"2013-05-13T11:22:56+00:00\",\n      \"created_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"indiana.jones@marshallcollege.edu\"\n      },\n      \"record_type\": \"rfi\",\n      \"record\": {\n        \"uid\": \"c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b\"\n      }\n    }\n  ],\n  \"total_count\": 6,\n  \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments?skip=4&limit=4\"\n}\n","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\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"RFI Missing","status":404},{"language":"json","code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}\n","name":"No Access","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"},{"_id":"56edc3235babe30e009bd838","ref":"","in":"query","required":false,"desc":"Only retrieve comments created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.","default":"","type":"datetime","name":"updated_after"}],"url":"/projects/:project_uid/rfis/:rfi_uid/comments"},"isReference":false,"order":63,"body":"","excerpt":"Get a list of comments on an RFI. Comment data is described in [The Comment Object](doc:the-comment-object). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-comments-on-an-rfi","type":"get","title":"Retrieve Comments on an RFI","__v":0,"childrenPages":[]}

getRetrieve Comments on an RFI

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.

Path Params

project_uid:
required
string
Unique identifier for RFI's project.
rfi_uid:
required
string
Unique identifier of RFI.

Query Params

limit:
integer50
Number of comments to retrieve. Maximum value of 50.
skip:
integer0
Number of comments to skip in the set of results.
updated_after:
datetime
Only retrieve comments created/updated after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "uid": "87658a3f-8ee0-4188-9c55-b06a203fa9e7",
      "text": "Those people are trying to kill us!",
      "created_at": "2013-05-17T02:30:22+00:00",
      "created_by": {
        "uid": "deae0b56-81c7-4a05-8e8b-410fd17a01f0",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0",
        "email": "henry.jones@oxford.edu"
      },
      "record_type": "rfi",
      "record": {
        "uid": "c62d6a09-1e7c-4aa0-b60b-86249eba7e5b",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b"
      }
    },
    {
      "uid": "465abf98-accb-42cd-bd54-16f29e8447f2",
      "text": "I know, Dad!",
      "created_at": "2013-05-15T18:54:22+00:00",
      "created_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "indiana.jones@marshallcollege.edu"
      },
      "record_type": "rfi",
      "record": {
        "uid": "c62d6a09-1e7c-4aa0-b60b-86249eba7e5b",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b"
      }
    },
    {
      "uid": "08ea8b05-a99c-40a7-a312-fee360ad432a",
      "text": "This is a new experience for me.",
      "created_at": "2013-05-14T8:30:56+00:00",
      "created_by": {
        "uid": "deae0b56-81c7-4a05-8e8b-410fd17a01f0",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/deae0b56-81c7-4a05-8e8b-410fd17a01f0",
        "email": "henry.jones@oxford.edu"
      },
      "record_type": "rfi",
      "record": {
        "uid": "c62d6a09-1e7c-4aa0-b60b-86249eba7e5b",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b"
      }
    },
    {
      "uid": "68839690-e0aa-4751-aedf-e630b921e91e",
      "text": "It happens to me all the time.",
      "created_at": "2013-05-13T11:22:56+00:00",
      "created_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "indiana.jones@marshallcollege.edu"
      },
      "record_type": "rfi",
      "record": {
        "uid": "c62d6a09-1e7c-4aa0-b60b-86249eba7e5b",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/c62d6a09-1e7c-4aa0-b60b-86249eba7e5b"
      }
    }
  ],
  "total_count": 6,
  "next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/comments?skip=4&limit=4"
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7da","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":[{"language":"json","code":"{\n  \"data\": [\n    {\n      \"field\": \"title\",\n      \"old_value\": \"Toilet does fit\",\n      \"new_value\": \"Toilet doesn't fit\",\n      \"updated_at\": \"2013-05-13T04:30:22+00:00\",\n      \"updated_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"betty@construction.com\"\n      }\n    },\n    {\n      \"field\": \"assigned_to\",\n      \"old_value\": [\n        {\n          \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n          \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n          \"email\": \"bob@subcontractor.com\"\n        }\n      ],\n      \"new_value\": [\n        {\n          \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n          \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n          \"email\": \"bob@subcontractor.com\"\n        },\n        {\n          \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n          \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n          \"email\": \"betty@construction.com\"\n        }\n      ],\n      \"updated_at\": \"2013-05-11T05:25:11+00:00\",\n      \"updated_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"betty@construction.com\"\n      }\n    },\n    {\n      \"field\": \"photos\",\n      \"old_value\": [],\n      \"new_value\": [\n        {\n          \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n          \"title\": \"Bongo Drums\",\n          \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n          \"created_at\": \"2013-05-17T02:30:22+00:00\",\n          \"created_by\": {\n            \"uid\": null,\n            \"url\": null,\n            \"email\": \"nick@subcontractor.com\"\n          },\n          \"deleted\": false\n        }\n      ],\n      \"updated_at\": \"2013-04-11T02:18:53+00:00\",\n      \"updated_by\": {\n        \"uid\": \"80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52\",\n        \"email\": \"betty@construction.com\"\n      },\n    },\n  ],\n  \"total_count\": 14,\n  \"next_page_url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/history?skip=2&limit=2\"\n}\n","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\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"RFI Missing","status":404},{"language":"json","code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}\n","name":"No Project Access","status":403}]},"settings":"","auth":"required","params":[{"_id":"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":64,"body":"","excerpt":"Get the change history of an RFI (includes references). Results are paginated, see [Pagination](doc:pagination) for details on how pagination works in PlanGrid's API.","slug":"retrieve-rfi-history","type":"get","title":"Retrieve RFI History","__v":0,"childrenPages":[]}

getRetrieve RFI History

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.

Path Params

project_uid:
required
string
Unique identifier for RFI's project.
rfi_uid:
required
string
Unique identifier of RFI.

Query Params

limit:
integer50
Number of history items to retrieve. Maximum value of 50.
skip:
integer0
Number of history to skip in the set of results.
updated_after:
string
Only retrieve RFI history created after specified UTC date and time. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "field": "title",
      "old_value": "Toilet does fit",
      "new_value": "Toilet doesn't fit",
      "updated_at": "2013-05-13T04:30:22+00:00",
      "updated_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "betty@construction.com"
      }
    },
    {
      "field": "assigned_to",
      "old_value": [
        {
          "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
          "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
          "email": "bob@subcontractor.com"
        }
      ],
      "new_value": [
        {
          "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
          "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
          "email": "bob@subcontractor.com"
        },
        {
          "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
          "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
          "email": "betty@construction.com"
        }
      ],
      "updated_at": "2013-05-11T05:25:11+00:00",
      "updated_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "betty@construction.com"
      }
    },
    {
      "field": "photos",
      "old_value": [],
      "new_value": [
        {
          "uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
          "title": "Bongo Drums",
          "url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
          "created_at": "2013-05-17T02:30:22+00:00",
          "created_by": {
            "uid": null,
            "url": null,
            "email": "nick@subcontractor.com"
          },
          "deleted": false
        }
      ],
      "updated_at": "2013-04-11T02:18:53+00:00",
      "updated_by": {
        "uid": "80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/80efb7e6-f15c-479a-8429-7e153b1e2a52",
        "email": "betty@construction.com"
      },
    },
  ],
  "total_count": 14,
  "next_page_url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/rfis/51cb7310-6feb-47ae-8ad9-a89ac6101294/history?skip=2&limit=2"
}
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
{
  "message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited."
}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7db","next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:33:29.568Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"patch","results":{"codes":[{"language":"json","code":"{\n  \"uid\": \"22f3530a-a00b-42f9-8139-3a7554c77c27\",\n  \"number\": 1,\n  \"status\": {\n    \"uid\": \"4898bfd4\",\n    \"label\": \"closed\",\n    \"color\": \"#000000\"\n  },\n  \"locked\": true,\n  \"title\": \"Door heights do not match.\",\n  \"question\": \"Door heights on A1.01 and A2.02 do not match each other.\",\n  \"answer\": \"Door height is 100' high.\",\n  \"sent_at\": \"2015-10-20T19:22:56+00:00\",\n  \"due_at\": \"2015-10-24T19:22:56+00:00\",\n  \"assigned_to\": [\n    {\n      \"uid\": \"d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n      \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b\",\n      \"email\": \"alfred@architect.com\"\n    }\n  ],\n  \"updated_at\": \"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\": \"betty@construction.com\"\n  },\n  \"created_at\": \"2015-06-08T18:04:02+00:00\",\n  \"created_by\": {\n    \"uid\": \"73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n    \"url\": \"https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2\",\n    \"email\": \"betty@construction.com\"\n  },\n  \"photos\": {\n    \"total_count\": 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","name":"Success","status":200},{"language":"json","code":"{\n  \"message\": \"Status (4898bfd4) must be a valid RFI status on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"Invalid Status","status":400},{"language":"json","code":"{\n  \"message\": \"Locked must be a boolean.\"\n}\n","name":"Invalid Locked","status":400},{"language":"json","code":"{\n  \"message\": \"Title (2) must be null or a string.\"\n}\n","name":"Invalid Title","status":400},{"language":"json","code":"{\n  \"message\": \"RFI title cannot exceed 200 characters.\"\n}\n","name":"Title Length","status":400},{"language":"json","code":"{\n  \"message\": \"Question (10) must be null or a string.\"\n}\n","name":"Invalid Question","status":400},{"language":"json","code":"{\n  \"message\": \"RFI question cannot exceed 10000 characters.\"\n}\n","name":"Question Length","status":400},{"language":"json","code":"{\n  \"message\": \"Answer (3) must be null or a string.\"\n}\n","name":"Invalid Answer","status":400},{"language":"json","code":"{\n  \"message\": \"RFI answer cannot exceed 10000 characters.\"\n}\n","name":"Answer Length","status":400},{"language":"json","code":"{\n  \"message\": \"Sent date (2015-9-2) must be null or a datetime in ISO-8601 format.\"\n}\n","name":"Invalid Sent At","status":400},{"language":"json","code":"{\n  \"message\": \"Due date (2015-9-2) must be null or a datetime in ISO-8601 format.\"\n}\n","name":"Invalid Due At","status":400},{"language":"json","code":"{\n  \"message\": \"Assignees ([0, bb29c783-bfb7-4664-8362-ba2ca716cade]) must be an array of UIDs of users on project.\"\n}\n","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}\n","name":"Assignee Missing","status":400},{"language":"json","code":"{\n  \"message\": \"RFI (22f3530a-a00b-42f9-8139-3a7554c77c27) must be unlocked before it can be updated.\"\n}\n","name":"RFI Locked","status":400},{"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\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"RFI Missing","status":404},{"language":"json","code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","name":"No Access","status":403}]},"settings":"","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":65,"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,"childrenPages":[]}

patchUpdate RFI in a Project

Updates an RFI on a project and sends appropriate notifications (e.g. to new assignees).

Path Params

project_uid:
required
string
Unique identifier of project.
rfi_uid:
required
string
Unique identifier of RFI to update.

Body Params

status:
string
Unique identifier of the RFI's new status.
locked:
boolean
Whether the RFI is locked.
title:
string
The RFI title.
question:
string
The RFI question.
answer:
string
The RFI answer.
sent_at:
datetime
Date when the RFI was sent. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.
due_at:
datetime
Date when the RFI is due. See [Timestamps and Timezones](doc:timestamps-and-timezones) for accepted date formats.
assigned_to_uids:
array of strings
Array of unique identifiers of users who are RFI assignees and replaces the current list of assignees.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "uid": "22f3530a-a00b-42f9-8139-3a7554c77c27",
  "number": 1,
  "status": {
    "uid": "4898bfd4",
    "label": "closed",
    "color": "#000000"
  },
  "locked": true,
  "title": "Door heights do not match.",
  "question": "Door heights on A1.01 and A2.02 do not match each other.",
  "answer": "Door height is 100' high.",
  "sent_at": "2015-10-20T19:22:56+00:00",
  "due_at": "2015-10-24T19:22:56+00:00",
  "assigned_to": [
    {
      "uid": "d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
      "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/d4c0bab2-cd1c-4c9d-b4b3-022a5a52cc7b",
      "email": "alfred@architect.com"
    }
  ],
  "updated_at": "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": "betty@construction.com"
  },
  "created_at": "2015-06-08T18:04:02+00:00",
  "created_by": {
    "uid": "73ec5368-48aa-4dba-ba55-7e438a01b8d2",
    "url": "https://io.plangrid.com/projects/bafce976-8f33-437f-9c52-fb274456940f/users/73ec5368-48aa-4dba-ba55-7e438a01b8d2",
    "email": "betty@construction.com"
  },
  "photos": {
    "total_count": 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."
}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7dc","next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:45:40.207Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"post","results":{"codes":[{"language":"json","code":"{\n  \"uid\": \"147a420e-a182-4312-8fa5-4d10064d2f1a\",\n  \"name\": \"Bender\",\n  \"folder\": \"Specifications\",\n  \"url\": \"https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf\",\n  \"created_at\": \"2013-05-17T02:30:22+00:00\",\n  \"created_by\": {\n    \"uid\": null,\n    \"url\": null,\n    \"email\": \"nick@subcontractor.com\"\n  },\n  \"deleted\": false\n}\n","name":"Success","status":200},{"language":"json","code":"{\n  \"message\": \"Attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) was not found in project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"Attachment Missing","status":400},{"language":"json","code":"{\n  \"message\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) must be unlocked before attachments can be added.\"\n}\n","name":"RFI Locked","status":400},{"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\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","name":"RFI Missing","status":404},{"language":"json","code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","name":"No Access","status":403}]},"settings":"","auth":"required","params":[{"_id":"56cf1ecc5267d70b00494bb8","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ecc5267d70b00494bb7","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI.","default":"","type":"string","name":"rfi_uid"},{"_id":"56cf1ecc5267d70b00494bb6","ref":"","in":"body","required":true,"desc":"Unique identifier of attachment to reference.","default":"","type":"string","name":"attachment_uid"}],"url":"/projects/:project_uid/rfis/:rfi_uid/attachments"},"isReference":false,"order":66,"body":"","excerpt":"Creates a reference to an attachment on an RFI. On success, returns the attachment. Attachment data is described in [The Attachment Object](doc:the-attachment-object).","slug":"reference-attachment-in-rfi","type":"post","title":"Reference Attachment in RFI","__v":0,"childrenPages":[]}

postReference Attachment in RFI

Creates a reference to an attachment on an RFI. On success, returns the attachment. Attachment data is described in [The Attachment Object](doc:the-attachment-object).

Path Params

project_uid:
required
string
Unique identifier of project.
rfi_uid:
required
string
Unique identifier of RFI.

Body Params

attachment_uid:
required
string
Unique identifier of attachment to reference.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "uid": "147a420e-a182-4312-8fa5-4d10064d2f1a",
  "name": "Bender",
  "folder": "Specifications",
  "url": "https://attachment-assets.plangrid.com/147a420e-a182-4312-8fa5-4d10064d2f1a.pdf",
  "created_at": "2013-05-17T02:30:22+00:00",
  "created_by": {
    "uid": null,
    "url": null,
    "email": "nick@subcontractor.com"
  },
  "deleted": false
}
{
  "message": "Attachment (147a420e-a182-4312-8fa5-4d10064d2f1a) was not found in project (bafce976-8f33-437f-9c58-fb274456940f)."
}
{
  "message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) must be unlocked before attachments can be added."
}
{
  "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."
}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7dd","next":{"pages":[],"description":""},"createdAt":"2016-03-20T21:37:04.044Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"delete","results":{"codes":[{"name":"","code":"","language":"json","status":204},{"name":"RFI Locked","code":"{\n  \"message\": \"RFI (d796e4d0-4639-406c-9b15-68d398dc6458) must be unlocked before it can be updated.\"\n}","language":"json","status":400},{"code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}","language":"json","status":404,"name":"No Project Access"},{"name":"RFI Missing","code":"{\n  \"message\": \"RFI (d796e4d0-4639-406c-9b15-68d398dc6458) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","language":"json","status":404},{"name":"Project Missing","status":404,"language":"json","code":"{\n  \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}"},{"code":"{\n  \"message\": \"Attachment (130dc467-27bf-4642-9684-0bb4cae82afa) is not referenced on RFI (d796e4d0-4639-406c-9b15-68d398dc6458).\"\n}","language":"json","name":"Attachment Not Referenced","status":404}]},"settings":"","auth":"required","params":[{"_id":"56ef1684a5bcfd0e0095175c","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56ef1684a5bcfd0e0095175b","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI.","default":"","type":"string","name":"rfi_uid"},{"_id":"56ef1684a5bcfd0e0095175a","ref":"","in":"path","required":true,"desc":"Unique identifier of referenced attachment.","default":"","type":"string","name":"attachment_uid"}],"url":"/projects/:project_uid/rfis/:rfi_uid/attachments/:attachment_uid"},"isReference":false,"order":67,"body":"","excerpt":"Remove a reference to an attachment in an RFI. The attachment is not deleted from the project.","slug":"remove-attachment-reference-in-rfi","type":"delete","title":"Remove Attachment Reference in RFI","__v":0,"childrenPages":[]}

deleteRemove Attachment Reference in RFI

Remove a reference to an attachment in an RFI. The attachment is not deleted from the project.

Path Params

project_uid:
required
string
Unique identifier of project.
rfi_uid:
required
string
Unique identifier of RFI.
attachment_uid:
required
string
Unique identifier of referenced attachment.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7de","next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:46:02.581Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"post","results":{"codes":[{"status":200,"name":"Success","code":"{\n  \"uid\": \"baa813cf-fd44-4a9c-be2b-62669958cc9a\",\n  \"title\": \"Bongo Drums\",\n  \"url\": \"https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg\",\n  \"created_at\": \"2013-05-17T02:30:22+00:00\",\n  \"created_by\": {\n    \"uid\": null,\n    \"url\": null,\n    \"email\": \"nick@subcontractor.com\"\n  },\n  \"deleted\": false\n}\n","language":"json"},{"status":"4XX","name":"Photo Missing","code":"HTTP/1.1 400 Bad Request\n{\n  \"message\": \"Photo (147a420e-a182-4312-8fa5-4d10064d2f1a) was not found in project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","language":"json"},{"status":"4XX","name":"RFI Locked","code":"HTTP/1.1 400 Bad Request\n{\n  \"message\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) must be unlocked before attachments can be added.\"\n}\n","language":"json"},{"status":"4XX","name":"Project Missing","code":"HTTP/1.1 404 Not Found\n{\n  \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","language":"json"},{"status":"4XX","name":"RFI Missing","code":"HTTP/1.1 404 Not Found\n{\n  \"message\": \"RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","language":"json"},{"status":"4XX","name":"No Access","code":"HTTP/1.1 403 Forbidden\n{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","language":"json"}]},"settings":"","auth":"required","params":[{"_id":"56cf1ecd5267d70b00494bbb","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ecd5267d70b00494bba","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI.","default":"","type":"string","name":"rfi_uid"},{"_id":"56cf1ecd5267d70b00494bb9","ref":"","in":"body","required":true,"desc":"Unique identifier of photo to reference.","default":"","type":"string","name":"photo_uid"}],"url":"/projects/:project_uid/rfis/:rfi_uid/photos"},"isReference":false,"order":68,"body":"","excerpt":"Creates a reference to a photo on an RFI. On success, returns the photo. Photo data is described in [The Photo Object](doc:the-photo-object).","slug":"reference-photo-in-rfi","type":"post","title":"Reference Photo in RFI","__v":0,"childrenPages":[]}

postReference Photo in RFI

Creates a reference to a photo on an RFI. On success, returns the photo. Photo data is described in [The Photo Object](doc:the-photo-object).

Path Params

project_uid:
required
string
Unique identifier of project.
rfi_uid:
required
string
Unique identifier of RFI.

Body Params

photo_uid:
required
string
Unique identifier of photo to reference.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "uid": "baa813cf-fd44-4a9c-be2b-62669958cc9a",
  "title": "Bongo Drums",
  "url": "https://photo-assets.plangrid.com/baa813cf-fd44-4a9c-be2b-62669958cc9a.jpg",
  "created_at": "2013-05-17T02:30:22+00:00",
  "created_by": {
    "uid": null,
    "url": null,
    "email": "nick@subcontractor.com"
  },
  "deleted": false
}
HTTP/1.1 400 Bad Request
{
  "message": "Photo (147a420e-a182-4312-8fa5-4d10064d2f1a) was not found in project (bafce976-8f33-437f-9c58-fb274456940f)."
}
HTTP/1.1 400 Bad Request
{
  "message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) must be unlocked before attachments can be added."
}
HTTP/1.1 404 Not Found
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
HTTP/1.1 404 Not Found
{
  "message": "RFI (87658a3f-8ee0-4188-9c55-b06a203fa9e7) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f)."
}
HTTP/1.1 403 Forbidden
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7df","next":{"pages":[],"description":""},"createdAt":"2016-03-20T21:25:30.034Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"delete","results":{"codes":[{"name":"","code":"","language":"json","status":204},{"name":"RFI Locked","code":"{\n  \"message\": \"RFI (d796e4d0-4639-406c-9b15-68d398dc6458) must be unlocked before it can be updated.\"\n}","language":"json","status":400},{"code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}","language":"json","status":404,"name":"No Project Access"},{"name":"RFI Missing","code":"{\n  \"message\": \"RFI (d796e4d0-4639-406c-9b15-68d398dc6458) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","language":"json","status":404},{"name":"Project Missing","status":404,"language":"json","code":"{\n  \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}"},{"code":"{\n  \"message\": \"Photo (130dc467-27bf-4642-9684-0bb4cae82afa) is not referenced on RFI (d796e4d0-4639-406c-9b15-68d398dc6458).\"\n}","language":"json","name":"Photo Not Referenced","status":404}]},"settings":"","auth":"required","params":[{"_id":"56ef1684a5bcfd0e0095175c","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56ef1684a5bcfd0e0095175b","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI.","default":"","type":"string","name":"rfi_uid"},{"_id":"56ef1684a5bcfd0e0095175a","ref":"","in":"path","required":true,"desc":"Unique identifier of referenced photo.","default":"","type":"string","name":"photo_uid"}],"url":"/projects/:project_uid/rfis/:rfi_uid/photos/:photo_uid"},"isReference":false,"order":69,"body":"","excerpt":"Remove a reference to a photo in an RFI. The photo is not deleted from the project.","slug":"remove-photo-reference-in-rfi","type":"delete","title":"Remove Photo Reference in RFI","__v":0,"childrenPages":[]}

deleteRemove Photo Reference in RFI

Remove a reference to a photo in an RFI. The photo is not deleted from the project.

Path Params

project_uid:
required
string
Unique identifier of project.
rfi_uid:
required
string
Unique identifier of RFI.
photo_uid:
required
string
Unique identifier of referenced photo.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}


{"category":"58fe37462b628c0f0033a79e","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37472b628c0f0033a7e0","next":{"pages":[],"description":""},"createdAt":"2016-03-20T21:41:40.877Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"delete","results":{"codes":[{"name":"","code":"","language":"json","status":204},{"name":"RFI Locked","code":"{\n  \"message\": \"RFI (d796e4d0-4639-406c-9b15-68d398dc6458) must be unlocked before it can be updated.\"\n}","language":"json","status":400},{"code":"{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) is prohibited.\"\n}","language":"json","status":404,"name":"No Project Access"},{"name":"RFI Missing","code":"{\n  \"message\": \"RFI (d796e4d0-4639-406c-9b15-68d398dc6458) does not exist on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}","language":"json","status":404},{"name":"Project Missing","status":404,"language":"json","code":"{\n  \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}"},{"code":"{\n  \"message\": \"Snapshot (130dc467-27bf-4642-9684-0bb4cae82afa) is not referenced on RFI (d796e4d0-4639-406c-9b15-68d398dc6458).\"\n}","language":"json","name":"Snapshot Not Referenced","status":404}]},"settings":"","auth":"required","params":[{"_id":"56ef1684a5bcfd0e0095175c","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56ef1684a5bcfd0e0095175b","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI.","default":"","type":"string","name":"rfi_uid"},{"_id":"56ef1684a5bcfd0e0095175a","ref":"","in":"path","required":true,"desc":"Unique identifier of referenced snapshot.","default":"","type":"string","name":"snapshot_uid"}],"url":"/projects/:project_uid/rfis/:rfi_uid/snapshots/:snapshot_uid"},"isReference":false,"order":70,"body":"","excerpt":"Remove a reference to a snapshot in an RFI. The snapshot is not deleted from the project.","slug":"remove-snapshot-reference-in-rfi","type":"delete","title":"Remove Snapshot Reference in RFI","__v":0,"childrenPages":[]}

deleteRemove Snapshot Reference in RFI

Remove a reference to a snapshot in an RFI. The snapshot is not deleted from the project.

Path Params

project_uid:
required
string
Unique identifier of project.
rfi_uid:
required
string
Unique identifier of RFI.
snapshot_uid:
required
string
Unique identifier of referenced snapshot.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}


{"category":"58fe37462b628c0f0033a79f","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7c3","next":{"pages":[],"description":""},"createdAt":"2015-10-24T16:43:04.464Z","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":71,"body":"[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"**uid**\\n`string`\",\n    \"0-1\": \"Not universally unique. Never blank. See [Unique Identifiers](doc:unique-identifiers) for details.\",\n    \"h-0\": \"Attribute\",\n    \"h-1\": \"Description\",\n    \"1-0\": \"**label**\\n`string`\",\n    \"1-1\": \"-\",\n    \"2-0\": \"**color**\\n`string`\",\n    \"2-1\": \"Color displayed in PlanGrid clients in [hexadecimal format](https://en.wikipedia.org/wiki/Web_colors#Hex_triplet). Never blank.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"uid\\\": \\\"4898bfd4\\\",\\n  \\\"label\\\": \\\"closed\\\",\\n  \\\"color\\\": \\\"#000000\\\"\\n}\",\n      \"language\": \"json\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]","excerpt":"","slug":"the-rfi-status-object","type":"basic","title":"The RFI Status Object","__v":0,"childrenPages":[]}

The RFI Status Object


Attribute
Description

uid
string

Not universally unique. Never blank. See Unique Identifiers for details.

label
string

-

color
string

Color displayed in PlanGrid clients in hexadecimal format. Never blank.

{
  "uid": "4898bfd4",
  "label": "closed",
  "color": "#000000"
}
{"category":"58fe37462b628c0f0033a79f","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7c4","next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:12:45.970Z","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\" : \"4898bfd4\",\n      \"label\" : \"draft\",\n      \"color\" : \"#34b27d\"\n    },\n    {\n      \"uid\" : \"0a83939c\",\n      \"label\" : \"open\",\n      \"color\" : \"#4d77cb\"\n    },\n    {\n      \"uid\" : \"19d0eace\",\n      \"label\" : \"closed\",\n      \"color\" : \"#dbdb57\"\n    },\n    {\n      \"uid\" : \"172c60ee\",\n      \"label\" : \"void\",\n      \"color\" : \"#cb4d4d\"\n    },\n    {\n      \"uid\" : \"711d51ff\",\n      \"label\" : \"\",\n      \"color\" : \"#e09952\"\n    },\n    {\n      \"uid\" : \"66a9e772\",\n      \"label\" : \"\",\n      \"color\" : \"#9933cc\"\n    }\n  ],\n  \"total_count\": 6,\n  \"next_page_url\": null\n}\n","language":"json"},{"status":"4XX","name":"Project Missing","code":"HTTP/1.1 404 Not Found\n{\n  \"message\": \"Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist.\"\n}\n","language":"json"},{"status":"4XX","name":"No Project Access","code":"HTTP/1.1 403 Forbidden\n{\n  \"message\": \"Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited.\"\n}\n","language":"json"}]},"settings":"","auth":"required","params":[{"_id":"56cf1ecf5267d70b00494bd4","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ecf5267d70b00494bd3","ref":"","in":"query","required":false,"desc":"Number of RFI statuses to retrieve. Maximum value of 50.","default":"50","type":"int","name":"limit"},{"_id":"56cf1ecf5267d70b00494bd2","ref":"","in":"query","required":false,"desc":"Number of RFI statuses to skip in the set of results.","default":"0","type":"int","name":"skip"}],"url":"/projects/:project_uid/rfis/statuses"},"isReference":false,"order":72,"body":"","excerpt":"Get the list of RFI statuses defined on the project. The first element in the list is the first/topmost status shown in PlanGrid clients. PlanGrid currently supports 6 RFI statuses.","slug":"retrieve-rfi-statuses-in-a-project","type":"get","title":"Retrieve RFI Statuses in a Project","__v":0,"childrenPages":[]}

getRetrieve RFI Statuses in a Project

Get the list of RFI statuses defined on the project. The first element in the list is the first/topmost status shown in PlanGrid clients. PlanGrid currently supports 6 RFI statuses.

Path Params

project_uid:
required
string
Unique identifier of project.

Query Params

limit:
integer50
Number of RFI statuses to retrieve. Maximum value of 50.
skip:
integer0
Number of RFI statuses to skip in the set of results.

User Information

Try It Out

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

Definition

{{ api_url }}{{ page_api_url }}

Result Format

{
  "data": [
    {
      "uid" : "4898bfd4",
      "label" : "draft",
      "color" : "#34b27d"
    },
    {
      "uid" : "0a83939c",
      "label" : "open",
      "color" : "#4d77cb"
    },
    {
      "uid" : "19d0eace",
      "label" : "closed",
      "color" : "#dbdb57"
    },
    {
      "uid" : "172c60ee",
      "label" : "void",
      "color" : "#cb4d4d"
    },
    {
      "uid" : "711d51ff",
      "label" : "",
      "color" : "#e09952"
    },
    {
      "uid" : "66a9e772",
      "label" : "",
      "color" : "#9933cc"
    }
  ],
  "total_count": 6,
  "next_page_url": null
}
HTTP/1.1 404 Not Found
{
  "message": "Project (bafce976-8f33-437f-9c58-fb274456940f) does not exist."
}
HTTP/1.1 403 Forbidden
{
  "message": "Access to project (bafce976-8f33-437f-9c58-fb274456940f) prohibited."
}


{"category":"58fe37462b628c0f0033a79f","parentDoc":null,"project":"55d2023b3c74062300aee506","user":"55d201fe945e481700afbb19","version":"58fe37462b628c0f0033a792","updates":[],"_id":"58fe37462b628c0f0033a7c5","next":{"pages":[],"description":""},"createdAt":"2016-03-19T21:13:20.323Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"method":"patch","results":{"codes":[{"status":200,"name":"Success","code":"{\n  \"uid\" : \"4898bfd4\",\n  \"label\" : \"draft\",\n  \"color\" : \"#34b27d\"\n}\n","language":"json"},{"status":400,"name":"Invalid Label","code":"{\n  \"message\": \"Label (2) must be null or a string at least one character long.\"\n}\n","language":"json"},{"status":403,"name":"Not Permitted","code":"{\n  \"message\": \"Insufficient permissions to update RFI statuses on project (bafce976-8f33-437f-9c58-fb274456940f).\"\n}\n","language":"json"}]},"settings":"","auth":"required","params":[{"_id":"56cf1ed05267d70b00494be4","ref":"","in":"path","required":true,"desc":"Unique identifier of project.","default":"","type":"string","name":"project_uid"},{"_id":"56cf1ed05267d70b00494be3","ref":"","in":"path","required":true,"desc":"Unique identifier of RFI status to update.","default":"","type":"string","name":"status_uid"},{"_id":"56cf1ed05267d70b00494be2","ref":"","in":"body","required":true,"desc":"A human readable label for the RFI status.","default":"","type":"string","name":"label"}],"url":"/projects/:project_uid/rfis/statuses/:status_uid"},"isReference":false,"order":73,"body":"","excerpt":"Updates an existing RFI status on the project.","slug":"update-rfi-status-in-a-project","type":"patch","title":"Update RFI Status in a Project","__v":0,"childrenPages":[]}

patchUpdate RFI Status in a Project

Updates an existing RFI status on the project.

Path Params

project_uid:
required
string
Unique identifier of project.
status_uid:
required
string
Unique identifier of RFI status to update.

Body Params

label:
required
string
A human readable label for the RFI status.

User Information

Try It Out

patch<