---
llm-context: api-documentation
purpose: Assist LLMs and developers with integrating the DoorFlow API API
service: doorflow
version: 3.0
endpoint: POST /api/3/card_designs
summary: Create card design
auth: oauth2
format: markdown
updated: 2026-06-14
---

# POST /api/3/card_designs

Create card design

Creates a new card design. Images can be provided as base64-encoded strings.

## 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:** account.card_design

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

## Request Body

### Fields

**`name`** *string*
Name of the card design (required for creation)

**`notes`** *string | null*
Free-text notes about the card design

**`image_front_base64`** *string | null*
Base64-encoded image data for the front of the card (data URI format, e.g. data:image/png;base64,...)

**`image_back_base64`** *string | null*
Base64-encoded image data for the back of the card (data URI format, e.g. data:image/png;base64,...)

### Example

```json
{
  "name": "Standard Blue Card",
  "notes": "string",
  "image_front_base64": "string",
  "image_back_base64": "string"
}
```

## Responses

### 201 - Card design created successfully

#### Response Fields

**`id`** *integer* - **Required**
Unique identifier for the card design
*Example:* `42`

**`name`** *string* - **Required**
Name of the card design
*Example:* `Standard Blue Card`

**`notes`** *string | null*
Free-text notes about the card design
*Example:* `Used for full-time employees`

**`image_front`** *object | null*
Front image URLs at multiple sizes, or null if no image is set

**`image_back`** *object | null*
Back image URLs at multiple sizes, or null if no image is set

**`created_at`** *string*
Timestamp of creation

**`updated_at`** *string*
Timestamp of last update

#### Example Response

```json
{
  "id": 42,
  "name": "Standard Blue Card",
  "notes": "Used for full-time employees",
  "image_front": {
    "original": "string",
    "medium": "string",
    "small": "string",
    "thumb": "string"
  },
  "image_back": {
    "original": "string",
    "medium": "string",
    "small": "string",
    "thumb": "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"
}
```

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

### 500 - Internal Server Error

#### Response Fields

**`error`** *string*
*Example:* `internal_server_error`

**`error_description`** *string*
*Example:* `An unexpected error occurred`

#### Example Response

```json
{
  "error": "internal_server_error",
  "error_description": "An unexpected error occurred"
}
```