This API allows you to issue badges for customers in bulk.

⚠️
Important
The badgeMetaId you provide must exist in the target organization's context. If you use a badgeMetaId from a different organization, the import will fail and return error code 1054 (GLOBAL.BADGE_NOT_FOUND).

👍
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.

Example request

curl --location 'https://eu.api.capillarytech.com/api_gateway/v1/badges/import/customerBadges' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic bWFkajU2YQ==' \
--header 'Cookie: _cfuvid=S8HjBH10RqTfOhguIBzGFsmmDRCu5LYrozbGHbzkPBE-1768884697575-0.0.1.1-604800000; _cfuvid=a29kRC1YIK1I8Q7ExG3CuyWB_.cTY7mz9Ldi1R5GmdU-1769693039796-0.0.1.1-604800000' \
--data '[
   {
       "badgeMetaId": "696f0fd40772ad476ecf74ac",
       "customerId": 555567088
       "earnExpiresOn": 1705828011
  },
   { 
   "badgeMetaId": "697a16140772ad476ecfe51c", 
   "customerId": 12098734, 
   "earnEventDate": 1635792000,
   "earnEventDateISO":"2025-09-10T15:00:00+05:30" 
   "earnExpiresOn": 1667328000
   "earnExpiresOnISO":"2022-11-02T00:10:00+05:30"
   }
]'

Prerequisites

Authentication: Basic or OAuth authentication
Default access group

Resource information


URI	api_gateway/v1/badges/import/customerBadges
HTTP method	PUT
Batch support	NA

Request body parameter

Parameter	Data Type	Description
badgeMetaId*	String	Unique identifier ("id") generated during the creation of the badge. The badgeMetaId must exist in the target organization's context. Using a badgeMetaId from a different organization will result in an error.
customerId*	Integer	Unique identifier for the customer.
earnEventDate*	Date	Timestamp of when the earning event occurred, in epoch milliseconds time format.
earnEventDateISO	String	Timestamp of when the earning event occurred, in the ISO 8601 standard format with the region offset. For example, The earning event occurred at 15:00:00 on September 10, 2025, in India. Format for the request parameter: 2025-09-10T15:00:00+05:30
earnExpiresOn*	Date	Timestamp of when the earned item expires, in epoch milliseconds time format.
earnExpiresOnISO	String	Timestamp of when the earned item expires, in the ISO 8601 standard format with the region offset. For example, The earned item expires at 15:00:00 on September 10, 2025, in India. Format for the request parameter: 2025-09-10T15:00:00+05:30

Example response

[
    {
        "data": {
            "badgeMetaId": "696f0fd40772ad476ecf74ac",
            "customerId": 555567088,
            "earnedBadgeId": "697b5f6f0772ad476ecff272",
            "expiresOn": 1705828011.000000000,
            "expiresOnISO": "2024-01-21T09:06:51Z",
            "requestId": "d9e144be-2450-4300-892f-798f9bb68ce2_1",
            "issuedId": null
        },
        "errors": null,
        "warnings": null
    },
    {
        "data": {
            "badgeMetaId": "697a16140772ad476ecfe51c",
            "customerId": 12098734,
            "earnedBadgeId": "697b5f6f0772ad476ecff275",
            "expiresOn": 1667328000.000000000,
            "expiresOnISO": "2022-11-01T18:40:00Z",
            "requestId": "d9e144be-2450-4300-892f-798f9bb68ce2_2",
            "issuedId": null
        },
        "errors": null,
        "warnings": null
    }
]

Response parameter

Parameter	Data Type	Description
badgeMetaId	String	Unique identifier for the badge metadata
customerId	Integer	Unique identifier for the customer
earnedBadgeId	String	Unique identifier for the earned badge
expiresOn	Float	Timestamp of when the badge or item expires
expiresOnISO	String	Timestamp of when the badge or item expires in ISO 8601 format, returned in the server time zone. EU server example 2025-09-10T15:00:00Z → 10 September 2025, 15:00:00 (UTC) India server example 2025-09-10T15:00:00+05:30 → 10 September 2025, 15:00:00 (IST) Note: The response time zone always matches the server time zone, regardless of the time zone offset in the request.
requestId	String	Unique identifier for the request
issuedId	String	A Unique identifier representing the specific issuance instance of the badge.
errors	Null/Object	Container for any errors (null if no errors). If you use a badgeMetaId that does not exist in the target organization, the response will include error code 1054 (GLOBAL.BADGE_NOT_FOUND).
warnings	Null/Object	Container for any warnings (null if no warnings)

200200

400400