Please note the current NinjaCat Agency Management Open API is in the Beta stage.

The purpose of the NinjaCat Agency Management Open API is to allow developers to interact with their NinjaCat Agency’s data through direct API access and not through the normal user interface. This is achieved through a request & response interchange between applications. A sample use case would be if an agency needs to quickly create a large number of users to their agency, instead of going through the UI to invite users one by one, a mass add can easily be done with this API. This article provides a brief summary of the API's features. Detailed developer documentation is available.

NinjaNote: Use of this feature requires a user account with access to the setup settings, and access to an area of the setup settings that can only be granted by a NinjaCat team member. Contact a NinjaCat team member and request access to the "APPS" tab in the setup settings.

Section Links

Access Credentials and Documentation

Authentication

NinjaCat SSO (Single Sign-On)

Agency Management Open API Features

Access Credentials and Documentation

1. Go to the Setup Settings

2. Click on "Agency Settings" in the sub-navigation

3. Click on the "Apps" tab under Agency Settings

Authentication

This method allows you to get back an access token for authentication purposes when making requests in this API. You will need an Agency Identifier Key, Client Id, and Client Secret that is found in NinjaCat under the agency setting screen in the Apps Tab. If you don’t see this Apps tab, please contact your NinjaCat Account manager to request this feature. For more detailed information on this API feature view the more detailed article.

NinjaCat SSO (Single Sign-On)

Once you have obtained the above authentication to make requests through this API you can use a combination of Agency Management features to control customized, programmatic access to the NinjaCat Platform. Click for more detailed information and links to the developer documentation.

Agency Management Open API Features

The functions of the Agency Management Open API are as follows:

• Agency User - allows you to add a new agency user - Fields available for edit:

  • username : The username that is used to login to NinjaCat

  • email : The email for this user

  • name : The actual name of this user

  • password : The password for this user

  • all_advertisers : Determine if this user has access to all the accounts for this agency

  • roleIds : Determine what role does this user have

  • advertiserIds : Determine what accounts this user has access to (if not set to all)

  • is_visible : Determine if this user is visible in the user list screen in NinjaCat

  • meta_data : additional information you want to put in for this user

• Advertiser User - This method allows you to add a new advertiser user. NinjaNote: This is the only operation where you can assign which account this advertiser belongs to. - Fields available for edit:

  • username : The username that is used to login to NinjaCat

  • email : The email for this user

  • name : The actual name of this user

  • password : The password for this user

  • advertiserId : The advertiser associated with this account

  • meta_data : additional information you want to put in for this user

• Role - This method allows you to add a new role. NinjaNote: To learn more about user roles check out the article titled; Creating and Customizing User Roles. - Fields available for edit:

  • name : The name of the Role

  • description : Description of the Role

  • permissionIds : A list of permission that the role has access to

• Advertiser - This method allows you to add a new advertiser account - Fields available for edit:

  • name : Name of this advertiser/account

  • phone : Phone of this advertiser/account

  • company : Company name of this advertiser/account

  • email : Primary email for this advertiser/account

  • website : Website for this advertiser/account

  • external_id : A external id that is used for matching custom data sources

  • owner_id : An id of an agency user that owns this advertiser/account

  • facebook_campaigns : A comma-separated list of Facebook campaigns to filter out when getting data for this advertiser/account for reports and dashboards

  • custom_field : This is used for the custom field place holder found in reporting’s email template

  • account_custom_field_values : This field is used to update account groups for this advertiser.

• Permissions - This method allows you to get back a list of permission that is available for your agency - Fields available for edit:
  • id : The id of the permission, this is used to set what permission a role has
  • name : Name of the permission
  • description : Description of what the permission does
• Login - The Login resource only has one operation and that is to create a login link for either an advertiser user or an agency user. This is to simulate automatically login for a user if you choose to link a user account between NinjaCat and your system
• Network - This method will get back a list of networks/data sources that are found in your agency
• Report - This method will get back a list of reports within your agency - Fields available for edit:

  • id : The unique id of this report

  • advertiser_id : The id of the advertiser the report belongs to

  • name : A user-friendly name for the report

  • completed_at : The timestamp at which the report was last run

  • date_range : The date range of time for which the report was last run

  • download_url : The URL from which the report can be retrieved

  • status : The status of the last report run

  • errors : An array of error messages from the last report run, if any

• Advertiser Network - This method allows you to add a new advertiser network/data source

  • advertiser_id : The advertiser id that indicates which advertiser this network belongs to

  • network_id : The id of the actual data source connection

  • network_definition_id : A read-only field that indicates the type of data source this is

  • network_account_id : A unique identifier that determines which account to use for an agency network data source

  • is_primary : Determine if this is the primary advertiser network to be used

  • sheet_mapping : The mapping id that is being used for this advertiser network

  • external_advertiser_id : The advertiser id that is set to use for filtering on special custom data sources

  • earliest_reporting_date : A Datetime field to indicate the earliest data to pull for reporting and dashboards

  • latest_reporting_date : A Datetime field to indicate the latest data to pull for reporting and dashboards

• Custom Field - allows you to add a new Account Group field
• Custom Field Value - allows you to add a new Account Group value - Fields available for edit:

  • name : The name of the Custom Field Value

  • custom_field_id : The id of a custom field (Account Group) this value belongs to

  • advertiserIds : A list of ids for advertisers that have this Custom Field Value (Account Group Value) assigned to them