Connecting To Choozle's Reporting API

Getting Started

This API is a connection to our servers that allows two applications  to talk to each other by sending requests and receiving responses, specifically about campaign information and metrics you see in our platform view. Keep in mind this is not high definition reporting.  Think of it as a way for a program to see our campaign dashboard screen in a way it can understand it.

For starters, the ORG admin or advertiser admin will need to create a API profile/username for the respective account(s). Once an API username is created, the system will generate an API secret key. Illustrated below is how to create an API login. 

NOTE: API Only access: Full access to account data through the API, including campaign and ad group reporting data. An API Only user cannot view, edit, or otherwise access the account from the website. Please Note: If you use a Google hosted email, you can use an alias by adding a "+" after your email address name (e.g. user+api@choozle.com) and it will still go to user@choozle.com, but be recognized as a separate address.

Here is our API documentation:  https://app.choozle.com/apidoc/

1. Authorization - GET Authorization Token

First step in connecting to Choozle's API is authorizing your credentials to avoid unknown and untrusted users from accessing your data and any sensitive campaign information.  This is created using your email addresses associated with your API profile, timestamp,  and your API secret key.  This information is then used to create a token by concatenating the submitted email and timestamp parameters. Hash the token signature using  HMAC-SHA256. This will print the hashed value required for the signature section. If you need assistance in producing any of these fields please reach out to your account manager or support center.

• Ensure the parameters are placed in the BODY - not the Header of the API call
• Declare in the header is Content-Type: application/x-www-form-urlencoded
• Make sure the hashed signature is in 'hex' format, not HEX or base64.  

Here is what a request might look like in postman(download here: https://www.getpostman.com/):

If done properly, you should get a response like this:

Use this token in the header for any future GET calls – keeping in mind the token is only good for 2 hours from creation. After that, you will need to generate a new token using the above script.

If there's not a specific language you're using  to generate your auth token, then we recommend using PHP or Python.  Plug in your email and API secret key into the script and then it will return a valid timestamp and Signature, which will then be used in your call request - https://app.choozle.com/apidoc. 

2. Reporting - Get Account information

Using a GET https://app.choozle.com/api/accounts and setting API Header parameter token: - you can retrieve a response that lists applicable account information:

 

Using the information retrieved in the prior step - you'll be able to GET reporting information. Be sure to keep the setting in your API Header parameter token: . Your API call might look something like this in postman: 

https://app.choozle.com/api/reports?account_id=8737&date_start=2023-01-16&end_date=2023-02-16

Common Troubleshooting Issues

• Hashing signature is in incorrect format – need to be HMAC SHA256 hex, not HEX or base64
• Content Type may need to be declared as application/x-www-form-urlencoded
• POST calls always need to have body parameters (NOT header)
• When requesting reports – optional filtering is done via query parameters in the GET request URL
  • https://app.choozle.com/api/reports?account_id=85&date_start=2017-12-11&date_end=2017-12-11&ad_group_id=42506,42507,42508,41194 

If you need additional assistance connecting to Choozle's API please contact your account manager or reach out to the support center.