Skip to main content

NinjaCat Inbound Data

NinjaCat Inbound Data

Daniel
  • Updated

In order to use NinjaCat’s API integration, you need to set up a custom integration and get the unique API Key. Currently, the API integration setup is shared with the Zapier integration so to set up the custom integration you first need to set up a Zapier Network in Ninjacat. This article leads you through the steps and lists the details for the setup and use of the NinjaCat Inbound API.

 

Section Links

Add the Custom Network to NinjaCat

Sending Data to NinjaCat

PHP Code Sample

Create a Mapping

Using API Custom Data in a Template

Error Codes

 

Add the Custom Network to NinjaCat

1. Go to the Setup Settings

2. Click on the "Add Network" button near the top right.

3. Select "Zapier" as the data source

4. Click on the “Connect” button under the Zapier icon

5. Enter a meaningful description for the type of data that you will be creating using this network

6. Click the “Add Network” button near the bottom left

NinjaNote: After clicking on the "Add Network" button the Network Settings window will update with a few new fields. The important field at this point is the "Token" field. It contains an alphanumeric key that you will need to send data to the API.

NinjaNote: If you want to send different types of data, create another data source, and name it appropriately - it will be provided with its own unique API key.

 

Sending Data To NinjaCat

In order to send data to NinjaCat you need 2 things:

  1. The Unique API Key (acquired above)

  2. The name of the account you are sending data to. It must match the name of the

    account in NinjaCat (it is not case-sensitive).

The URL to post data to is:

https://app.ninjacat.io/open_api/zapier_add_data?api_key=​$api_key
NinjaCat will respond with our internal row id which will allow you to update the data later if

necessary.

Consider each post to be a single row of data. So if you want to send 100 rows you will require 100 posts. You should Post Data to that URL with the following parameters:

Parameter Details

date -

This is the date that the data will be associated with. When working on the data in NinjaCat this date field will be used to determine what time frame this data appears in.

Sample: Y-m-d H:i:s E.g.:2001-03-10 17:16:18

client -

This is the name of the Ninjacat Account the data will be associated with. It must match the name exactly - it is not case-sensitive.

One of client or client_external_id must be provided.

Sample: Coca Cola

client_external_id -

This is the value stored in the external id of the Ninjacat Account that the data will be associated with. It can be alphanumeric. It must match the external id exactly - it is not case-sensitive.

One of client or client_external_id must be provided.

Sample: Our ID 123

row_id -

This is the row id to update. It’s an optional parameter, and, if provided, will update the existing row instead of inserting a new record. If the row id is provided and the row is not found then an error will be returned.

data -

This is the data to be reported on. The format is JSON key-value pairs.

Format: {“key”:”value”,”key2”:”value2”} Sample: {“Campaign”:”Brand Value”, “Clicks”:”100”, “Impressions”:”1500”}

You do not need to format any of the metrics. Dimensions can be formatted exactly as you want them to be displayed. You can use ASCII characters to send special displays like \u2193 will display ↓.

 

 

 

PHP Code Sample

This sample uses the php Guzzle library (​http://docs.guzzlephp.org/en/stable/​)

 

$array ​= []; 
$array​[​"impressions"​] = ​5​; 
$array​[​"clicks"​] = ​10​; 

$api_key ​= ​"INSERT YOUR KEY"​;
$url ​= ​"​https://legacy.ninjacat.io/api/zapier_add_data.php?api_key=​$api_key​"​; 

$params ​= ​new ​\stdClass();
$params​->​date ​= Date(​"Y-m-dTh:m:s"​, ​strtotime​(​"now"​)); 
$params​->​client ​= ​"CLIENT NAME"​;
$data ​= ​new ​stdClass();
foreach​(​$array ​as ​$key​=>​$value​){ 
   ​$data​->​$key ​= ​$value​;
} 
$params​->​data ​= ​$data​; 

$options ​= [​"headers" ​=> [​"Content-Type" ​=> ​"application/json"​, ​"Accept" ​=> 
"application/json"​], ​"body" ​=> ​json_encode​(​$params​)]; 
$client ​= ​new ​\GuzzleHttp\Client(); 
$response ​= ​$client​->post(​$url​, ​$options​);

 

Creating a Mapping

1. Go to the Setup Settings

2. Select the new Zapier/Custom API Network you just created in the previous steps

3. Click on "Edit Mapping" near the top right

4. Click on the "Add Mapping" button near the center

FILL IN THE NEEDED INFORMATION IN EACH OF THE REQUIRED TABS

INFORMATION Tab

  • Name Identifier - Give the Mapping a distinct name that you will use to identify the data being pulled through it in the NinjaCat Template Builder

DIMENSIONS Tab -- Repeat the instructions below for each dimension you need to pull from your sheet

     A. Click the "Add Dimensions" button near the center

B. Fill in the needed fields in the "Dimension Editor" pop-up window

  • Name - A title for the Dimension that will be visible in the Template Builder
  • Header Mapping - Select the actual column from your sheet that contains the right data for the Dimension
  • Aggregation Mapping - (If appropriate) The common Dimension set that this data could fall under if being combined with data from other data sources
  • Display As - The specific format that the data from the sheet should be represented as

C. Click the "OK" button near the bottom right of the pop-up window after all the fields are filled

 

METRICS Tab -- Repeat the instructions below for each dimension you need to pull from your sheet

A. Click the "Add Metrics" button near the center

B. Fill in the needed fields in the "Metrics Editor" pop-up window

  • Name - A title for the Metric that will be visible in the Template Builder
  • Header Mapping - Select the actual column from your sheet that contains the right data for the Metric
  • Display As - The specific numeric format that the data from the sheet should be represented as
  • Calculate totals as... - For combining metric values choose Summation or Average
  • Aggregation Mapping - (If appropriate) The common Metric set that this data could fall under if being combined with data from other data sources

C. Click the "OK" button near the bottom right of the pop-up window after all the fields are filled

5. Click the "Save" button near the bottom left after the INFORMATION, DIMENSIONS, and METRICS tabs have been completed.

 

Using API Custom Data in a Template

1. Access the NinjaCat Template Builder

2. Add a data widget to the template

3. Click on "Add Data Source" near the top right

4. Click on "Custom Data" from the list of data sources

5. Fill in the "Custom Data" pop-up window by addressing the fields:

  • Name - Give the data source entry a distinct label
  • Grouping - Select an account group (if creating a roll-up)
  • Data Source Type - Select "Zapier / Custom API" from the drop-down menu
  • Mapping - Select the Mapping that leads to the desired data

 

6. Click the "Close" button near the bottom right of the pop-up window

NinjaNote: Once a mapping is selected in the pop-up window, two buttons will now be available below the "Mapping" field. The "View Mapping" button will give you a view of the Dimensions and Metrics available through the Mapping. The "Edit Mapping" button will take you to the Edit Mappings area and allow you to make changes to the Mapping itself. When done you will be returned to the NinjaCat Template builder.

NinjaNote: We never show today’s data so if you sent data with today’s date it will not be visible until tomorrow.

NinjaNote: Postman sends data weirdly to PHP for parsing purposes. So make sure that you use the raw data post instead of form data for the body and send the JSON blob directly as a format.

 

Error Codes

  

 

Code
Message

 

Additional Info

api_key_not_provided

You did not provide an api

key. Please see this

support article for

details:

https://support.ninjacat.i o/hc/en-us/articles/115015

708228

Please check the syntax of the URL you are providing - it must be included directly in the URL.

api_key_invalid

No network with specified API key found. Please set

_

up a network and try

again.

Please make sure the API key you are providing is valid and matches the token in the Zapier API screen.

data_parsing_issue

Cannot parse provided data json

The data you have provided isn’t in valid JSON format.

client_not_provided

Account not specified.

Please use client key to
provide account name or
client external id for

__

account external id

You did not provide a client or client_external_id in the parameters.

client_invalid

Cannot find account with
provided name or external

id

The client or client_external_id you provided does not match anything in our system.

row_id_invalid
Data with provided row id

do not exist

The row id provided wasn’t found in our system

date_not_provided

You did not provide date.

Please see this support

article for

details:https://support.ni njacat.io/hc/en-us/article

s/115015708228

You didn’t provide a valid date in the parameters.

date_invalid

Error parsing Date. Please

check date format and try

again.

The date you provided was an invalid format and couldn’t be turned into a valid date.

data_not_provided

You did not provide data.

Please see this support
article for details:

https://support.ni njacat.io/hc/en-us/article

s/115015708228

You didn’t provide a valid data node in the parameters.

  

 

Related articles

Comments

0 comments

Article is closed for comments.