Tracking Usage with mdGroupId

Tracking Usage with mdGroupId#

mdGroupId is an optional, user-defined value that associates each request with a specific group, such as a department, business unit, application, or environment. It allows you to view usage broken down by group in the Usage Report.

Requirements#

  • Maximum unique mdGroupIds: 20 per account. Once this limit is reached, requests using additional new mdGroupId values are still counted in your total usage but are not tracked.

  • Maximum length: 30 characters. Values longer than 30 characters are truncated.

  • Allowed characters: Letters, numbers, dashes (-), and periods (.).

  • Recommended: Use letters and numbers for your mdGroupId values.

Important Notes#

  • mdGroupId values should represent reusable groupings rather than unique per-request values such as transaction IDs, GUIDs, or timestamps.

  • Requests that do not include an mdGroupId are still included in your overall usage but are not assigned to a specific group in the mdGroupId usage breakdown.

Example#

Say you want to track usage separately for three groups: Sales, Marketing, and Engineering. You can use the same license key for all requests while passing a different mdGroupId for each group.

For example, you could use numeric values as mdGroupIds and maintain your own mappings to internal groups.

mdGroupId

Internal Group

1

Sales

2

Marketing

3

Engineering

In your requests you would use:

  • Sales request: t={"mdGroupId": "1"}

  • Marketing request: t={"mdGroupId": "2"}

  • Engineering request: t={"mdGroupId": "3"}

Your Usage Report can then show:

  • 1: 500 records

  • 2: 100 records

  • 3: 200 records

  • Total Usage: 800 records

How to Use mdGroupId#

mdGroupId should be added to the TransmissionReference request field. This is a request-level field, and its value is passed through to the TransmissionReference response field.

For mdGroupId to be recognized, you must use the following syntax within the TransmissionReference field.

Request Type

Syntax

GET Requests

t={"mdGroupId": "Sample-ID"}

POST Requests

"TransmissionReference": "{\"mdGroupId\": \"Sample-ID\"}"

mdGroupId Usage Reporting#

mdGroupId tracking begins the first time you include an mdGroupId in a request. Usage from before that point cannot be broken down by group.

Your standard Usage Report always reflects your complete usage, whether or not an mdGroupId is provided.