✕
Home Pricing Documentation Contact Book a demo Blog
DataReportive
Create a free accountSign in

Introduction

Welcome to the DataReportive API. With the DataReportive API you will be able to retrieve, create, and edit Users, Groups, and Schedules. The API does not currently allow to add or edit data sources, folders, and reports yet. You will be able to get metadata about your reports as well as delete them using the API. Additionally you will be able to send a report to a defined set of users or groups through email on demand (sending reports in Slack in currently unsupported). For any feedback, comments, or suggestions around the API please contact us using the support page.

Authentication

The DataReportive API uses API tokens to authenticate requests. You can view and manage your API keys below. You can get a token per an admin user, and using this token you can authenticate. Any resources created will be associated with the token corresponding to the user.

Authentication to the API is performed via a bearer token. In the request you will need to add the Authorization header in the following way Authorization: Token [[TOKEN HERE]].

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

On the right is a simple example of retrieving active users and shows how authentication should be included in a request (Changing the user above will change all examples to use the corresponding token).

Example Request

curl 'https://datareportive.acmeinc.com/api/v1/users/' -X GET -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"

Response

{
  "status": 200,
  "message": "Request successful!",
  "data": {
    "results": [
      {
        "first_name": ...,
        "last_name": ...,
        "url": ...,
        "num_reports_receiving": ...,
        "user_type_dispaly": ...,
        "user_type": ...,
        "email": ...,
        "date_updated": ...,
        "date_created": ...,
        "id": ...
      },
      ...
    ]
  }
}

Responses and Errors

DataReportive uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.). Codes in the 5xx range indicate an error with DataReportive's servers.

Some 4xx errors that could be handled programmatically (e.g., a card is declined) include an error code that briefly explains the error reported.

HTTP Codes

200 - OKEverything worked as expected.
400 - Bad RequestThe request was unacceptable, often due to missing a required parameter.
401 - UnauthorizedNo valid API key provided.
402 - Request FailedThe parameters were valid but the request failed.
403 - ForbiddenThe API key doesn't have permissions to perform the request.
404 - Not FoundThe requested resource doesn't exist.
409 - ConflictThe request conflicts with another request (perhaps due to using the same idempotent key).
429 - Too Many RequestsToo many requests hit the API too quickly. We recommend an exponential backoff of your requests.
500, 502, 503, 504 - Server ErrorsSomething went wrong on DataReportive's end. (These are rare.)

Resources

The DataReportive API is currently centered . The API currently support a single view of a resource so the metadata cannot be customized. We've included the most commonly needed fields, and we've extended the initial resource to include related resources (One to One and One to Many) where deamed appropriate. We will be rolling out more cusomized views of resources in future versions.

Should you need a view that we don't currently support to optimize your calls to the API please reachout to our support team.

Supported resources and operations

Users GET (One/Multiple), POST, PUT, DELETE
Groups GET (One/Multiple), POST, PUT, DELETE
Schedules GET (One/Multiple), POST, PUT, DELETE
Reports GET (One/Multiple), DELETE
Sending Reports POST

Getting Users

Getting all active users
GET /api/v1/users/

Getting all active users by permission type ( Possible values: A | N | R. )
GET /api/v1/users/?permissions=N

Getting a specific user ( Possible values: The numeric ID for the user. This can be retrieved for each user in the response for all active users. )
GET /api/v1/users/[ USER ID ]/

Getting all active users

curl 'https://datareportive.acmeinc.com/api/v1/users/' -X GET -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"

Getting all active users by permission type

curl 'https://datareportive.acmeinc.com/api/v1/users/?permissions=N' -X GET -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"

Getting a specific user

curl 'https://datareportive.acmeinc.com/api/v1/users/[ USER ID ]/' -X GET -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"

Creating/Updating an User

Creating an User
POST /api/v1/users/

Updating an User
PUT /api/v1/users/[USER ID]/ or POST /api/v1/users/[USER ID]/

Required fields:

first_nameString for first name.
last_nameString for last name.
emailString for email address (an email will be sent to the user with their password).
user_typeThe user type (Admin/Normal/Restricted). Possible values "A","N", and "R" correspondingly.

Creating a user example

curl 'https://datareportive.acmeinc.com/api/v1/users/' \
-X POST \
-H 'Authorization: Token bac01bfaf68e4b30b246b392651f26bc' \
-H 'Content-Type: application/json' \
-d '{"first_name":"John", "last_name":"Smith", "email":"john@smith.com", "user_type":"A"}'

Deleting Users

Deleting a specific user ( Possible values: The numeric ID for the user. This can be retrieved for each user in the response for all active users. )
DELETE /api/v1/users/[ USER ID ]/

DELETE a specific user

curl 'https://datareportive.acmeinc.com/api/v1/users/[ USER ID ]/' -X DELETE -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"

Getting Groups

Getting all Groups
GET /api/v1/groups/

Getting a specific Group ( Possible values: The numeric ID for the Group. This can be retrieved for each group in the response for all active Groups. )
GET /api/v1/groups/[ GROUP ID ]/

Getting all Groups

curl 'https://datareportive.acmeinc.com/api/v1/groups/' -X GET -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"

Getting a specific Group

curl 'https://datareportive.acmeinc.com/api/v1/groups/[ GROUP ID ]/' -X GET -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"

Creating/Updating a Group

Creating a Group
POST /api/v1/groups/

Updating a Group
PUT /api/v1/groups/[GROUP ID]/ or POST /api/v1/groups/[GROUP ID]/

Required fields:

nameString for the name of the Group.

Optional fields:

descriptionString for the description of the Group.
usersA list of User IDs that comprise the Groups (e.g. [3, 4]).

Creating a group example

curl 'https://datareportive.acmeinc.com/api/v1/groups/' \
-X POST \
-H 'Authorization: Token bac01bfaf68e4b30b246b392651f26bc' \
-H 'Content-Type: application/json' \
-d '{"name":"My Clients", "description":"A list of my clients", "users":[1,2]}'

Adding/Removing Users from a Group

Adding Users
POST /api/v1/groups/[GROUP ID]/add_users/

Removing
POST /api/v1/groups/[GROUP ID]/remove_users/
or
DELETE /api/v1/groups/[GROUP ID]/remove_users/

Required fields:

usersA list of User IDs (e.g [22,24]).

Adding Users to a Group example

curl 'https://datareportive.acmeinc.com/api/v1/groups/1/add_users/' \
-X POST \
-H 'Authorization: Token bac01bfaf68e4b30b246b392651f26bc' \
-H 'Content-Type: application/json' \
-d '{"users":[1,2]}'

Remove Users to a Group example

curl 'https://datareportive.acmeinc.com/api/v1/groups/1/remove_users/' \
-X POST \
-H 'Authorization: Token bac01bfaf68e4b30b246b392651f26bc' \
-H 'Content-Type: application/json' \
-d '{"users":[1,2]}'

Deleting Groups

Deleting a specific Group ( Possible values: The numeric ID for the Group. This can be retrieved for each user in the response for all active Groups. )
DELETE /api/v1/groups/[ GROUP ID ]/

DELETE a specific Group

curl 'https://datareportive.acmeinc.com/api/v1/groups/[ GROUP ID ]/' -X DELETE -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"

Getting Schedules

Getting all Schedules
GET /api/v1/schedules/

Getting a specific Schedule ( Possible values: The numeric ID for the Schedule. This can be retrieved for each schedule in the response for all active Schedules. )
GET /api/v1/schedules/[ Schedule ID ]/

Getting all Schedules

curl 'https://datareportive.acmeinc.com/api/v1/schedules/' -X GET -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"

Getting a specific Schedule

curl 'https://datareportive.acmeinc.com/api/v1/schedules/[ GROUP ID ]/' -X GET -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"

Creating/Updating a Schedule

Creating a Schedule
POST /api/v1/schedules/

Updating a Schedule
PUT /api/v1/schedules/[SCHEDULE ID]/ or POST /api/v1/schedules/[SCHEDULE ID]/

Required fields:

reportThe report ID.
nameAn optional name for the report.
schedule_typeThe type of schedule: Once, Daily, Weekly, Monthly, Quaterly. ( Possible values: O | D | W | M | Q )
scheduled_time_hourHour of schedule ( Possible values: "00"-"23" )
scheduled_time_minuteMinute of schedule ( Possible values: "00" | "15" | "30" | "45" )
export_typeDocument export type PDF or PNG (not required if it is an email). ( Possible values: pdf | png )
export_data_typeData export type CSV or Excel (not required if it is an email or document export type selected). ( Possible values: csv | xlsx )
method_typeMethod of delivery: Email or Slack ( Possible values: email | slack )
timezoneString for the timezone used in the schedule (for a list of possible values see the selector here).
schedule_conditionIf the schedule is conditional or not ( Possible values: "1" - Non-conditional | "2" - Conditional ). Type: String.
retry_conditionHow long should the schedule be retried if it fails its condition ( Possible values: "0" - No retries | "1" - 15 minutes | "2" - 30 minutes | "3" - 1 hour | "4" - 2 hours | "5" - 6 hours ). Type: String.

Optional fields:

scheduled_day_of_weekA list of days in the week (e.g [0,1]) ( Possible values: 0 - Monday| 1 - Tuesday | 2 - Wednesday | 3 - Thursday | 4 - Friday | 6 - Saturday | 6 - Sunday ) Type: List of Integers.
scheduled_day_of_monthScheduled day of the month ( Possible values: 1-29 | 29th means last day of the month) Type: Integer.
usersA list of User IDs (e.g. [2,3]). Type: List of Integers.
groupsA list of Group IDs (e.g. [5,6]). Type: List of Integers.
trigger_valueTrigger value. Type: String.
queryQuery for the condition. Type: String.
datasourceThe ID for the datasource. You can find the IDs for datasources here. Type: Integer

Creating a schedule example

curl 'https://datareportive.acmeinc.com/api/v1/schedules/' \
-X POST \
-H 'Authorization: Token bac01bfaf68e4b30b246b392651f26bc' \
-H 'Content-Type: application/json' \
-d '{
    "report": 167,
    "schedule_type": "W",
    "scheduled_time_hour": "15",
    "scheduled_time_minute": "15",
    "method_type":"email",
    "timezone":"Europe/London",
    "schedule_condition":"1",
    "retry_condition":"1",
    "users":[24,22],
    "export_type":"pdf",
    "scheduled_day_of_week":[1,2]
}'

Adding/Removing Users from a Schedule

Adding Users
POST /api/v1/schedules/[SCHEDULE ID]/add_users/

Removing
POST /api/v1/schedules/[SCHEDULE ID]/remove_users/
or
DELETE /api/v1/schedules/[SCHEDULE ID]/remove_users/

Required fields:

usersA list of User IDs (e.g [22,24]).

Adding Users to a Schedule example

curl 'https://datareportive.acmeinc.com/api/v1/groups/1/add_users/' \
-X POST \
-H 'Authorization: Token bac01bfaf68e4b30b246b392651f26bc' \
-H 'Content-Type: application/json' \
-d '{"users":[1,2]}'

Remove Users to a Schedule example

curl 'https://datareportive.acmeinc.com/api/v1/groups/1/remove_users/' \
-X POST \
-H 'Authorization: Token bac01bfaf68e4b30b246b392651f26bc' \
-H 'Content-Type: application/json' \
-d '{"users":[1,2]}'

Adding/Removing Groups from a Schedule

Adding Groups
POST /api/v1/schedules/[SCHEDULE ID]/add_groups/

Removing
POST /api/v1/schedules/[SCHEDULE ID]/remove_groups/
or
DELETE /api/v1/schedules/[SCHEDULE ID]/remove_groups/

Required fields:

groupsA list of Group IDs (e.g [22,24]).

Adding Groups to a Schedule example

curl 'https://datareportive.acmeinc.com/api/v1/schedules/1/add_groups/' \
-X POST \
-H 'Authorization: Token bac01bfaf68e4b30b246b392651f26bc' \
-H 'Content-Type: application/json' \
-d '{"groups":[1,2]}'

Remove Groups to a Schedule example

curl 'https://datareportive.acmeinc.com/api/v1/schedules/1/remove_groups/' \
-X POST \
-H 'Authorization: Token bac01bfaf68e4b30b246b392651f26bc' \
-H 'Content-Type: application/json' \
-d '{"groups":[1,2]}'

Deleting Schedules

Deleting a specific Schedule ( Possible values: The numeric ID for the Schedule. This can be retrieved for each user in the response for all active Schedules. )
DELETE /api/v1/schedules/[ SCHEDULE ID ]/

DELETE a specific Schedule

curl 'https://datareportive.acmeinc.com/api/v1/schedules/[ SCHEDULE ID ]/' -X DELETE -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"

Getting Reports

Getting all Reports
GET /api/v1/reports/

Getting a specific Report ( Possible values: The numeric ID for the Report. This can be retrieved for each report in the response for all active Reports. )
GET /api/v1/reports/[ REPORT ID ]/

Getting all Reports

curl 'https://datareportive.acmeinc.com/api/v1/reports/' -X GET -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"

Getting a specific Report

curl 'https://datareportive.acmeinc.com/api/v1/reports/[ REPORT ID ]/' -X GET -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"

Sending a report via email

Sending an email
POST /api/v1/reports/REPORT ID/send/

Required fields:

export_typeDocument export type PDF or PNG (not required if it is an email). ( Possible values: pdf | png | no )
export_data_typeData export type CSV or Excel (not required if it is an email or document export type selected). ( Possible values: csv | xlsx | no )

Optional fields:

usersA list of User IDs (e.g. [3, 4]).
groupsA list of Group IDs(e.g. [3, 4]).

Creating a group example

curl 'https://datareportive.acmeinc.com/api/v1/reports/167/send/' \
-X POST \
-H 'Authorization: Token bac01bfaf68e4b30b246b392651f26bc' \
-H 'Content-Type: application/json' \
-d '{"export_type":"pdf", "users":[22],"export_data_type":"no"}'

Deleting Reports

Deleting a specific Report ( Possible values: The numeric ID for the Report. This can be retrieved for each user in the response for all active Report. )
DELETE /api/v1/reports/[ REPORT ID ]/

DELETE a specific Report

curl 'https://datareportive.acmeinc.com/api/v1/reports/[ REPORT ID ]/' -X DELETE -H "Authorization: Token bac01bfaf68e4b30b246b392651f26bc"