Skip to content

Requests

Parameters

Path Parameters

In all requests, Path Parameters specified in the endpoint will always be implicitly required.
In addition to the {account_id} parameter, which is always present in each endpoint (as well as the {billing_plan} parameter which is almost always present).
Other Path Parameters in a request will often be obtained from another endpoint response that will be indicated for each case.

Billing Plan

For most of the calls, it is required to specify the Billing Plan in the endpoint for which the API usage is granted, as previously commercially agreed.

Possible values for {billing_plan} are the following:

  • licence: using only a subset of API, with a specific subscribed deal.
  • ondemand: each call will be billed. A single API callback price will be calculated based on a specific tier.

Therefore, when billing plan is required for a request, the call will have the following pattern:

Template 
curl 'https://api.datappeal.io/v4/{billing_plan}/account/{account_id}/…' \
-H 'x-api-key: {x_api_key}' \
-H 'Authorization: Bearer {jwt_bearer}' \
Licence

When performing calls with a Licence Billing Plan, it's not of interest to consider the price tier of the call. Every authorized call is included in the deal subscription until the usage limits are met.

Within this documentation, calls enabled by a licence subscription are marked with a badge meaning the following:

  • : user is always authorized to call, regardless the subscribed licence type.
  • : user is authorized to call only if a Premium Licence has been subscribed.
  • : user is authorized to call only if a specific enabling add-on has been subscribed.
  • : user is authorized to call only if commercially agreed, regardless the licence subscription type.

Please Note

Calls which are not marked with such a badge are excluded from Licence Billing Plan.

On-demand

Performing calls with On-demand Billing Plan, since a consumption-based deal was subscribed, each compliant call is authorized by default and has a unitary tier-based price that will concur in billing at the time of invoicing.
Even if every call is subject to billing, the calls' quota will be subject to usage limits as well.

Within this documentation, calls enabled by an on-demand subscription are marked with a badge with one of the following values:

  • : call will not be billed.
  • : call will be billed with the lowest unitary price as commercially agreed.
  • : call will be billed with the intermediate unitary price as commercially agreed.
  • : call will be billed with the highest unitary price as commercially agreed.

Please Note

Calls which are not marked with such a badge are excluded from On-demand Billing Plan.

Pagination

For each call that supports pagination, a unitary price multiplier will be calculated and applied as follows:

  • If the number of elements recovered is > 0 and <= 25 the multiplier will be 1 (default)
  • If the number of elements recovered is > 25 and <= 50 the multiplier will be 2
  • If the number of elements recovered is > 51 and <= 75 the multiplier will be 3
  • If the number of elements recovered is > 76 and <= 100 the multiplier will be 4

Header and Query Parameters

Nullability

The required Header and Query Parameters will be marked with * before the parameter name, while optional parameters will not be marked.

Deprecation

Deprecated Header and Query Parameters will be strikethrough and marked with :fontawesome-solid-exclamation-circle:, which means that is highly recommended not to use that parameter as it will be removed soon.
Corresponding replacing fields will be marked with :fontawesome-solid-sync-alt:.

Multi-value

Query Parameters marked with ⓝ can be repeated and set with a different value each time in order to be set with multiple values.

Pagination

When specified in the endpoint documentation, results can be paginated specifying page and page_size Query Parameters, which will always have implicit default values.

Ordering

When specified in the endpoint documentation, results can be ordered specifying an {order_value} for order_by Query Parameter.
When order_by Query Parameter is marked with double-value symbol ②, double ordering is supported and parameter values order will be interpreted as primary ordering and secondary ordering.

Value Description
{order_value} {order_value} is ordered in ascending order.
+{order_value} {order_value} is ordered in ascending order.
-{order_value} {order_value} is ordered in descending order.

Request Body

Similarly to Request Parameters, in Request Body JSON object descriptions, required fields will be marked with * before the field name, while optional fields will not be marked.