A vendor is an external third-party brand that you can use to fulfil your rewards. This API allows you to define vendor details, add images and videos, and display them in your reward catalogue.

👍
Note
For detailed information about our APIs and for hands-on testing, refer documentation in API overview and step-by-step guide on making your first API call in Make your first API call .

Prerequisites

Authentication: Basic/OAuth authentication
Default access group

Resource information


URI	/api_gateway/rewards/core/v1/vendor/create
HTTP method	POST
Pagination	NA
Rate limit	NA
Batch support	NA

API endpoint example

https://eu.api.capillarytech.com/api_gateway/rewards/core/v1/vendor/create

Request body

{
    "name": "DocVendor",
    "code": "Doc001",
    "brandId": 61,
    "type": "REWARDS",
    "rank": 1,
    "description": "The top priority vendor"
}

{
    "name": "DocVendor2",
    "code": "Doc002",
    "brandId": 61,
    "type": "REWARDS",
    "images": [
        {
            "name": "imageName001",
            "altText": null,
            "id": "Img1",
            "isExternal": false
        }
    ],
    "videos": [
        {
            "name": "videoName001",
            "altText": null,
            "id": "Vid1",
            "isExternal": false
        }
     ],
    "rank": 1,
    "description": "The top priority vendor"
}

{
    "name": "DocVendor3",
    "code": "Doc003",
    "brandId": 61,
    "type": "REWARDS",
    "images": [
        {
            "name": "imageName001",
            "altText": null,
            "url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcS6RFSqYEgenJSDc0Wo_eoEKzxd0iXvTOO-LQ&s",
            "isExternal": true
        }
    ],
    "videos": [
        {
            "name": "videoName001",
            "altText": null,
            "url": "https://videos.pexels.com/video-files/6265096/6265096-uhd_1440_2560_30fps.mp4",
            "isExternal": true
        }
    ],
    "rank": 1,
    "description": "The top priority vendor"
}

Request body parameters

Parameter (Parameters marked with * are mandatory)	Data Type	Description
name*	String	Unique name for the vendor. The maximum character limit is 255.
code	String	Unique identification code for the vendor. A random, unique code is assigned to the vendor if the code is null or not provided. The maximum character limit is 255.
brandId*	Integer	Unique brand ID of the organisation. This value must be greater than 0.
type*	Enum	Type of vendor. Supported value: `REWARDS`
images	Object	Object containing details of images associated with the vendor. You can add up to 5 images for a vendor. Any image format is supported.
- name*	String	Unique name identifier for the image.
- altText	String	Descriptive text that conveys the meaning and context of the image.
- id	String	Unique ID that is generated when an image is created. This ID is the `file_handle` for the associated image in the Capillary system. If `isExternal` is false, then this parameter is required. To add an image, to the file service location raise a ticket to the support team.
- url	String	Direct link to the image. If `isExternal` is true, then this parameter is required.
- isExternal	Boolean	Indicate if the image is from an external source.
videos	Object	Object containing details of videos associated with the vendor. You can add up to 2 videos for a vendor.
- name*	String	Unique name identifier for the video.
- altText	String	Descriptive text that conveys the meaning and context of the video.
- id	String	Unique ID that is generated when a video is created. This ID is the `file_handle` for the associated video in the Capillary system. If `isExternal` is false, then this parameter is required. To add a video to the file service location, raise a ticket to the support team. Any video format is supported.
- url	String	Direct link to the video. If `isExternal` is true, then this parameter is required.
- isExternal	Boolean	Indicate if the video is from an external source.
rank	Integer	Assign a rank to the vendor. This can be used for ordering and prioritizing. This value must be greater than 0.
description	String	Description for the vendor. The maximum character limit is 1034.

Response body

{
    "status": {
        "success": true,
        "code": 5002,
        "message": "Vendor created successfully"
    },
    "vendor": {
        "id": 145,
        "name": "vendorRedemptionCrete",
        "brandId": 61,
        "enabled": true,
        "isEncryptionRequired": false,
        "vendorTypes": null,
        "vendorDetails": null,
        "type": "REWARDS",
        "createdBy": 75161973,
        "lastUpdatedBy": 75161973,
        "createdOn": 1748350401000,
        "lastUpdatedOn": 1748350401000,
        "createdOnDateTime": "2025-05-27T12:53:21Z",
        "lastUpdatedOnDateTime": "2025-05-27T12:53:21Z",
        "rank": 20,
        "code": "17447980",
        "description": "test description for test_Rewards_createAndGetVendorsWithMediaAndAdditionalMeta",
        "images": [],
        "videos": [],
        "encryptionRequired": false
    }
}

{
  "status": {
    "success": false,
    "code": 400,
    "message": "Cannot deserialize value of type com.capillary.solutions.rewards.domain.Type from String \"REWARD\": value not one of declared Enum instance names: [POINTS, REWARDS]"
  }
}

{
  "status": {
    "success": false,
    "code": 400,
    "message": "rank must be greater than zero"
  }
}

{
    "status": {
        "success": false,
        "code": 3004,
        "message": "Brand not found"
    }
}

{
    "status": {
        "success": false,
        "code": 5007,
        "message": "Vendor already exists"
    },
    "vendor": null
}

Response parameters

Parameter	Description
status	Object containing details about the status of the request.
- success	Indicates whether the request was successful. `true`: Request was successful. `false`: Request was unsuccessful.
- code	Status code of the request.
- message	Status message of the request.
vendor	Object containing details on the vendor that is created.
- id	Unique ID generated for the vendor upon successful creation.
- name	Unique name of the vendor.
- brandId	Unique brand ID of the organisation.
- enabled	Indicates if the vendor is currently enabled or disabled. `true`: Vendor is enabled. `false`: Vendor is disabled.
- isEncryptionRequired	Indicates if the vendor requires encryption. `true`: Vendor requires encryption. `false`: Vendor does not require encryption.
- vendorTypes	Type of vendor. These are specialized vendor types for which we have implemented customized solutions in our system to handle reward issuance. Supported types: LINKAJA/AIRSPRING/OVO/BONUSLINK
- vendorDetails	Object containing details on the vendor, if any.
- type	Type of vendor. Possible value: `REWARDS`
- rank	Rank assigned to the vendor. This can be used for ordering and prioritizing.
- code	Unique identification code of the vendor.
- description	Description for the vendor.
- images	Object containing details on the images for the vendor, if any.
- videos	Object containing details on the videos for the vendor, if any.
- encryptionRequired	Indicates if encryption is required for transactions with the vendor. `true`: Vendor requires encryption. `false`: Vendor does not require encryption.
lastUpdatedOn	Indicates the timestamp when the vendor redemption was updated. The timestamp is in Epoch time format.
lastUpdatedBy	The till ID of the user who last updated the vendor redemption record.
createdBy	The till ID of the user who created the vendor redemption.
createdOn	Indicates the timestamp when the vendor redemption was created. The timestamp is in Epoch time format.
createdOnDateTime	Indicates the date and time when the vendor redemption was created, formatted in ISO 8601.
lastUpdatedOnDateTime	Indicates the date and time when the vendor redemption was updated, formatted in ISO 8601.

API error codes

Code	Description	Reason
5007	Vendor already exists	Vendor with the same name already exists.
3004	Brand not found	`brandId` provided is invalid.
400	Cannot deserialize value of type com.capillary.solutions.rewards.domain.Type from String "REWARD": value not one of declared Enum instance names: [POINTS, REWARDS]	`type` is invalid.
400	rank must be greater than zero	Value for `rank` provided is 0.

Create a Vendor

👍
Note

Prerequisites

Resource information

API endpoint example

Request body

Request body parameters

Response body

Response parameters

API error codes

👍Note

Prerequisites

Resource information

API endpoint example

Request body

Request body parameters

Response body

Response parameters

API error codes

👍
Note