---
title: "Creates a custom objective."
method: POST
path: "/v1/pvt/Objectives/custom"
tags: ["Objectives"]
---

# Creates a custom objective.

`POST /v1/pvt/Objectives/custom`

## Request

- Base URL: `https://api.bonifiq.com.br`
- URL: `https://api.bonifiq.com.br/v1/pvt/Objectives/custom`
- Auth: HTTP basic

The objective is created for the store of the API key and is listed by the objectives list endpoints.
Use the returned Guid to reward customers through POST v1/pvt/Objectives/{guid}/importpoints.
            
This endpoint is not idempotent: each successful call creates a new objective.

**Required permission:** `PointsWrite` (Admin: Pontos e cashback - Leitura e escrita)

## Request body

- CreateCustomObjectiveRequest: Request to create a custom objective. Customers are rewarded later through the import points endpoint (POST v1/pvt/Objectives/{guid}/importpoints), using the Guid returned on creation.
  - `Name` string, nullable: Name of the objective. Required, up to 100 characters.
  - `AmountOfPoints` integer: Amount of points granted each time a customer completes the objective. Must be greater than zero.
  - `Active` boolean: If false, the objective is created inactive and does not grant points. Defaults to true.
  - `CustomerMaxCompletion` integer, nullable: Maximum number of times each customer can be rewarded by this objective. Null (default) means no limit; when informed it must be greater than zero.
  - `ShowOnWidgetAndLandingPage` boolean: If true, the objective card is shown on the widget and on the landing page. Defaults to false.
  - `IconUrl` string, nullable: Optional icon shown on the objective card. Must be an absolute HTTPS URL with up to 2048 characters.
  - `CardTitle` string, nullable: Optional card title, up to 20 characters. The widget and the landing page show the card without a title when it is empty.
  - `CardDescription` string, nullable: Optional card description, up to 4000 characters. Accepts basic HTML (p, br, strong, b, em, i, u, ul, ol, li, a, img); any other tag, attribute or unsafe link is removed.
  - `ActionButtonText` string, nullable: Optional action button text, up to 10 characters. Must be informed together with ActionButtonUrl.
  - `ActionButtonUrl` string, nullable: Optional action button URL. Must be an absolute HTTP or HTTPS URL with up to 2048 characters and informed together with ActionButtonText.
  - `NotifyCustomerWhenPointIsGiven` boolean: If true, the customer is notified when points are granted by this objective. Defaults to false.

## Response `200`

The created custom objective, including its Guid.

- BaseExternalApiResponseOfCreateCustomObjectiveResponse: Standard response envelope used by the External API.
  - `ErrorMessage` string, nullable: Error message returned when the request fails validation or processing. For warnings and successful responses, consumers should usually inspect `Result`, `Code` and `Severity` first.
  - `ErrorCode` integer, nullable: Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use `ApiResponseErrorDescription`.
  - `Result` CreateCustomObjectiveResponse, nullable: Custom objective created through the External API.
    - `Id` integer: Identifier of the objective, the same returned as Id by the objectives list endpoints.
    - `Guid` string, guid: Identifier used to reward customers through POST v1/pvt/Objectives/{guid}/importpoints.
    - `Name` string: Name of the objective.
    - `AmountOfPoints` integer: Amount of points granted each time a customer completes the objective.
    - `Active` boolean: If true, the objective is active and grants points.
    - `CustomerMaxCompletion` integer, nullable: Maximum number of times each customer can be rewarded. Null means no limit.
    - `ShowOnWidgetAndLandingPage` boolean: If true, the objective card is shown on the widget and on the landing page.
    - `IconUrl` string, nullable: Icon shown on the objective card.
    - `CardTitle` string, nullable: Card title.
    - `CardDescription` string, nullable: Card description, after HTML sanitization.
    - `ActionButtonText` string, nullable: Action button text.
    - `ActionButtonUrl` string, nullable: Action button URL.
    - `NotifyCustomerWhenPointIsGiven` boolean: If true, the customer is notified when points are granted by this objective.
    - `CreatedAt` string, date-time, nullable: Creation date (UTC).
  - `Code` string, nullable: Endpoint-specific business code formatted as a two-digit string, such as `03` or `07`. This field is available for success, warning and error outcomes.
  - `CodeName` string, nullable: Symbolic enum name associated with `Code`, such as `CheckoutNotFound`.
  - `Severity` 0 | 1 | 2: 0 = Success 1 = Warning 2 = Error
  - `HasWarning` boolean: Convenience flag that is `true` when `Severity` is `Warning`. Warnings are valid `200 OK` business outcomes and should not be handled as transport or validation errors.
  - `HasError` boolean: Indicates whether the request failed and should be handled as an error response. This flag is reserved for real API errors; warnings must keep this property as `false`.

## Other responses

- `403`: The API credential does not have the permission required by this endpoint.

## Changes

- **2026-11-13** `260edb232133`: 1 info
  - added the non-success response with the status `403`
- **2026-11-10** `6654d6c06d54`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis/changes/v1/pvt/Objectives/custom/post.md)

---

[API](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis.md) - [All operations](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/bonifiq/apis/bonifiq-private-apis/revisions/a43551bf4b5f?raw)
