---
llm-context: api-documentation
purpose: Assist LLMs and developers with integrating the DoorFlow API API
service: doorflow
version: 3.0
endpoint: PUT /api/3/card_templates/{id}/background_image/{side}
summary: Upload background image
auth: oauth2
format: markdown
updated: 2026-06-14
---

# PUT /api/3/card_templates/{id}/background_image/{side}

Upload background image

Uploads or replaces the background image for the specified side.

## Authentication

This endpoint requires authentication using one of the following methods:

### OAuth 2.0 (Recommended)

Use an OAuth 2.0 access token in the Authorization header. This is the recommended authentication method for all integrations. OAuth provides automatic token expiration, granular permission scopes, detailed usage tracking, and per-integration revocation.

**Required Scopes:** private.account.card_template

**Example:**
```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

## Parameters

### Path Parameters

**`id`** (Required)
- **Type:** integer
- **Description:** Card template ID



**`side`** (Required)
- **Type:** string
- **Description:** Which side of the card
- **Allowed values:** `front`, `back`


## Responses

### 200 - Background image uploaded successfully

#### Response Fields

**`id`** *integer* - **Required**
Server-assigned identifier
*Example:* `42`

**`uuid`** *string* - **Required**
Client-generated UUID (RFC 4122)
*Example:* `550E8400-E29B-41D4-A716-446655440000`

**`name`** *string* - **Required**
Template display name, unique per account
*Example:* `Staff Card`

**`template_type_code`** *string* - **Required**
References a template type code
*Example:* `ISO_CARD`

**`card_type`** *string*
Card finish/format
*Example:* `standard`

**`double_sided`** *boolean*
Whether the card has a reverse side
*Example:* `true`

**`orientation_front`** *string*
P = Portrait, L = Landscape
*Example:* `P`

**`orientation_back`** *string*
P = Portrait, L = Landscape
*Example:* `L`

**`default_template`** *boolean*
Whether this is the account default template

**`background_image_front_url`** *string | null*
URL to the front background image, or null if not set

**`background_image_back_url`** *string | null*
URL to the back background image, or null if not set

**`template_objects`** *array<object>*
Free-form JSONB objects representing layout elements on this template

**`owner_id`** *integer | null*
ID of the user who owns this template, or null if unowned. Set
server-side on create. May be reassigned via PATCH by the current
owner or by any admin in the account; the new value must be the
ID of an admin in the same account.


**`editable_by`** *string*
Who can edit this template

**`deleted_at`** *string | null*
Soft-delete timestamp. Null for live templates. Writable via PATCH:
sending a non-null value soft-deletes the template; sending null
restores it. Soft-deleted templates are excluded from index by
default (see include_deleted).


**`deleted_by_id`** *integer | null*
ID of the user who soft-deleted this template, set server-side
from the authenticated user when deleted_at is written. Cleared
when deleted_at is cleared.


**`linked_files`** *array<object>*
Files linked to this template (images, fonts, etc.)

**`created_at`** *string*
ISO 8601 UTC timestamp.

**`updated_at`** *string*
ISO 8601 UTC timestamp.

#### Example Response

```json
{
  "id": 42,
  "uuid": "550E8400-E29B-41D4-A716-446655440000",
  "name": "Staff Card",
  "template_type_code": "ISO_CARD",
  "card_type": "standard",
  "double_sided": true,
  "orientation_front": "P",
  "orientation_back": "L",
  "default_template": false,
  "background_image_front_url": "string",
  "background_image_back_url": "string",
  "template_objects": [
    {}
  ],
  "owner_id": 0,
  "editable_by": "string",
  "deleted_at": "string",
  "deleted_by_id": 0,
  "linked_files": [
    {
      "uuid": "string",
      "entity_type": "string",
      "entity_uuid": "string",
      "file_role": "string",
      "url": "string",
      "content_type": "string",
      "created_at": "string",
      "updated_at": "string"
    }
  ],
  "created_at": "string",
  "updated_at": "string"
}
```

### 401 - Unauthorized - Invalid or missing authentication

#### Response Fields

**`error`** *string*
*Example:* `unauthorized`

**`error_description`** *string*
*Example:* `The access token is invalid`

#### Example Response

```json
{
  "error": "unauthorized",
  "error_description": "The access token is invalid"
}
```

### 403 - Forbidden - User does not have permission

#### Response Fields

**`error`** *string*
*Example:* `forbidden`

**`error_description`** *string*
*Example:* `You are not authorized to access this resource`

#### Example Response

```json
{
  "error": "forbidden",
  "error_description": "You are not authorized to access this resource"
}
```

### 404 - Not Found - Resource does not exist or is not an admission request event

#### Response Fields

**`error`** *string*
*Example:* `not_found`

**`error_description`** *string*
*Example:* `The requested resource was not found`

#### Example Response

```json
{
  "error": "not_found",
  "error_description": "The requested resource was not found"
}
```

### 422 - Unprocessable Entity - Validation failed

#### Response Fields

**`error`** *string*
Error message

**`errors`** *object*
Field-specific validation errors

#### Example Response

```json
{
  "error": "string",
  "errors": {
    "value": [
      "string"
    ],
    "credential_type_id": [
      "string"
    ],
    "limit_reached": "You have reached your HID Mobile licence limit. Please contact DoorFlow Support."
  }
}
```