Tag

Tags can be applied to customers or suppliers to record context that is relevant to your risk decisions. These endpoints let you retrieve the current tags on customers and suppliers, and also fetch the history of tag changes. Tags can be added or removed through Ravelin API endpoints, by rules, via bulk-tagging operations, or manually in the Ravelin dashboard.

To receive notifications about tag changes made manually in the Ravelin dashboard or by rules, see Tag Updates.

GET api.ravelin.com/v3/tag/customer/:customerId:

Returns the tags currently added to a customer. Tags are returned regardless of whether they were added by a rule, manually in the Ravelin dashboard, or through Ravelin API endpoints.

Request

Example request:

GET https://api.ravelin.com/v3/tag/customer/abc-123-ZYZ HTTP/1.1
Authorization: token ...
Accept: application/json

Response

Show all
customerId string

The unique identifier of the customer.

tags array

The tags that are currently attached to the customer.

Show definition 
{
  "customerId": "abc-123-ZYZ",
  "tags": [
    {
      "id": "t1",
      "name": "vip",
      "addedAt": 1782136496000
    },
    {
      "id": "t2",
      "name": "staff",
      "addedAt": 1782136400000
    }
  ]
}

GET api.ravelin.com/v3/tag/supplier/:supplierId:

Returns the tags currently added to a supplier. Tags are returned regardless of whether they were added by a rule, manually in the Ravelin dashboard, or through Ravelin API endpoints.

Request

Example request:

GET https://api.ravelin.com/v3/tag/supplier/abc-123-ZYZ HTTP/1.1
Authorization: token ...
Accept: application/json

Response

Show all
supplierId string

The unique identifier of the supplier.

tags array

The tags that are currently attached to the supplier.

Show definition 
{
  "supplierId": "abc-123-ZYZ",
  "tags": [
    {
      "id": "t1",
      "name": "vip",
      "addedAt": 1782136496000
    },
    {
      "id": "t2",
      "name": "staff",
      "addedAt": 1782136400000
    }
  ]
}

GET api.ravelin.com/v3/tag/customer/:customerId:/history

Returns the history of tag changes for a customer, in reverse chronological order. Use the query parameters to page through results and to filter by date.

Query parameters

limit
integer optional

The maximum number of events to return per page.

Defaults to 20. Maximum: 1000.

offset
integer optional

The number of events to skip before returning results.

Defaults to 0.

startDate
string optional

Return only events that occurred on or after this date. The boundary is inclusive. A date in YYYY-MM-DD format, interpreted in UTC. Can be used with or without endDate.

endDate
string optional

Return only events that occurred on or before this date. The boundary is inclusive. A date in YYYY-MM-DD format, interpreted in UTC. Can be used with or without startDate.

Request

Example request:

GET https://api.ravelin.com/v3/tag/customer/abc-123-ZYZ/history?limit=3&offset=6&startDate=2026-04-01&endDate=2026-05-01 HTTP/1.1
Authorization: token ...
Accept: application/json

Response

Show all
meta object

Pagination metadata for the current tag history result set.

Show definition
customerId string

The unique identifier of the customer.

The customer's tag history items, sorted from newest to oldest.

Show definition 
{
  "meta": {
    "count": 10,
    "offset": 6,
    "limit": 3,
    "prev": "/v3/tag/customer/abc-123-ZYZ/history?limit=3&offset=3&startDate=2026-04-01&endDate=2026-05-01",
    "next": "/v3/tag/customer/abc-123-ZYZ/history?limit=3&offset=9&startDate=2026-04-01&endDate=2026-05-01"
  },
  "customerId": "abc-123-ZYZ",
  "tagHistory": [
    {
      "id": "t3",
      "name": "highroller",
      "timestamp": 1777550400000,
      "action": "TAG_ADDED"
    },
    {
      "id": "t2",
      "name": "vip",
      "timestamp": 1777550400000,
      "action": "TAG_ADDED"
    },
    {
      "id": "t1",
      "name": "staff",
      "timestamp": 1777291200000,
      "action": "TAG_REMOVED"
    }
  ]
}

Example requests

  • Fetch the first page of history (default limit of 20):

    GET https://api.ravelin.com/v3/tag/customer/abc-123-ZYZ/history

  • Fetch the second page (skip the first 20 records):

    GET https://api.ravelin.com/v3/tag/customer/abc-123-ZYZ/history?offset=20

  • Fetch 50 records per page:

    GET https://api.ravelin.com/v3/tag/customer/abc-123-ZYZ/history?limit=50

  • Fetch tag events from a specific date onwards:

    GET https://api.ravelin.com/v3/tag/customer/abc-123-ZYZ/history?startDate=2026-01-01

  • Fetch tag events up to a specific date:

    GET https://api.ravelin.com/v3/tag/customer/abc-123-ZYZ/history?endDate=2026-06-30

  • Fetch tag events within a date range:

    GET https://api.ravelin.com/v3/tag/customer/abc-123-ZYZ/history?startDate=2026-01-01&endDate=2026-06-30

  • Combine pagination with date filtering:

    GET https://api.ravelin.com/v3/tag/customer/abc-123-ZYZ/history?startDate=2026-01-01&endDate=2026-06-30&offset=20&limit=10

GET api.ravelin.com/v3/tag/supplier/:supplierId:/history

Returns the history of tag changes for a supplier, in reverse chronological order. Use the query parameters to page through results and to filter by date.

Query parameters

limit
integer optional

The maximum number of events to return per page.

Defaults to 20. Maximum: 1000.

offset
integer optional

The number of events to skip before returning results.

Defaults to 0.

startDate
string optional

Return only events that occurred on or after this date. The boundary is inclusive. A date in YYYY-MM-DD format, interpreted in UTC. Can be used with or without endDate.

endDate
string optional

Return only events that occurred on or before this date. The boundary is inclusive. A date in YYYY-MM-DD format, interpreted in UTC. Can be used with or without startDate.

Request

Example request:

GET https://api.ravelin.com/v3/tag/supplier/abc-123-ZYZ/history?limit=3&offset=6&startDate=2026-04-01&endDate=2026-05-01 HTTP/1.1
Authorization: token ...
Accept: application/json

Response

Show all
meta object

Pagination metadata for the current tag history result set.

Show definition
supplierId string

The unique identifier of the supplier.

The supplier's tag history items, sorted from newest to oldest.

Show definition 
{
  "meta": {
    "count": 10,
    "offset": 6,
    "limit": 3,
    "prev": "/v3/tag/supplier/abc-123-ZYZ/history?limit=3&offset=3&startDate=2026-04-01&endDate=2026-05-01",
    "next": "/v3/tag/supplier/abc-123-ZYZ/history?limit=3&offset=9&startDate=2026-04-01&endDate=2026-05-01"
  },
  "supplierId": "abc-123-ZYZ",
  "tagHistory": [
    {
      "id": "t3",
      "name": "highroller",
      "timestamp": 1777550400000,
      "action": "TAG_ADDED"
    },
    {
      "id": "t2",
      "name": "vip",
      "timestamp": 1777550400000,
      "action": "TAG_ADDED"
    },
    {
      "id": "t1",
      "name": "staff",
      "timestamp": 1777291200000,
      "action": "TAG_REMOVED"
    }
  ]
}

Example requests

  • Fetch the first page of history (default limit of 20):

    GET https://api.ravelin.com/v3/tag/supplier/abc-123-ZYZ/history

  • Fetch the second page (skip the first 20 records):

    GET https://api.ravelin.com/v3/tag/supplier/abc-123-ZYZ/history?offset=20

  • Fetch 50 records per page:

    GET https://api.ravelin.com/v3/tag/supplier/abc-123-ZYZ/history?limit=50

  • Fetch tag events from a specific date onwards:

    GET https://api.ravelin.com/v3/tag/supplier/abc-123-ZYZ/history?startDate=2026-01-01

  • Fetch tag events up to a specific date:

    GET https://api.ravelin.com/v3/tag/supplier/abc-123-ZYZ/history?endDate=2026-06-30

  • Fetch tag events within a date range:

    GET https://api.ravelin.com/v3/tag/supplier/abc-123-ZYZ/history?startDate=2026-01-01&endDate=2026-06-30

  • Combine pagination with date filtering:

    GET https://api.ravelin.com/v3/tag/supplier/abc-123-ZYZ/history?startDate=2026-01-01&endDate=2026-06-30&offset=20&limit=10

Feedback

© Ravelin Technology Ltd. All rights reserved