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": "john.doe@example.com"
  },
  "updated_at": "2024-01-20T14:45:00Z",
  "updated_by": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "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": "john.doe@example.com"
  },
  "updated_at": "2024-01-20T14:45:00Z",
  "updated_by": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "team": {
    "id": "789e0123-e45b-67d8-a901-234567890123",
    "name": "Safety Team"
  },
  "data": {
    "control_count": 5,
    "controls": [
      {
        "id": "444e5555-e66b-77d4-a888-999900001111",
        "field_id": "safety_page",
        "type": "page",
        "path": "Safety Observations",
        "label": "Safety Observations",
        "children_count": 4,
        "children": [
          "111e2222-e33b-44d4-a555-666677778888",
          "222e3333-e44b-55d4-a666-777788889999",
          "333e4444-e55b-66d4-a777-888899990000",
          "555e6666-e77b-88d4-a999-000011112222"
        ],
        "parent_id": null,
        "options": {}
      },
      {
        "id": "111e2222-e33b-44d4-a555-666677778888",
        "field_id": "inspection_date",
        "type": "date",
        "path": "Safety Observations/Inspection Date",
        "label": "Inspection Date",
        "children_count": 0,
        "children": [],
        "parent_id": "444e5555-e66b-77d4-a888-999900001111",
        "options": {
          "is_required": true,
          "show_time": false
        }
      },
      {
        "id": "222e3333-e44b-55d4-a666-777788889999",
        "field_id": "inspector_name",
        "type": "text",
        "path": "Safety Observations/Inspector Name",
        "label": "Inspector Name",
        "children_count": 0,
        "children": [],
        "parent_id": "444e5555-e66b-77d4-a888-999900001111",
        "options": {
          "is_required": true,
          "is_multiline": false,
          "placeholder": "Enter inspector name"
        }
      },
      {
        "id": "333e4444-e55b-66d4-a777-888899990000",
        "field_id": "safety_rating",
        "type": "radio",
        "path": "Safety Observations/Saftey Rating",
        "label": "Safety Rating",
        "children_count": 0,
        "children": [],
        "parent_id": "444e5555-e66b-77d4-a888-999900001111",
        "options": {
          "is_required": true,
          "choices": [
            "Excellent",
            "Good",
            "Fair",
            "Poor"
          ]
        }
      },
      {
        "id": "555e6666-e77b-88d4-a999-000011112222",
        "field_id": "observation",
        "type": "text",
        "path": "Safety Observations/Observation",
        "label": "Observation",
        "children_count": 0,
        "children": [],
        "parent_id": "444e5555-e66b-77d4-a888-999900001111",
        "options": {
          "is_required": false,
          "is_multiline": true,
          "placeholder": "Enter observation details"
        }
      }
    ]
  }
}

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