> ## Documentation Index > Fetch the complete documentation index at: https://developers.conveyour.com/llms.txt > Use this file to discover all available pages before exploring further. # Create a custom report > Creates a new custom report template. The `class` must be the camelCase ID of an existing report (e.g. `campaignsCampaignPerformance`, `officePerformance`). The `input` field configures how each report control parameter behaves for viewers of the shared report: - **`locked`** — the value is fixed; the viewer cannot change it and the control is hidden - **`editable`** — the value is the default; the viewer can override it Create a custom report template ## OpenAPI ````yaml /api-reference/specs/reports.json post /api/custom-reports openapi: 3.1.0 info: title: ConveYour API — Reports description: >- Retrieve report data, run report actions, access shared reports, and manage custom report templates. version: 1.0.0 servers: - url: https://{subdomain}.conveyour.com description: Your organization's ConveYour instance variables: subdomain: default: acme description: >- Your organization's slug — the subdomain you sign in on. Replace `acme` with yours: if you sign in at `bigco.conveyour.com`, enter `bigco`. security: - conveyourToken: [] tags: - name: Reports description: >- Retrieve report data, run report actions, access shared reports, and manage custom report templates. paths: /api/custom-reports: post: tags: - Reports summary: Create a custom report description: >- Creates a new custom report template. The `class` must be the camelCase ID of an existing report (e.g. `campaignsCampaignPerformance`, `officePerformance`). The `input` field configures how each report control parameter behaves for viewers of the shared report: - **`locked`** — the value is fixed; the viewer cannot change it and the control is hidden - **`editable`** — the value is the default; the viewer can override it Create a custom report template operationId: createACustomReportTemplate parameters: - $ref: '#/components/parameters/teams' requestBody: required: true content: application/json: schema: type: object required: - class properties: title: description: Display name for this saved report configuration. type: string class: description: >- The camelCase ID of the report class to render (e.g. `campaignsCampaignPerformance`). type: string secure: description: >- When `true` (default), parameters are JWT-encoded in the share URL. When `false`, params go as plain query strings. type: boolean portal_visible: description: >- When `true`, this report is visible to contacts via the portal. Default: `false`. type: boolean teams: description: >- Team IDs that restrict access to this report. Empty array = all teams. type: array items: type: string input: description: >- Map of control parameter keys to their rule and default value. Each entry: `{ "rule": "locked" | "editable", "value": "..." }`. type: object additionalProperties: true responses: '200': description: Success. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - type: object properties: data: $ref: '#/components/schemas/Report' example: status: ok message: Custom Report created data: id: 507f1f77bcf86cd799439011 pid: abc123def456ghi789jkl012 title: Office Performance Report class: officePerformance secure: true portal_visible: false teams: [] input: office_id: rule: locked value: '' date_range: rule: editable value: last_30_days '403': $ref: '#/components/responses/ForbiddenToken' components: parameters: teams: name: teams[] in: query description: >- Team scope for the request, as one or more team ObjectIds. The brackets are required: PHP keeps only the last value for a repeated plain key, so `teams=A&teams=B` silently resolves to B alone. On requests with a JSON body you may send `teams` (no brackets) in the body instead. **Values that are not valid ObjectIds are silently ignored** — a mistyped team ID behaves as if no team was sent. See the [teams section of the API conventions guide](/guides/api-conventions#team-scoping). style: form explode: true schema: type: array items: type: string example: - 64a1b2c3d4e5f6a7b8c9d0ff schemas: Envelope: type: object description: The common response envelope shared by all ConveYour endpoints. properties: status: type: string enum: - ok - failed description: '`ok` on success, `failed` on error.' message: type: string description: Human-readable description of the result. data: description: >- The response payload — an object or an array depending on the endpoint. Report: type: object description: A saved custom report. properties: id: type: string description: Record ObjectId. pid: type: string description: Public ID, 24 chars, generated in onSaving(). Used in the share URL. org_id: type: integer description: Owning organization. user_id: type: integer description: User who created the report. title: type: string description: Display title. class: type: string description: The registered report class this record configures. secure: type: boolean description: Whether the share URL requires a signed JWT. Defaults to true. portal_visible: type: boolean description: Whether learners see it in the portal. Defaults to false. teams: type: array items: type: string description: Team ObjectIds the report is scoped to. input: type: object description: >- Saved input values, keyed by input name. Declared as a NestedModel, so each entry is an object — not a scalar. additionalProperties: type: object properties: rule: type: string enum: - locked - editable description: Whether a viewer may change this input. Defaults to locked. value: type: string description: The saved value. pinned_fields: type: array items: type: string description: Field keys pinned in the report view. created_at: type: string description: Creation timestamp. updated_at: type: string description: Last update timestamp. deleted_at: type: - string - 'null' description: Soft-delete timestamp; null while active. required: - class responses: ForbiddenToken: description: >- The token is missing, expired, or not permitted for this HTTP method. **This endpoint enforces no named permission**, so a 403 here never carries a `permission` field. content: application/json: example: status: failed message: Token is either expired or does not have the correct permissions data: [] securitySchemes: conveyourToken: type: apiKey in: header name: x-conveyour-token description: >- Your API key token. Contacts endpoints require a **Server-only — Full API** key — see [Authentication](/quickstart). ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.