Get a template by id

Time	Status	User Agent
Retrieving recent requests…

Overview

This endpoint retrieves a single template by its unique identifier. The template can be identified using either its GUID (UUID) or its template identifier string.

Endpoint: GET /v1/templates/{templateIdOrIdentifier}

Authentication: Required - API key must be provided in the access-token header

Authentication

All requests to this endpoint require authentication via an API key. The API key must be included in the request header:

access-token: <your-api-key>

If the API key is missing or invalid, the endpoint will return a 401 Unauthorized response.

Path Parameters

`templateIdOrIdentifier` (required)

The unique identifier for the template. This parameter accepts either:

Template GUID: A UUID format identifier (e.g., 550e8400-e29b-41d4-a716-446655440000)
Template Identifier: A string identifier (maximum 20 characters, case-insensitive)

The endpoint will first attempt to parse the value as a GUID. If successful, it searches for a template with that GUID. If the GUID parsing fails, it searches for a template with a matching template identifier (case-insensitive comparison).

Examples:

GET /v1/templates/550e8400-e29b-41d4-a716-446655440000 (GUID)
GET /v1/templates/INSP-001 (Template identifier)

Query Parameters

`includes` (optional)

A list of strings that controls the amount of data returned in the response. This parameter can be specified multiple times or as a comma-separated list.

Valid values:

"data" - Includes the full template structure with controls
"all" - Same as "data", includes the full template structure with controls

Examples:

GET /v1/templates/550e8400-e29b-41d4-a716-446655440000?includes=data
GET /v1/templates/INSP-001?includes=all
GET /v1/templates/550e8400-e29b-41d4-a716-446655440000?includes=data&includes=all (multiple values)

Note: If the includes parameter is not provided or does not contain "data" or "all", the response will not include the data field with template controls.

Request Examples

Example 1: Get template by GUID (without includes)

GET /v1/templates/550e8400-e29b-41d4-a716-446655440000 HTTP/1.1
Host: api.example.com
access-token: your-api-key-here

Example 2: Get template by template identifier

GET /v1/templates/INSP-001 HTTP/1.1
Host: api.example.com
access-token: your-api-key-here

Example 3: Get template with full data structure

GET /v1/templates/550e8400-e29b-41d4-a716-446655440000?includes=data HTTP/1.1
Host: api.example.com
access-token: your-api-key-here

Example 4: Using cURL

# Get template by GUID
curl -X GET "https://api.example.com/v1/templates/550e8400-e29b-41d4-a716-446655440000" \
  -H "access-token: your-api-key-here"

# Get template by identifier
curl -X GET "https://api.example.com/v1/templates/INSP-001" \
  -H "access-token: your-api-key-here"

# Get template with data
curl -X GET "https://api.example.com/v1/templates/550e8400-e29b-41d4-a716-446655440000?includes=data" \
  -H "access-token: your-api-key-here"

Response Structure

Success Response (200 OK)

On success, the endpoint returns a single template object. For detailed information on the template object, refer here.

Response Examples

Example 1: Success Response (without includes)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Safety Inspection Template",
  "template_id": "SAFETY-001",
  "description": "Template for conducting safety inspections",
  "created_at": "2024-01-15T10:30:00Z",
  "created_by": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "email": "[email protected]"
  },
  "updated_at": "2024-01-20T14:45:00Z",
  "updated_by": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "email": "[email protected]"
  },
  "team": {
    "id": "789e0123-e45b-67d8-a901-234567890123",
    "name": "Safety Team"
  }
}

Example 2: Success Response (with includes=data)

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Safety Inspection Template",
  "template_id": "SAFETY-001",
  "description": "Template for conducting safety inspections",
  "created_at": "2024-01-15T10:30:00Z",
  "created_by": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "email": "[email protected]"
  },
  "updated_at": "2024-01-20T14:45:00Z",
  "updated_by": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "email": "[email protected]"
  },
  "team": {
    "id": "789e0123-e45b-67d8-a901-234567890123",
    "name": "Safety Team"
  },
  "data": {
    "control_count": 9,
    "controls": [
      {
        "id": "444e5555-e66b-77d4-a888-999900001111",
        "field_id": "site_page",
        "type": "page",
        "path": "Site Walkthrough",
        "label": "Site Walkthrough",
        "children_count": 1,
        "children": [
          "888e9999-e00b-11d4-a222-333344445555"
        ],
        "parent_id": null,
        "options": {}
      },
      {
        "id": "888e9999-e00b-11d4-a222-333344445555",
        "field_id": "roof_section",
        "type": "section",
        "path": "Site Walkthrough/Roof",
        "label": "Roof",
        "children_count": 7,
        "children": [
          "666e7777-e88b-99d4-a000-111122223333",
          "111e2222-e33b-44d4-a555-666677778888",
          "222e3333-e44b-55d4-a666-777788889999",
          "333e4444-e55b-66d4-a777-888899990000",
          "555e6666-e77b-88d4-a999-000011112222",
          "999e0000-e11b-22d4-a333-444455556666",
          "777e8888-e99b-00d4-a111-222233334444"
        ],
        "parent_id": "444e5555-e66b-77d4-a888-999900001111",
        "options": {
          "data_view": "card_view",
          "is_repeatable": false
        }
      },
      {
        "id": "666e7777-e88b-99d4-a000-111122223333",
        "field_id": "roof_scope",
        "type": "instructions",
        "path": "Site Walkthrough/Roof/Roof Scope",
        "label": "Roof Scope",
        "children_count": 0,
        "children": [],
        "parent_id": "888e9999-e00b-11d4-a222-333344445555",
        "options": {
          "description": "The roof covering, flashing and drainage are inspected from ground level.\nRoof spaces are not entered.",
          "show_in_report": false
        }
      },
      {
        "id": "111e2222-e33b-44d4-a555-666677778888",
        "field_id": "inspection_date",
        "type": "date",
        "path": "Site Walkthrough/Roof/Inspection Date",
        "label": "Inspection Date",
        "children_count": 0,
        "children": [],
        "parent_id": "888e9999-e00b-11d4-a222-333344445555",
        "options": {
          "show_time": false,
          "is_required": true,
          "show_notes": true,
          "show_media": true,
          "allow_upload_photos": true,
          "show_in_report": true
        }
      },
      {
        "id": "222e3333-e44b-55d4-a666-777788889999",
        "field_id": "inspector_name",
        "type": "text",
        "path": "Site Walkthrough/Roof/Inspector Name",
        "label": "Inspector Name",
        "children_count": 0,
        "children": [],
        "parent_id": "888e9999-e00b-11d4-a222-333344445555",
        "options": {
          "is_multiline": false,
          "placeholder": "Enter inspector name",
          "is_required": true,
          "show_notes": false,
          "show_media": false,
          "allow_upload_photos": false,
          "show_in_report": true
        }
      },
      {
        "id": "333e4444-e55b-66d4-a777-888899990000",
        "field_id": "roof_condition",
        "type": "radio",
        "path": "Site Walkthrough/Roof/Roof Condition",
        "label": "Roof Condition",
        "children_count": 0,
        "children": [],
        "parent_id": "888e9999-e00b-11d4-a222-333344445555",
        "options": {
          "choices": [
            "Good",
            "Fair",
            "Poor"
          ],
          "choices_type": "manual",
          "data_source_id": null,
          "choice_items": [
            {
              "id": "9a1f0c2e-3b4d-4e5f-8a6b-7c8d9e0f1a2b",
              "value": "Good",
              "color": "#29AF62",
              "score": 2,
              "is_flagged": false,
              "flag": null
            },
            {
              "id": "9a1f0c2e-3b4d-4e5f-8a6b-7c8d9e0f1a2c",
              "value": "Fair",
              "color": "#FAB005",
              "score": 1.5,
              "is_flagged": false,
              "flag": null
            },
            {
              "id": "9a1f0c2e-3b4d-4e5f-8a6b-7c8d9e0f1a2d",
              "value": "Poor",
              "color": "#E01E53",
              "score": 0,
              "is_flagged": true,
              "flag": {
                "id": "5c7e2a10-8f3b-4d6a-9e21-0b4c6d8f1a3e",
                "name": "Needs repair",
                "color": "#E01E53"
              }
            }
          ],
          "is_required": true,
          "show_notes": true,
          "show_media": true,
          "allow_upload_photos": true,
          "show_in_report": true
        }
      },
      {
        "id": "555e6666-e77b-88d4-a999-000011112222",
        "field_id": "roof_pitch",
        "type": "number",
        "path": "Site Walkthrough/Roof/Roof Pitch (degrees)",
        "label": "Roof Pitch (degrees)",
        "children_count": 0,
        "children": [],
        "parent_id": "888e9999-e00b-11d4-a222-333344445555",
        "options": {
          "placeholder": "Enter pitch",
          "is_required": false,
          "show_notes": true,
          "show_media": true,
          "allow_upload_photos": true,
          "show_in_report": true
        }
      },
      {
        "id": "999e0000-e11b-22d4-a333-444455556666",
        "field_id": "country_of_manufacture",
        "type": "dropdown",
        "path": "Site Walkthrough/Roof/Country of Manufacture",
        "label": "Country of Manufacture",
        "children_count": 0,
        "children": [],
        "parent_id": "888e9999-e00b-11d4-a222-333344445555",
        "options": {
          "choices": [],
          "choices_type": "custom_sets",
          "data_source_id": "cd438fcb-3525-484c-ba83-858377d91948",
          "choice_items": [],
          "is_required": false,
          "show_notes": false,
          "show_media": false,
          "allow_upload_photos": false,
          "show_in_report": true
        }
      },
      {
        "id": "777e8888-e99b-00d4-a111-222233334444",
        "field_id": "reference_photos",
        "type": "image",
        "path": "Site Walkthrough/Roof/Reference Photos",
        "label": "Reference Photos",
        "children_count": 0,
        "children": [],
        "parent_id": "888e9999-e00b-11d4-a222-333344445555",
        "options": {
          "layout": "stack",
          "image_size": "large",
          "alignment": "left",
          "is_carousel": false,
          "columns": null,
          "hide_label": true,
          "show_in_report": true
        }
      }
    ]
  }
}

Error Responses

400 Bad Request

Returned when the request parameters are invalid.

Example Response:

{
  "code": 400,
  "message": "Invalid parameter value: template_id"
}

Common causes:

Missing or empty templateIdOrIdentifier path parameter
Invalid includes parameter value (though this is typically ignored if invalid)

401 Unauthorized

Returned when authentication fails.

Example Response:

{
  "code": 401,
  "message": "Access to the requested resource is denied due to invalid or missing authentication credentials."
}

Common causes:

Missing access-token header
Invalid or expired API key
API key does not belong to a valid organization

404 Not Found

Returned when the template with the specified identifier cannot be found.

Example Response:

{
  "code": 404,
  "message": "Template not found"
}

Common causes:

Template GUID does not exist
Template identifier does not exist
Template exists but is not accessible to the organization associated with the API key
Template has been deleted

500 Internal Server Error

Returned when an unexpected server error occurs.

Example Response:

{
  "code": 500,
  "message": "An internal server error occurred. Please try again later."
}

Notes and Additional Information

Template Identifier Case Sensitivity: Template identifiers are case-insensitive. INSP-001, insp-001, and Insp-001 will all match the same template.
Search Logic: The endpoint first attempts to parse the templateIdOrIdentifier as a GUID. If successful, it searches for a template with that GUID. If GUID parsing fails, it searches for a template with a matching template identifier (case-insensitive).
Includes Parameter:
- When includes contains "data" or "all", the response includes the full template structure with all controls and their options.
- If includes is not provided or contains invalid values, the data field will be omitted from the response.
Organization Scope: Templates are scoped to the organization associated with the API key. Only templates belonging to teams within that organization are accessible.
Template Access: The template must belong to a team that is part of the organization associated with the API key. Templates from other organizations will not be returned, even if the GUID or identifier matches.
Response Format: All dates and times are returned in ISO 8601 format (UTC).
Instruction text: For instructions controls, options.description is the instruction text as plain text, with \n line breaks. See Control options.
Choice options: For radio, checkbox and dropdown controls, read the options from options.choice_items: each option's id, value, color, score and flag. options.choices is deprecated and will be retired. For a custom set control, choice_items is empty; get the items with Get a custom set by id using options.data_source_id.

Overview

Authentication

Path Parameters

templateIdOrIdentifier (required)

Query Parameters

includes (optional)

Request Examples

Example 1: Get template by GUID (without includes)

Example 2: Get template by template identifier

Example 3: Get template with full data structure

Example 4: Using cURL

Response Structure

Success Response (200 OK)

Response Examples

Example 1: Success Response (without includes)

Example 2: Success Response (with includes=data)

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

Notes and Additional Information

200Response (with includes=data)

400Bad Request

401Unauthorized

404Not Found

500Internal Server Error

`templateIdOrIdentifier` (required)

`includes` (optional)