Learn more:

• CP Codes and Reporting Groups Tool

• Download this API’s RAML and JSON schema descriptors.

Overview

The CP Codes and Reporting Groups API offers a programmatic interface to manage CP codes and reporting groups. It also details contracts and products associated with each CP code, and contracts and CP codes associated with each reporting group. Knowing these associations lets you break down your invoices and reports by reporting groups rather than by contracts or products only. You can sort and retrieve CP code and reporting group details available in your contract using either a CP code or reporting group ID.

The CP Code and Reporting Group API lets you:

• List and update CP codes. Note: If you want to create CP codes, use the Property Manager API which automatically assigns them to the correct product and contract. CP code deletion is unavailable at this time.

• Create, delete, list, and update reporting groups.

Who should use this API

Developers, DevOps, and operations personnel use this API as an alternative to using Control Center.

Getting started

To configure this API for the first time:

• First review Get Started with APIs to learn how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this: https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net.

• To enable this API, choose the API service named CPcode and Reporting group (CPRG), and set the access level to READ WRITE.

• To use this API, you need to add one of the following roles:

  • CP Code - Edit CP Code Information

  • CP Code - View CP Code Information

  • CPCode Rep Group - All privileges

  • CPCode Rep Group - Edit/View

  Use the Identity and Access Management application. You can also add these roles programmatically with the Identity Management: User Administration API.

• To use this API, you need to have a READ access level to the Property Manager API.

Concepts

You deal with various conceptual objects when interacting with the CP Codes and Reporting Group API.

• Account. An account key that Akamai customers use to access all their services. While administrators may have access to more than one account, in general they provision all their web assets under a single account.

• Contract. The level of access that depends on the contracts associated with your Control Center username. If your username is not associated with the contractId you select, then the request fails. Each account features one or more contracts, each of which has a fixed term of service during which specified Akamai products and modules are active.

• Reporting group. A Logical grouping of content provider (CP) codes that consolidates billing for a contract. Without reporting groups, reports in the Billing Center are broken down by contracts and products only.

• Content Provider (CP) code. A unique identifier assigned to each customer to track and report on a set of traffic served over the Akamai network. It is primarily used for billing, reporting, and access control. A customer and a single contract may each have multiple CP codes.

• High water mark limit. By default, the maximum number of CP codes or reporting groups allowed for an account. Usually, all contracts associated with an account share the account’s limit, and the total number of objects created in all associated contracts don’t exceed the account’s limit. For example, you can split 100 CP codes in total among all contracts associated with an account having a 100 CP code limit. Note that high water mark limit may also refer to the maximum number of CP codes or reporting groups allowed for a contract if the contract’s limit overrides its account limit. An overridden contract’s limit is a separate limit that isn’t affected by the account’s limit constraint. To increase the account or contract limit, contact your account representative.

How to use water mark limits

Example 1:

In the first example, neither of the contracts overrides their account limit. This means that you can add 100 CP codes in total to the contracts under this account. In this case, you are left with 30 CP codes to share between the contracts.

Here are the account’s and contract’s water mark limits:

Here are the CP codes added to the associated contracts and the account’s capacity:

Example 2:

In the second example, one of the contracts overrides its account limit. As a result of the override, this contract’s limit is separate from the account’s limit and doesn’t affect its count. This means that you can add 100 CP codes in total to the contracts that share the account’s limit and up to 200 CP codes to the contract that overrides the account’s limit. In this case, you are left with 10 CP codes that you can share between the contracts constrained by the account’s limit (Contract1 and Contract2), and 50 CP codes that you can add to the overridden contract (Contract3).

Here are the account’s and contract’s water mark limits:

Here are the CP codes added to the associated contracts, account’s capacity, and overridden contract’s capacity:

Resources

This section provides details on the API’s various operations.

API summary

Download the RAML descriptors for this API.

List CP codes

This operation lists detailed information about CP codes available within your account and contract paring.

{
    "cpcodes": [
        {
            "cpcodeId": 123456,
            "cpcodeName": "CPC XYZ",
            "purgeable": true,
            "accountId": "act_1-1TGTG",
            "defaultTimezone": "GMT 0 (Greenwich Mean Time)",
            "type": "Regular",
            "overrideTimezone": {
                "timezoneId": "0",
                "timezoneValue": "GMT 0 (Greenwich Mean Time)"
            },
            "accessGroup": {
                "groupId": 9760,
                "contractId": "ctr_004W"
            },
            "contracts": [
                {
                    "contractId": "ctr_004W",
                    "status": "ongoing"
                }
            ],
            "products": [
                {
                    "productId": "AdvSite::Reporter",
                    "productName": "Monitor site advance"
                }
            ]
        },
        {
            "cpcodeId": 67890,
            "cpcodeName": "CPC SME",
            "purgeable": true,
            "accountId": "act_1-1TGTG",
            "defaultTimezone": "GMT 0 (Greenwich Mean Time)",
            "type": "Regular",
            "overrideTimezone": {
                "timezoneId": "0",
                "timezoneValue": "GMT 0 (Greenwich Mean Time)"
            },
            "accessGroup": {
                "groupId": 9760,
                "contractId": "ctr_004W"
            },
            "contracts": [
                {
                    "contractId": "ctr_004W",
                    "status": "ongoing"
                }
            ],
            "products": [
                {
                    "productId": "Dev::Cloud",
                    "productName": "Cloud development CD"
                }
            ]
        }
    ]
}

List details of a CP code

This operation lists detailed information about a specific CP code, including its type, name, time zone, and the account it’s assigned to. It also lists the access control group that the CP code belongs to and the contracts and products assigned to this CP code.

{
    "cpcodeId": 123456,
    "cpcodeName": "CPC XYZ",
    "purgeable": true,
    "accountId": "act_1-1TGTG",
    "defaultTimezone": "GMT 0 (Greenwich Mean Time)",
    "type": "Regular",
    "overrideTimezone": {
        "timezoneId": "0",
        "timezoneValue": "GMT 0 (Greenwich Mean Time)"
    },
    "accessGroup": {
        "groupId": 9760,
        "contractId": "ctr_004W"
    },
    "contracts": [
        {
            "contractId": "ctr_004W",
            "status": "ongoing"
        }
    ],
    "products": [
        {
            "productId": "AdvSite::Reporter",
            "productName": "Monitor site advance"
        }
    ]
}

Update a CP code

This operation allows you to modify a specific CP code. You should only modify a CP code’s name, time zone, and purgeable member.

{
    "cpcodeId": 123456,
    "cpcodeName": "CPC XYZ",
    "contracts": [
        {
            "contractId": "ctr_004W"
        }
    ],
    "products": [
        {
            "productId": "PPPL::ABC"
        },
        {
            "productId": "AdvSite::Reporter"
        }
    ]
}

{
    "cpcodeId": 123456,
    "cpcodeName": "CPC XYZ",
    "purgeable": true,
    "accountId": "act_1-1TGTG",
    "defaultTimezone": "GMT 0 (Greenwich Mean Time)",
    "type": "Regular",
    "overrideTimezone": {
        "timezoneId": "0",
        "timezoneValue": "GMT 0 (Greenwich Mean Time)"
    },
    "accessGroup": {
        "groupId": 9760,
        "contractId": "ctr_004W"
    },
    "contracts": [
        {
            "contractId": "ctr_004W",
            "status": "ongoing"
        }
    ],
    "products": [
        {
            "productId": "Core::Analyzer",
            "productName": "Core utility JL"
        }
    ]
}

List water mark limits for CP codes

This operation lists a water mark limit for CP codes for the account associated within a specific contract.

{
    "limit": 5000,
    "currentCapacity": 3500,
    "limitType": "account"
}

List reporting groups

This operation lists detailed information about reporting groups available within your account and contract paring.

{
    "reporting-groups": [
        {
            "reportingGroupId": 101010,
            "reportingGroupName": "Region XYZ",
            "accessGroup": {
                "groupId": 9760,
                "contractId": "ctr_1Q004"
            },
            "contracts": [
                {
                    "contractId": "ctr_1Q004",
                    "cpcodes": [
                        {
                            "cpcodeId": 12345,
                            "cpcodeName": "CPC XYZ"
                        }
                    ]
                }
            ]
        },
        {
            "reportingGroupId": 101011,
            "reportingGroupName": "Region gLobal XYZ",
            "accessGroup": {
                "groupId": 9760,
                "contractId": "ctr_1Q0042"
            },
            "contracts": [
                {
                    "contractId": "ctr_1Q004",
                    "cpcodes": [
                        {
                            "cpcodeId": 67890,
                            "cpcodeName": "CPC SME"
                        },
                        {
                            "cpcodeId": 98765,
                            "cpcodeName": "CPC Global"
                        }
                    ]
                }
            ]
        }
    ]
}

Create a reporting group

This operation allows you to create a reporting group. The reporting group’s name must be unique within an account. The location header in the response provides a relative path to the created reporting group.

{
    "reportingGroupName": "Region XYZ",
    "accessGroup": {
        "groupId": 9760,
        "contractId": "ctr_1Q004"
    },
    "contracts": [
        {
            "contractId": "ctr_1Q004",
            "cpcodes": [
                {
                    "cpcodeId": 12345,
                    "cpcodeName": "CPC XYZ"
                },
                {
                    "cpcodeId": 67890,
                    "cpcodeName": "CPC SME"
                }
            ]
        }
    ]
}

Location: /cprg/v2/reporting-groups/1234

{
    "reportingGroupId": 101010,
    "reportingGroupName": "Region XYZ",
    "description": "Region XYZ",
    "accessGroup": {
        "groupId": 9760,
        "contractId": "ctr_004W"
    },
    "contracts": [
        {
            "contractId": "ctr_004W",
            "cpcodes": [
                {
                    "cpcodeId": 12345,
                    "cpcodeName": "CPC XYZ"
                },
                {
                    "cpcodeId": 67890,
                    "cpcodeName": "CPC SME"
                }
            ]
        }
    ]
}

List details of a reporting group

This operation lists detailed information about a specific reporting group, including its name and the access control group that it belongs to. It also lists the contracts and CP codes assigned to the reporting group.

{
    "reportingGroupId": 101010,
    "reportingGroupName": "Region XYZ",
    "description": "Region XYZ",
    "accessGroup": {
        "groupId": 9760,
        "contractId": "ctr_004W"
    },
    "contracts": [
        {
            "contractId": "ctr_004W",
            "cpcodes": [
                {
                    "cpcodeId": 12345,
                    "cpcodeName": "CPC XYZ"
                },
                {
                    "cpcodeId": 67890,
                    "cpcodeName": "CPC SME"
                }
            ]
        }
    ]
}

Update a reporting group

This operation allows you to modify a specific reporting group. You should only modify a reporting group’s name and assigned CP codes.

{
    "reportingGroupId": 101010,
    "reportingGroupName": "Region XYZ",
    "description": "Region XYZ",
    "contracts": [
        {
            "contractId": "ctr_1Q004",
            "cpcodes": [
                {
                    "cpcodeId": 12345,
                    "cpcodeName": "CPC XYZ"
                },
                {
                    "cpcodeId": 67890,
                    "cpcodeName": "CPC SME"
                }
            ]
        }
    ]
}

{
    "reporting-group": {
        "reportingGroupId": 101010,
        "reportingGroupName": "Region XYZ",
        "description": "Region XYZ",
        "accessGroup": {
            "groupId": 9760,
            "contractId": "ctr_1Q004"
        },
        "contracts": [
            {
                "contractId": "ctr_1Q004",
                "cpcodes": [
                    {
                        "cpcodeId": 12345,
                        "cpcodeName": "CPC XYZ"
                    },
                    {
                        "cpcodeId": 67890,
                        "cpcodeName": "CPC SME"
                    }
                ]
            }
        ]
    }
}

Delete a reporting group

This operation deletes a specific reporting group.

List products within a reporting group

This operation lists products and services assigned to a specific reporting group.

{
    "products": [
        {
            "productId": "PPPL::ABC",
            "productName": "Performance PPL ABC "
        },
        {
            "productId": "Core::Analyzer",
            "productName": "Core utility JL"
        },
        {
            "productId": "Dev::Cloud",
            "productName": "Cloud development CD"
        },
        {
            "productId": "AdvSite::Reporter",
            "productName": "Monitor site advance"
        }
    ]
}

List water mark limits for reporting groups

This operation lists a water mark limit for reporting groups available within a specific contract.

{
    "limit": 100,
    "currentCapacity": 25,
    "limitType": "account"
}

Data

This section provides details for each type of data object the API exchanges.

Download the JSON schemas for this API.

The data schema tables below list membership requirements as follows:

CpCode

Contains the request members that you can specify when updating a CP code. You should only modify a CP code’s name, time zone, and purgeable member. Modifying other members results in a 400 error response and causes the request to fail.

Download schema: update-cpcode-request.json, cpcode.json

Sample PUT request:

{
    "cpcodeId": 123456,
    "cpcodeName": "CPC XYZ",
    "contracts": [
        {
            "contractId": "ctr_004W"
        }
    ],
    "products": [
        {
            "productId": "PPPL::ABC"
        },
        {
            "productId": "AdvSite::Reporter"
        }
    ]
}

CpCode members

ReportingGroup

Provides the request members that you can specify when creating a reporting group.

Download schema: create-reporting-group-request.json, update-reporting-group-request.json, reportinggroup.json

Sample POST request:

{
    "reportingGroupName": "Region XYZ",
    "accessGroup": {
        "groupId": 9760,
        "contractId": "ctr_1Q004"
    },
    "contracts": [
        {
            "contractId": "ctr_1Q004",
            "cpcodes": [
                {
                    "cpcodeId": 12345,
                    "cpcodeName": "CPC XYZ"
                },
                {
                    "cpcodeId": 67890,
                    "cpcodeName": "CPC SME"
                }
            ]
        }
    ]
}

ReportingGroup members

ReportingGroupProducts

Provides information about products and services assigned to a specific reporting group.

Download schema: get-reporting-group-product-response.json

Sample GET response:

{
    "products": [
        {
            "productId": "PPPL::ABC",
            "productName": "Performance PPL ABC "
        },
        {
            "productId": "Core::Analyzer",
            "productName": "Core utility JL"
        },
        {
            "productId": "Dev::Cloud",
            "productName": "Cloud development CD"
        },
        {
            "productId": "AdvSite::Reporter",
            "productName": "Monitor site advance"
        }
    ]
}

ReportingGroupProducts members

WatermarkLimits

Provides information about water mark limits for CP codes or reporting groups available within a specific contract.

Download schema: watermark-limits.json

Sample GET response:

{
    "limit": 5000,
    "currentCapacity": 3500,
    "limitType": "account"
}

WatermarkLimits members

Errors

This section provides details on the data object that reflects the API’s common response to error cases, and lists the API’s range of response status codes for both error and success cases.

Error responses

When you encounter an error, the CP Code and Reporting Groups API responds with HTTP Problem objects that provide details useful for debugging, as in the example below.

{
  "details": [
    {
      "code": "invalid.data",
      "message": "Group name is mandatory"
    }
  ],
  "code": "bad.request",
  "title": "Bad Request",
  "incidentId": "dc2f405e-29d3-4845-a4ac-2f6b4a732aca"
}

HTTP status codes

This section lists the full range of response codes the API may generate.

Last modified: 6/13/2019