Create a Vendor

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 methodPOST
PaginationNA
Rate limitNA
Batch supportNA

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*StringUnique name for the vendor. The maximum character limit is 255.
codeStringUnique 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*LongUnique brand ID of the organisation. This value must be greater than 0.
type*EnumType of vendor. Supported value: REWARDS
imagesObjectObject containing details of images associated with the vendor. You can add up to 5 images for a vendor. Any image format is supported.
- name*StringUnique name identifier for the image.
- altTextStringDescriptive text that conveys the meaning and context of the image.
- idStringUnique 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.
- urlStringDirect link to the image. If isExternal is true, then this parameter is required.
- isExternalBooleanIndicate if the image is from an external source.
videosObjectObject containing details of videos associated with the vendor. You can add up to 2 videos for a vendor.
- name*StringUnique name identifier for the video.
- altTextStringDescriptive text that conveys the meaning and context of the video.
- idStringUnique 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.
- urlStringDirect link to the video. If isExternal is true, then this parameter is required.
- isExternalBooleanIndicate if the video is from an external source.
rankIntegerAssign a rank to the vendor. This can be used for ordering and prioritizing. This value must be greater than 0.
descriptionStringDescription for the vendor. The maximum character limit is 1034.

Response body

{
  "status": {
    "success": true,
    "code": 5002,
    "message": "Vendor created successfully"
  },
  "vendor": {
    "id": 55,
    "name": "DocVendor3",
    "brandId": 61,
    "enabled": true,
    "isEncryptionRequired": false,
    "vendorTypes": null,
    "vendorDetails": null,
    "type": "REWARDS",
    "rank": 1,
    "code": "Doc003",
    "description": "description",
    "images": null,
    "videos": null,
    "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

ParameterDescription
statusObject containing details about the status of the request.
- successIndicates whether the request was successful.
true: Request was successful.
false: Request was unsuccessful.
- codeStatus code of the request.
- messageStatus message of the request.
vendorObject containing details on the vendor that is created.
- idUnique ID generated for the vendor upon successful creation.
- nameUnique name of the vendor.
- brandIdUnique brand ID of the organisation.
- enabledIndicates if the vendor is currently enabled or disabled.
true: Vendor is enabled.
false: Vendor is disabled.
- isEncryptionRequiredIndicates if the vendor requires encryption.
true: Vendor requires encryption.
false: Vendor does not require encryption.
- vendorTypesType 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
- vendorDetailsObject containing details on the vendor, if any.
- typeType of vendor. Possible value: REWARDS
- rankRank assigned to the vendor. This can be used for ordering and prioritizing.
- codeUnique identification code of the vendor.
- descriptionDescription for the vendor.
- imagesObject containing details on the images for the vendor, if any.
- videosObject containing details on the videos for the vendor, if any.
- encryptionRequiredIndicates if encryption is required for transactions with the vendor.
true: Vendor requires encryption.
false: Vendor does not require encryption.

API error codes

CodeDescriptionReason
5007Vendor already existsVendor with the same name already exists.
3004Brand not foundbrandId provided is invalid.
400Cannot 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.
400rank must be greater than zeroValue for rank provided is 0.
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!