Skip to main content
POST
Creates a custom objective.

Authorizations

Authorization
string
header
required

Use API Basic Auth Keys

Body

application/json

Custom objective data.

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 | null

Name of the objective. Required, up to 100 characters.

AmountOfPoints
integer<int32>

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<int32> | null

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 | null

Optional icon shown on the objective card. Must be an absolute HTTPS URL with up to 2048 characters.

CardTitle
string | null

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 | null

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 | null

Optional action button text, up to 10 characters. Must be informed together with ActionButtonUrl.

ActionButtonUrl
string | null

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 - application/json

The created custom objective, including its Guid.

Standard response envelope used by the External API.

ErrorMessage
string | null

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<int32> | null

Legacy numeric error code derived from internal API errors when available. This field is relevant only for error flows that use ApiResponseErrorDescription.

Result
object | null

Business payload returned by the endpoint.

Code
string | null

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 | null

Symbolic enum name associated with Code, such as CheckoutNotFound.

Severity
enum<integer>

Final severity of the response. Success means the action completed as expected, Warning means the request was valid but the business outcome is informational or non-ideal, and Error means the request should be treated as a failure.

Available options:
0,
1,
2
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.