Client Admin Users

Reference for the client_admin_users endpoints of the Surfmeter API.

Surfmeter API – Client Admin Users v1

The Surfmeter API lets you manage clients, users, capabilities, measurements, and organization-wide settings programmatically.

---

Servers

Description	URL
https://surfmeter-server.{host}/client_admin_api/v1	https://surfmeter-server.{host}/client_admin_api/v1

Client Admin Users

---

GET /client_admin_users

Input parameters

Parameter	In	Type	Default	Nullable	Description
ApiKeyAuth	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.

Response 200 OK

application/json

{
    "users": [
        {
            "id": 0,
            "email": "user@example.com",
            "username": "string",
            "role": "org_admin",
            "first_name": "string",
            "last_name": "string",
            "ai_usage_accepted": true,
            "ai_custom_prompt": "string",
            "pending_email": "string",
            "pending_email_token_sent_at": "2026-01-15T10:30:00Z",
            "pending_email_state": "active"
        }
    ]
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "description": "Response for client admin user index action",
    "type": "object",
    "required": [
        "users"
    ],
    "properties": {
        "users": {
            "type": "array",
            "items": {
                "type": "object",
                "required": [
                    "id",
                    "email",
                    "username",
                    "role"
                ],
                "properties": {
                    "id": {
                        "type": "integer"
                    },
                    "email": {
                        "type": "string",
                        "format": "email",
                        "example": "user@example.com"
                    },
                    "username": {
                        "type": "string"
                    },
                    "role": {
                        "type": "string",
                        "enum": [
                            "org_admin",
                            "admin",
                            "editor",
                            "viewer"
                        ]
                    },
                    "first_name": {
                        "type": "string",
                        "nullable": true
                    },
                    "last_name": {
                        "type": "string",
                        "nullable": true
                    },
                    "ai_usage_accepted": {
                        "type": "boolean",
                        "nullable": true
                    },
                    "ai_custom_prompt": {
                        "type": "string",
                        "nullable": true
                    },
                    "pending_email": {
                        "type": "string",
                        "nullable": true
                    },
                    "pending_email_token_sent_at": {
                        "type": "string",
                        "format": "date-time",
                        "nullable": true,
                        "example": "2026-01-15T10:30:00Z"
                    },
                    "pending_email_state": {
                        "type": "string",
                        "enum": [
                            "active",
                            "expired",
                            null
                        ],
                        "nullable": true
                    }
                }
            }
        }
    }
}

---

POST /client_admin_users

Input parameters

Parameter	In	Type	Default	Nullable	Description
ApiKeyAuth	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.

Request body

application/json

{
    "email": "user@example.com",
    "username": "string",
    "role": "org_admin",
    "first_name": "string",
    "last_name": "string",
    "notify_user": true
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "description": "Data for client admin user create action",
    "type": "object",
    "required": [
        "email",
        "username",
        "role"
    ],
    "properties": {
        "email": {
            "type": "string",
            "format": "email",
            "example": "user@example.com"
        },
        "username": {
            "type": "string"
        },
        "role": {
            "type": "string",
            "enum": [
                "org_admin",
                "admin",
                "editor",
                "viewer"
            ]
        },
        "first_name": {
            "type": "string",
            "nullable": true
        },
        "last_name": {
            "type": "string",
            "nullable": true
        },
        "notify_user": {
            "type": "boolean",
            "description": "When true, email the new user that their account has been created. Defaults to false when omitted."
        }
    }
}

Response 201 Created

application/json

{
    "user": {
        "id": 0,
        "email": "user@example.com",
        "username": "string",
        "role": "org_admin",
        "first_name": "string",
        "last_name": "string",
        "ai_usage_accepted": true,
        "ai_custom_prompt": "string",
        "pending_email": "string",
        "pending_email_token_sent_at": "2026-01-15T10:30:00Z",
        "pending_email_state": "active"
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "description": "Response for client admin user create action",
    "type": "object",
    "required": [
        "user"
    ],
    "properties": {
        "user": {
            "type": "object",
            "required": [
                "id",
                "email",
                "username",
                "role"
            ],
            "properties": {
                "id": {
                    "type": "integer"
                },
                "email": {
                    "type": "string",
                    "format": "email",
                    "example": "user@example.com"
                },
                "username": {
                    "type": "string"
                },
                "role": {
                    "type": "string",
                    "enum": [
                        "org_admin",
                        "admin",
                        "editor",
                        "viewer"
                    ]
                },
                "first_name": {
                    "type": "string",
                    "nullable": true
                },
                "last_name": {
                    "type": "string",
                    "nullable": true
                },
                "ai_usage_accepted": {
                    "type": "boolean",
                    "nullable": true
                },
                "ai_custom_prompt": {
                    "type": "string",
                    "nullable": true
                },
                "pending_email": {
                    "type": "string",
                    "nullable": true
                },
                "pending_email_token_sent_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true,
                    "example": "2026-01-15T10:30:00Z"
                },
                "pending_email_state": {
                    "type": "string",
                    "enum": [
                        "active",
                        "expired",
                        null
                    ],
                    "nullable": true
                }
            }
        }
    }
}

---

GET /client_admin_users/{id}

Input parameters

Parameter	In	Type	Default	Nullable	Description
ApiKeyAuth	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
id	path	string		No

Response 200 OK

application/json

{
    "user": {
        "id": 0,
        "email": "user@example.com",
        "username": "string",
        "role": "org_admin",
        "first_name": "string",
        "last_name": "string",
        "ai_usage_accepted": true,
        "ai_custom_prompt": "string",
        "pending_email": "string",
        "pending_email_token_sent_at": "2026-01-15T10:30:00Z",
        "pending_email_state": "active"
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "description": "Response for client admin user show action",
    "type": "object",
    "required": [
        "user"
    ],
    "properties": {
        "user": {
            "type": "object",
            "required": [
                "id",
                "email",
                "username",
                "role"
            ],
            "properties": {
                "id": {
                    "type": "integer"
                },
                "email": {
                    "type": "string",
                    "format": "email",
                    "example": "user@example.com"
                },
                "username": {
                    "type": "string"
                },
                "role": {
                    "type": "string",
                    "enum": [
                        "org_admin",
                        "admin",
                        "editor",
                        "viewer"
                    ]
                },
                "first_name": {
                    "type": "string",
                    "nullable": true
                },
                "last_name": {
                    "type": "string",
                    "nullable": true
                },
                "ai_usage_accepted": {
                    "type": "boolean",
                    "nullable": true
                },
                "ai_custom_prompt": {
                    "type": "string",
                    "nullable": true
                },
                "pending_email": {
                    "type": "string",
                    "nullable": true
                },
                "pending_email_token_sent_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true,
                    "example": "2026-01-15T10:30:00Z"
                },
                "pending_email_state": {
                    "type": "string",
                    "enum": [
                        "active",
                        "expired",
                        null
                    ],
                    "nullable": true
                }
            }
        }
    }
}

---

PUT /client_admin_users/{id}

Input parameters

Parameter	In	Type	Default	Nullable	Description
ApiKeyAuth	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
id	path	string		No

Request body

application/json

{
    "first_name": "string",
    "last_name": "string",
    "ai_usage_accepted": true,
    "ai_custom_prompt": "string"
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the request body

{
    "description": "Request data for client admin user update action",
    "type": "object",
    "properties": {
        "first_name": {
            "type": "string",
            "nullable": true
        },
        "last_name": {
            "type": "string",
            "nullable": true
        },
        "ai_usage_accepted": {
            "type": "boolean",
            "nullable": true
        },
        "ai_custom_prompt": {
            "type": "string",
            "nullable": true
        }
    }
}

Response 200 OK

application/json

{
    "user": {
        "id": 0,
        "email": "user@example.com",
        "username": "string",
        "role": "org_admin",
        "first_name": "string",
        "last_name": "string",
        "ai_usage_accepted": true,
        "ai_custom_prompt": "string",
        "pending_email": "string",
        "pending_email_token_sent_at": "2026-01-15T10:30:00Z",
        "pending_email_state": "active"
    }
}

⚠️ This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "description": "Response for client admin user update action",
    "type": "object",
    "required": [
        "user"
    ],
    "properties": {
        "user": {
            "type": "object",
            "required": [
                "id",
                "email",
                "username",
                "role"
            ],
            "properties": {
                "id": {
                    "type": "integer"
                },
                "email": {
                    "type": "string",
                    "format": "email",
                    "example": "user@example.com"
                },
                "username": {
                    "type": "string"
                },
                "role": {
                    "type": "string",
                    "enum": [
                        "org_admin",
                        "admin",
                        "editor",
                        "viewer"
                    ]
                },
                "first_name": {
                    "type": "string",
                    "nullable": true
                },
                "last_name": {
                    "type": "string",
                    "nullable": true
                },
                "ai_usage_accepted": {
                    "type": "boolean",
                    "nullable": true
                },
                "ai_custom_prompt": {
                    "type": "string",
                    "nullable": true
                },
                "pending_email": {
                    "type": "string",
                    "nullable": true
                },
                "pending_email_token_sent_at": {
                    "type": "string",
                    "format": "date-time",
                    "nullable": true,
                    "example": "2026-01-15T10:30:00Z"
                },
                "pending_email_state": {
                    "type": "string",
                    "enum": [
                        "active",
                        "expired",
                        null
                    ],
                    "nullable": true
                }
            }
        }
    }
}

---

DELETE /client_admin_users/{id}

Input parameters

Parameter	In	Type	Default	Nullable	Description
ApiKeyAuth	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
id	path	string		No

Response 200 OK

application/json

Schema of the response body

{
    "description": "Response for client admin user destroy action",
    "type": "object",
    "properties": {}
}

---

POST /client_admin_users/{id}/email_change

Input parameters

Parameter	In	Type	Default	Nullable	Description
ApiKeyAuth	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
id	path	string		No

Response 200 OK

---

DELETE /client_admin_users/{id}/email_change

Input parameters

Parameter	In	Type	Default	Nullable	Description
ApiKeyAuth	header	string	N/A	No	API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.
id	path	string		No

Response 200 OK

---

Schemas

ClientAdminUserCreateData

Name	Type
email	string(email)
first_name	string| null
last_name	string| null
notify_user	boolean
role	string
username	string

ClientAdminUserCreateResponse

Name	Type
user	Properties: id, email, username, role, first_name, last_name, ai_usage_accepted, ai_custom_prompt, pending_email, pending_email_token_sent_at, pending_email_state

ClientAdminUserDestroyResponse

ClientAdminUserIndexResponse

Name	Type
users	Array<Properties: id, email, username, role, first_name, last_name, ai_usage_accepted, ai_custom_prompt, pending_email, pending_email_token_sent_at, pending_email_state>

ClientAdminUserShowResponse

Name	Type
user	Properties: id, email, username, role, first_name, last_name, ai_usage_accepted, ai_custom_prompt, pending_email, pending_email_token_sent_at, pending_email_state

ClientAdminUserUpdateData

Name	Type
ai_custom_prompt	string| null
ai_usage_accepted	boolean| null
first_name	string| null
last_name	string| null

ClientAdminUserUpdateResponse

Name	Type
user	Properties: id, email, username, role, first_name, last_name, ai_usage_accepted, ai_custom_prompt, pending_email, pending_email_token_sent_at, pending_email_state

Security schemes

Name	Type	Scheme	Description
ApiKeyAuth	apiKey		API key used on every request. Create keys in the Surfmeter Dashboard under Keys → Surfmeter API Keys.