DSP Reporting API: Integration Guide
As we continue to evolve and improve our systems, we're excited to announce a new reporting endpoint designed to deliver enhanced performance, robust security, and seamless compatibility with ongoing reporting enhancements. This upgrade is a key step toward ensuring a smoother and more efficient experience for all users.
Transitioning to the new endpoint is essential to maintain uninterrupted service, leverage the latest features, and stay aligned with our commitment to cutting-edge reporting capabilities. This guide is your comprehensive roadmap to ensure a smooth migration. It includes step-by-step instructions on everything you need to do:
API Changes
Affected endpoints that are being migrated to the newer endpoint.
Old Endpoints
Endpoint: https://api.rocketfuel.com/2016/reports |
|---|
For instance:
JSON
|
Response:  |
For instance:
JSON
|
Response:  |
Endpoint: https://api.rocketfuel.com/2016/reports/dimensions |
|---|
For instance:
JSON
|
Response:  |
New Endpoints
Endpoint: https://api.dsp.zetaglobal.net/report |
|---|
For instance:
JSON
|
Response:  |
For instance:
JSON
|
Other overall API changes:
Parameter Changes:
Changes to the query parameters, headers, body structure, or authentication methods.
In the old version, the header “X-API-Version: 1” was using version 1.
In the new version, the header is now “X-API-Version: 20”, but we are making it optional to pass it.
The header “x-auth-token" is still the same as the old API endpoint.
Header “Accept” and “Content-Type” are still “application/json”
The /report endpoint is now wrapped into a response
The response is now wrapped into a meta-object, which returns the elapsed time of the query:
Rate Limiting and Throttling:
By default, you can only have 8000 queries per day.
If you reach this maximum, you will get a FORBIDDEN HTTP response with a body stating this issue. Contact your account manager if you wish to have that changed.
Client Actions
Required client actions on your end:
Update API Calls: Update your reporting systems to use the new endpoint as listed in the Appendix section. By default, the API returns network-level data. To filter down to Campaign or Company level, here are the parameters you can use:
company_id: ?company_id=4242
company_id is the advertiser_id
campaign_id: ?campaign_id=4242
Authentication Changes: Current authentication system is compatible with the newer API.
Testing & Validation: Recommend that clients test their integration with the V2 version in a staging or sandbox environment before going live.
Code Adjustments: Here are the adjustments required:
The /report endpoint is now wrapped into a response. Sample available in Appendix 1.
The /schema endpoint is now replacing both /dimensions and /metrics. Sample available in Appendix 2.
Migration Process
Step-by-Step Migration Process:
Backup and Test: Backup current data and configuration, and test V2 in a sandbox environment.
Update Integration: Modify API calls to point to V2.
Perform Dry Run: Run a dry run or staging deployment of the updated integration.
Monitor and Troubleshoot: Monitor the integration in real time and address any issues.
Final Go-Live: Once testing is successful, migrate to production.
Post-Migration Support: For any questions, concerns, or issues encountered pre-migration, during or post-migration, please reach out to the Zeta Account Representative.
FAQs
Question | Answer |
|---|---|
Will the old version be supported during the migration? | Yes, until |
Can I roll back to the old version after migrating to A2? | Older version is supported only until |
What happens if I don’t migrate by the deprecation date? | The old endpoints will be turned off. So you will not be able to access them |
How can I ensure the migration goes smoothly? | Start early to allow enough time to troubleshoot and sync with all internal dependencies |
Contact Information
Contact your Account Manager or create a Service Desk ticket.
Appendices
1. /report endpoint:
You can filter down to the company level or campaign level by adding these parameters at the end of the URL:
?company_id=4242
?campaign_id=4242
Pro-tip: If you do not have the right permissions at the network level, you probably will need to filter down to the company or campaign level.
Sample curl request:
JSON
|
Response:  |
You can import this in postman to test it.
Parameters:
?campaign_id=4242 at the end of the url filters down by campaign
?company_id=22 filters down by company
Required Fields: In the JSON parameter body, you enter the required fields: start and end dates, a currency, a time zone, and the metrics and dimensions.
Optional fields: filters, limit, sortBy, and sortOrder.
2. /schema endpoint:
Sample curl request:
JSON
|
Response: It will return the list of metrics and dimensions for your user, according to what you put in the url parameter network level (no param), company level (?company_id=XXX), or campaign level (campaign_id=XXX). You can pick and choose what you want to use. The response will be formatted as shown below:
CODE
|
3. Error Handling
Most errors are very explicit in the response body. The system follows REST framework. For instance, if you pass a wrong metric, you will get a 400 BAD REQUEST:
{
"message": "Unknown metric 'foo_bar'"
} If your JWT is expired, you will get a 401 UNAUTHORIZED:
{
"message": "Failed to parse Auth token. jwt expired",
"errors": [
{
"path": "/report",
"message": "Failed to parse Auth token. jwt expired"
}
]
}