Procore Company Observation Types API

openapi: 3.2.0
info:
  title: Procore REST Company Observation Types API
  version: v1.0/v2.0
  description: Merged from the per-resource OpenAPI documents Procore publishes through its developer portal (https://developers.procore.com/api/v1/resource_groups). Originals are kept verbatim in openapi/_original/resources/.
  x-source: https://developers.procore.com/api/v1/resource_groups
servers:
- url: https://api.procore.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Company Observation Types
paths:
  /rest/v1.0/companies/{company_id}/observation_types:
    parameters:
    - name: Procore-Company-Id
      in: header
      description: Unique company identifier associated with the Procore User Account.
      required: true
      schema:
        type: integer
    - name: company_id
      in: path
      description: Unique identifier for the company.
      required: true
      schema:
        type: integer
    x-compliance-level: full
    get:
      x-doc:
        visibility: public
        stage: ga
        exposure: public
      summary: List Company Observation Types
      description: Returns every Observation Type defined at the Company level, including deactivated ones. Company types are the pool that individual Projects activate from; use `GET /rest/v1.0/projects/{project_id}/observation_types` to see what is actually selectable on a given Project.
      tags:
      - Company Observation Types
      parameters:
      - name: page
        in: query
        description: Page
        schema:
          type: integer
      - name: per_page
        in: query
        description: Elements per page
        schema:
          type: integer
      responses:
        '200':
          description: OK
          headers:
            Per-Page:
              description: Number of items retrieved per page
              schema:
                type: integer
            Total:
              description: Total number of items to be retrieved
              schema:
                type: integer
            Link:
              description: Link headers for the first, prev, next, and last link
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                description: Array of Company Observation Types
                items:
                  type: object
                  title: Company Observation Type
                  properties:
                    id:
                      type: integer
                      description: Unique identifier for this Company Observation Type. Pass as `observation_template[observation_type_id]` when creating an Observation Template, or as `observation[type_id]` when creating an Observation Item on a Project where the type is activated.
                      example: 2020
                    name:
                      type: string
                      description: Display name of the Observation Type, localized to the requesting user's locale when a translation exists.
                      example: Air Quality
                    localized_name:
                      type: string
                      description: Type name resolved for the locale of the request, falling back to the Company default and then the stored name. Display this to end users rather than reimplementing the fallback chain.
                      example: Air Quality
                    category:
                      type: string
                      description: Localized display name of the type's Observations Category. Procore ships six built-in categories (Quality, Safety, Commissioning, Warranty, Work to Complete, Environmental), but companies can define additional categories, so treat this as free-form text. Use `category_key` for programmatic comparisons.
                      example: Environmental
                    category_key:
                      type: string
                      description: Stable, unlocalized key of the type's Observations Category. Prefer this over `category` when branching on category in code.
                      example: environmental
                    category_id:
                      type: integer
                      description: ID of the Observations Category this type belongs to. Corresponds to the `id` returned by `GET /rest/v2.0/companies/{company_id}/observations/categories`.
                      example: 13
                    company_active:
                      type: boolean
                      description: Whether the type is active at the Company level. For a company-level type this always matches `active`; the two diverge only when the same type is read in a Project scope where it has been deactivated.
                      example: true
                    active:
                      type: boolean
                      description: Whether the type can be selected on new Observations. Inactive types are still returned so existing Observations render correctly.
                      example: true
                    kind:
                      type: string
                      description: Whether the type is owned by the Company or defined on a single Project. Always `company` for records returned by the Company Observation Types endpoint.
                      enum:
                      - company
                      - project
                      example: company
                    parent_inactive:
                      type: boolean
                      description: Whether the type's parent company-level type has been deactivated. Always false here, since Company Observation Types have no parent.
                      example: false
                    in_use:
                      type: boolean
                      description: Whether at least one Observation Item currently references this type or one of its project-level children. Use to warn before deactivating or deleting a type.
                      example: false
                    name_translations:
                      type:
                      - object
                      - 'null'
                      additionalProperties:
                        type: string
                      description: Company-authored translations of the type name, keyed by locale code (for example `en`, `es`, `fr-CA`). Null when the Company has not configured custom translations for this type.
                      example:
                        en: Air Quality
                        es: Calidad del aire
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    format: int32
                  message:
                    type: string
                  fields:
                    type: string
                  reason:
                    description: A human-readable code providing additional detail on the cause of the error.
                    type: string
                  error:
                    description: Description of the error thrown.
                    type:
                    - string
                    - 'null'
                    example: Invalid Token
      x-code-samples:
      - id: node_request
        title: Node.js
        content: "const request = require('request');\n\nconst options = {\n  method: 'GET',\n  url: 'https://api.procore.com/rest/v1.0/companies/%7Bcompany_id%7D/observation_types',\n  qs: {page: 'SOME_INTEGER_VALUE', per_page: 'SOME_INTEGER_VALUE'},\n  headers: {Authorization: 'Bearer REPLACE_BEARER_TOKEN'}\n};\n\nrequest(options, function (error, response, body) {\n  if (error) throw new Error(error);\n\n  console.log(body);\n});\n"
      - id: python_python3
        title: Python3
        content: 'import http.client


          conn = http.client.HTTPSConnection("api.procore.com")


          headers = { ''Authorization'': "Bearer REPLACE_BEARER_TOKEN" }


          conn.request("GET", "/rest/v1.0/companies/%7Bcompany_id%7D/observation_types?page=SOME_INTEGER_VALUE&per_page=SOME_INTEGER_VALUE", headers=headers)


          res = conn.getresponse()

          data = res.read()


          print(data.decode("utf-8"))'
      - id: shell_curl
        title: Curl
        content: "curl --request GET \\\n  --url 'https://api.procore.com/rest/v1.0/companies/%7Bcompany_id%7D/observation_types?page=SOME_INTEGER_VALUE&per_page=SOME_INTEGER_VALUE' \\\n  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'"
      - id: csharp_httpclient
        title: C#
        content: "var client = new HttpClient();\nvar request = new HttpRequestMessage\n{\n    Method = HttpMethod.Get,\n    RequestUri = new Uri(\"https://api.procore.com/rest/v1.0/companies/%7Bcompany_id%7D/observation_types?page=SOME_INTEGER_VALUE&per_page=SOME_INTEGER_VALUE\"),\n    Headers =\n    {\n        { \"Authorization\", \"Bearer REPLACE_BEARER_TOKEN\" },\n    },\n};\nusing (var response = await client.SendAsync(request))\n{\n    response.EnsureSuccessStatusCode();\n    var body = await response.Content.ReadAsStringAsync();\n    Console.WriteLine(body);\n}"
      x-rate-limit-enabled: true
      x-procore-kong-tags:
      - rate-limit:enabled
      x-changelog:
      - summary: Added Company Observation Types list endpoint
        description: Get a list of Company Observation Types for a given company id.
        endpoint: GET /companies/{company_id}/observation_types
        type: new
        breaking: false
        datestamp: '2021-07-12'
        versions:
        - '1.0'
        x-doc:
          visibility: public
          stage: ga
          exposure: public
        link: company-observation-types?version=1.0#list-company-observation-types
      - summary: Return I18n localized name
        description: 'The index endpoint is now able to leverage the `Accept-Language` header to return its closest language match for `name` & `category` in the response.

          To localize, using header `HTTP_ACCEPT_LANGUAGE=''fr''`, `HTTP_ACCEPT_LANGUAGE=''fr-ca''`, `HTTP_ACCEPT_LANGUAGE=''fr-CA''`.'
        endpoint: GET /companies/{company_id}/observation_types
        type: refinement
        breaking: false
        datestamp: '2022-12-21'
        versions:
        - '1.0'
        x-doc:
          visibility: public
          stage: ga
          exposure: public
        link: company-observation-types?version=1.0#list-company-observation-types
      - summary: Add Observation Category ID
        description: Adds observation category ID to be used in place of category to set and return custom observation categories associated with a type.
        endpoint: GET /companies/{company_id}/observation_types
        type: refinement
        breaking: false
        datestamp: '2025-09-25'
        versions:
        - '1.0'
        x-doc:
          visibility: public
          stage: ga
          exposure: public
        link: company-observation-types?version=1.0#list-company-observation-types
      operationId: listCompanyObservationTypes
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer