This is the full external API documentation for the Partnerize API. The API is organised around REST principles like resource-oriented URLs and uses standard HTTP features like response codes, verbs and Authentication. At Partnerize, we build features API-first and have built our web application on top of the API as we want to make our core functionality available to developers to consume programmatically.

You can refer to the API reference for a full list of supported endpoints. If it is the first time you are using the API, go to the Quick Start section for a quick start tutorial on making your first API call.

Currently there are three global versions of the Partnerize API. You can distinguish between them by looking at the endpoint URL. First version endpoints do not include a version in the path: e.g. https://api.partnerize.com/network/. Second and third version endpoints can be identified by the v2 and v3 in the URL: e.g. https://api.partnerize.com/v2/campaigns/{campaignId}/commissions or https://api.partnerize.com/v3/brand/campaigns/{campaignId}/conversions/bulk. Since the versions are global, there are common conventions that apply to all API versions as well as version specific ones. The sections below describe these conventions in detail.

This tutorial takes you through creating your first Partnerize API call. The example below demonstrates how to:

1. Obtain your API keys
2. Generate an Authorization header
3. Make your first Partnerize API request

Step 1. Obtaining your API keys

1. Login to the Partnerize console at https://console.partnerize.com.
2. Go to Settings – the User Application Key and User API key can be found under Account settings.

Step 2. Generate an Authorization header

Authentication is achieved by providing an Authorization header in the following format:

Authorization: Basic cDN0ZXcxNDV5M3RhZzQxbjowaHkzNGho

Where cDN0ZXcxNDV5M3RhZzQxbjowaHkzNGho is the Base64 encoding of the User Application Key and User API key joined by a colon ':'.

Refer to the Access and Authentication section for more details.

Step 3. Make your first Partnerize API request

In this step you are going to make a call to the "Networks" endpoint to retrieve a list of all networks your user has access to.

In the example below, replace the {personal_token} with the one generated in the previous step:

curl -X GET https://api.partnerize.com/network -H 'Authorization: Basic {personal_token}'

The response will contain a collection of networks:

{
    "count": 1,
    "execution_time": "0.20239 seconds",
    "networks": [
        {
            "network": {
                "network_id": 1,
                "network_name": "Partnerize",
                "network_description": "Test Network",
                "network_notes": "This is a test Partnerize network",
                "network_application_id": 2,
                "auto_approve_publishers": "n",
                "default_campaign_id": null,
                "cm_client_id": “b4d0d85cff813cdce092c261b2b200”,
                "network_contact_email": null,
                "network_locale": "en"
            }
        }
    ]
}

Backwards-compatible changes

Consumers of the Partnerize API should ensure that their applications can handle backwards-compatible changes. Examples of what Partnerize considers to be backwards-compatible changes:

• Introducing new resources
• Introducing new optional request parameters to existing API resources
• Introducing new properties in the responses of existing API resources
• Introducing new methods to existing API resources
• Introducing new headers to existing responses
• Changing the order of existing response properties

Partnerize will be making backwards-compatible changes without advanced notice. The changes will be communicated by updating the API documentation.

Breaking changes

Breaking changes would usually require changes in the code of a Partnerize API consumer. Examples of what Partnerize considers to be breaking changes:

• Removing a resource (see API Resource Deprecation below)
• Removing or renaming properties in existing responses
• Removing documented response headers
• Introducing new mandatory request parameters or header
• Making an optional request parameter or header to mandatory

Partnerize will announce breaking changes at least 3 months in advance.

Hotfix changes

Partnerize may introduce either breaking or backwards-compatible changes if required to address stability or security issues. In the rare situation of that happening Partnerize reserves the right to make those changes without the agreed minimum notice period announcement.

Partnerize will give API consumers at least 3 months notice about deprecating an API resource. Partnerize will notify affected consumers via email with instructions about the upgrade process. Once the announcement is made the resource will be marked as Obsolete in the API documentation together with an alternative new functionality to use.

Older API endpoints may refer to Brands as Advertisers and Partners as Publishers. Those terms are used interchangeably throughout the API reference. The reference in this set of documents is the single source of truth for the interface specification.

The Partnerize API uses HTTP Basic Authentication. You must have valid application_key and user_api_key to make API requests. Refer to the Quick Start tutorial for details on how to obtain these. The application_key identifies the Network you are making the request against and the user_api_key identifies the User on whose behalf the request is made. The keys are sent as part of an Authorization header which value contains the word Basic followed by space and a base-64-encoded string username:password, where:

• username: application_key

• password: user_api_key

  Authorization: Basic cDN0ZXcxNDV5M3RhZzQxbjowaHkzNGho

Access to data and operations of certain endpoints is dependent on the access rights of the user.

All API requests must be made over HTTPS and contain a valid Authorization header value.

Certain endpoints will generate large result sets. To save bandwidth and long processing times, these endpoints will paginate the results to reduce the strain on both client and server.

Any endpoint that supports pagination will return 3 attributes to support this:

• offset the current offset of the data returned
• limit the number of results to which the output was restricted
• count the total number of results available

If offset combined with limit is less than the overall count, the results have been truncated. Therefore, to consume all data you will need to page through the result set.

Paging

To paginate through a result set, you can use a combination of 2 parameters:

For example, if an endpoint produces 500 results, only the first 300 will be returned (results 0 to 299). In order to retrieve the remaining results, implement the offset GET param. In this example, adding offset=300 to the query string parameters.

There are 2 considerations when doing this:

• Results begin at offset 0. If you're retrieving a report with limit=300, page 2 will begin at offset=300, page 3 at offset=600, page 4 at offset=900, etc.
• The reports you generate are based on live data, and could be subject to continuous, incremental changes. If your query covers a particularly busy data set, then data inserts or updates may occur between paging.

Hypermedia

It can be cumbersome to manage pagination programmatically, especially when attempting to rapidly prototype. To provide some helpful assistance, the API will output a hypermedia node for all paginated result sets. Essentially this performs all necessary calculations and outputs all relevant information with absolute URI's to assist easier pagination.

"hypermedia": {
    "pagination": {
        "total_page_count": 15,
        "total_item_count": 51234,
        "first_page": "/user.json?limit=100&offset=0",
        "last_page": "/user.json?limit=100&offset=1400",
        "next_page": "/user.json?limit=100&offset=100",
        "previous_page": null
    }
}

For the granular conversion reporting endpoint, we have adopted cursor based pagination. Due to the scale of some clients, there is a large overhead involved in processing the offset and computing the total number of results. This overhead compounds as the data set size increases, and when the data set grows large enough it becomes impractical to perform the task in real time.

To ensure these high volume endpoints can scale, cursor based pagination has been implemented, where each response will now return a cursor_id attribute along with the results. This indicates where the client is currently within the result set. When the client requests another page, and includes the cursor_id value, the server will be able to determine where the client is up to in the result set and send the appropriate items.

This approach does not suffer from the same overhead drawbacks that limit/offset pagination does, and provides a consistent view of the result set across pages.

Paging

To paginate through a result set, you can use a combination of 2 parameters:

For example, if an endpoint produces 5,000 results, only the first 300 will be returned (results 0 to 299). Within the header attributes, a cursor_id will be included. Simply pass the cursor_id in conjunction with the desired limit to return the subsequent items from the result set.

Hypermedia

The hypermedia object has been updated to automatically include the relevant cursor_id and limit for the next page.

"hypermedia": {
    "pagination": {
        first_page: "/reporting/report_publisher/publisher/10l1/conversion.json?start_date=2018-03-01+00%3A00%3A00&end_date=2018-04-01+00%3A00%3A00&limit=300",
        next_page: "/reporting/report_publisher/publisher/10l1/conversion.json?start_date=2018-03-01+00%3A00%3A00&end_date=2018-04-01+00%3A00%3A00&limit=300&cursor_id=10325942995"
    }
}

To protect our API users, API endpoints will rate limit based on usage. If violated, the API will respond with with a 429 http status code with the following body:

v1 API:

{
    "error": {
        "message": "Too Many Requests",
        "type": "429"
    }
}

v2 API:

{
  "error": {
    "errors": [
    ],
    "code": "429",
    "message": "Too Many Requests"
  }
}

v3 API:

{
  "error": {
    "errors": [
      {
        "property": "",
        "message": "You have made too many requests recently, please try again later.",
        "code": "3b22ff00-96a5-4fa4-96cc-f36e68dbd2e2",
        "type": "too_many_requests"
      }
    ],
    "message": "Too Many Requests",
    "code": "429"
  }
}

To help monitor your API usage, the following headers will be returned via the API to help moderate the integration:

Base URL

The base URL for version 1 API endpoints is https://api.partnerize.com/

The default response format is JSON. You can specify the response format of each request, by adding a file extension suffix to the end of the request URI. The requested format will dictate the HTTP Content-Type header that is returned in the response. Currently, there are 3 available formats:

Whenever too many requests are sent through within a period of time the response will be an error with an http status code 429 Too Many Requests. See Rate limits for more information on this.

Sample JSON response body when a rate limit is hit.

{
        "error": {
            "message": "Too Many Requests",
            "type": "429"
        }
    }

The API is compression-enabled. To control whether the API response is compressed, send the relevant Accept-Encoding HTTP header:

• Request: Accept-Encoding: gzip
• Response: Content-Encoding: gzip

Base URL

The base URL for version 2 API endpoints is https://api.partnerize.com/v2.

Supported HTTP Verbs

Partnerize's API uses appropriate HTTP verbs where possible. Endpoints support one or more of the following HTTP verbs:

GET – GET requests retrieve one or more entities and are always read-only. A successful request returns a response with a 200 OK status code.

POST – POST requests are mainly are used to create Partnerize entities or batch operations. When successful such a request returns a 201 Created response code. In the cases when the POST request is used for batch operations processing is done asyncronously. In those cases the successful request will return a 202 Accepted response code and the response should contain a job id, which can be used to monitor the status of the processing.

PUT – PUT request update the resource provided in the URL. PUT requests are idempotent and result in the resource being replaced. A successful request returns a response with a 200 OK status code.

PATCH – Used to do partial updates to Partnerize entities. A successful request returns a response with a 200 OK status code.

DELETE – DELETE requests can be used to remove an entity when supported. A successful request returns a response with a 200 OK or a 204 No Content status code.

If an endpoint doesn't support a particular method, it will return a response with a 405 Method Not Allowed code.

Version 2 API endpoints return response data as a JSON object. Refer to the API reference for details of each endpoint responses. The response will include one of the following HTTP status codes:

HTTP Status Codes Summary

See the Errors section below for more details on error responses.

Response format

Top level attributes

Each response document contains an execution_time top level attribute.

Collections response

In addition to the execution_time top level attribute, a collection response contains a count one, which represents the total number of resources in the collection.

Example:

{
    "execution_time": "1.11761 seconds",
    "count": 0,
    "commissions": []
}

Single resource response

Example:

{
    "execution_time": "1.11761 seconds",
    "commission": {
      "id": '1234',
    }
}

The Version 2 API uses the above mentioned standard HTTP status codes to indicate the success or failure of the API calls. The body of the response will be JSON in the following format:

{
  "error": {
    "errors": [
      {
        "property": "evaluation_period",
        "type": "validation_error",
        "code": "required_property",
        "message": "Parameter 'evaluation_period' is required"
      }
    ],
    "code": "400",
    "message": "Bad Request"
  }
}

Bad Request (Code 400)

If there is an error in your input, you’ll receive a “400 Bad Request” http response. The body of the response will be JSON with the errors attribute containing an array of details of the error(s).

Unauthorized (Code 401)

If there is an error with your authentication credentials, you’ll receive a “401 Unauthorized” http response.

Sample JSON response body

{
  "error": {
    "errors": [
      {
        "type": "error",
        "code": "unauthorized",
        "message": "Your API credentials can be found in Account settings. 'Username' will be your 'User application key' and 'Password' will be your 'User API key'"
      }
    ],
    "code": "401",
    "message": "Unauthorized"
  }
}

Forbidden (Code 403)

If there is an denial of access to a resouce within your request, you’ll receive a “403 Forbidden“ http response.

{
  "error": {
    "errors": [
      {
        "type": "error",
        "code": "unauthorized",
        "message": "You do not have 'read' permission on campaign with id '1'"
      }
    ],
    "code": "403",
    "message": "Forbidden"
  }
}

When the user is not allowed to know the resource exists, i.e. they don't have READ permission on the resource, the response will have a 404 Not Found status code.

Not Found (Code 404)

If there is an error locating a requested resource, you’ll receive a “404 Not Found" http response.

Sample JSON response body when an invalid URL has been requested.

{
  "error": {
    "errors": [
      {
        "type": "error",
        "code": "entity_not_found",
        "message": "campaign not found for id '1'"
      }
    ],
    "code": "404",
    "message": "Not Found"
  }
}

Method Not Allowed (Code 405)

If there is an error accessing a resource using the given HTTP verb, you’ll receive a “405 Method Not Allowed“ http response. The body of the response will be JSON with the errors attribute containing an array of details of the error(s).

Sample JSON response body when an valid URL has been requested with an invalid request method.

{
  "error": {
    "errors": [
      {
        "type": "error",
        "code": "routing_error",
        "message": "index not supported"
      }
    ],
    "code": "405",
    "message": "Method Not Allowed"
  }
}

Too Many Requests (Code 429)

This error code indicates that too many requests were sent within a period of time. See Rate limits for more information on this.

Sample JSON response body when a rate limit is hit.

    {
      "error": {
        "errors": [
        ],
        "code": "429",
        "message": "Too Many Requests"
      }
    }

v2 API endpoints use ISO-8601 date time format.

Example:

2019-03-01T12:01:00+00:00 - this example represents 1 minute past midday on the 1st of March 2019 in UTC.

2019-03-01 - date only example

Base URL

The base URL for version 3 API endpoints is https://api.partnerize.com/v3. Version 3 of the API endpoints introduces brands and partners context to the API. This means that the brand endpoints will have the following base URL: https://api.partnerize.com/v3/brand and the partner ones will have: https://api.partnerize.com/v3/partner

Supported HTTP Verbs

Partnerize's API uses appropriate HTTP verbs where possible. Endpoints support one or more of the following HTTP verbs:

GET – GET requests retrieve one or more entities and are always read-only. A successful request returns a response with a 200 OK status code.

POST – POST requests are mainly are used to create Partnerize entities or batch operations. When successful such a request returns a 201 Created response code. In the cases when the POST request is used for batch operations processing is done asyncronously. In those cases the successful request will return a 202 Accepted response code and the response should contain a job id, which can be used to monitor the status of the processing.

PUT – PUT request update the resource provided in the URL. PUT requests are idempotent and result in the resource being replaced. A successful request returns a response with a 200 OK status code.

PATCH – Used to do partial updates to Partnerize entities. A successful request returns a response with a 200 OK status code.

DELETE – DELETE requests can be used to remove an entity when supported. A successful request returns a response with a 200 OK or a 204 No Content status code.

If an endpoint doesn't support a particular method, it will return a response with a 405 Method Not Allowed code.

Unrecognized request headers and parameters

• We ignore unrecognized HTTP headers.
• We ignore unrecognized query string parameters.
• We return a 400 Bad Request if there are unrecognized parameters in the request body.

Version 3 API endpoints return response data as a JSON object. Refer to the API reference for details of each endpoint responses. The response will include one of the following HTTP status codes:

HTTP Status Codes Summary

See the Errors section below for more details on error responses.

Response format

Top level attributes

Each response document contains a data top level attribute and may contain a hypermedia one. The data attribute wraps all response data in the payload, while hypermedia will contain links to related resources.

Example:

{
  "data": {
      "id": "111111l11",
      ...
  },
  "hypermedia": {
      "links": {
      "tasks": "/v3/jobs/111111l11/tasks"
    }
  }
}

The API uses standard HTTP status codes to indicate the success or failure of the API call. The body of the response will be JSON in the following format:

{
  "error": {
    "errors": [
      {
        "property": "[name]",
        "message": "The attribute expected to be of type 'string' but 'integer' given.",
        "code": "6a6c32c0-de05-4301-89dd-4a72133c137f",
        "type": "validation_error"
      }
    ],
    "code": "400",
    "message": "Bad Request"
  }
}

Bad Request (Code 400)

If there is an error in your input, you’ll receive a “400 Bad Request” http response. The body of the response will be JSON with the errors attribute containing an array of details of the error(s).

Authorized (Code 401)

If there is an error with your authentication credentials, you’ll receive a “401 Unauthorized” http response. The body of the response will be JSON with the errors attribute containing an array of details of the error(s).

Sample JSON response body when no credentials has been supplied.

{
  "error": {
    "errors": [
      {
        "property": "",
        "message": "Your API credentials can be found in Account settings. 'Username' will be your 'User application key' and 'Password' will be your 'User API key'.",
        "code": "39b4b7c2-e5b9-41b1-83d4-db3b23b5ebfa",
        "type": "unauthorised"
      }
    ],
    "message": "Unauthorized",
    "code": "401"
  }
}

Sample JSON response body when an invalid User application key and User API key combination has been supplied.

{
  "error": {
    "errors": [
      {
        "property": "",
        "message": "Your 'User application key' and 'User API key' combination is invalid.",
        "code": "39b4b7c2-e5b9-41b1-83d4-db3b23b5ebfa",
        "type": "unauthorised"
      }
    ],
    "message": "Unauthorized",
    "code": "401"
  }
}

Forbidden (Code 403)

If there is an denial of access to a resouce within your request, you’ll receive a “403 Forbidden“ http response. The body of the response will be JSON with the errors attribute containing an array of details of the error(s).

{
  "error": {
    "errors": [
      {
        "property": "[campaigns][0]",
        "message": "You do not have \"view\" access on this entity.",
        "code": "16bd7f4a-bf84-45c3-aa95-9b32aeb139b0",
        "type": "unauthorised"
      }
    ],
    "code": "403",
    "message": "Forbidden"
  }
}

Not Found (Code 404)

If there is an error locating a requested resource, you’ll receive a “404 Not Found" http response. The body of the response will be JSON with the errors attribute containing an array of details of the error(s).

Sample JSON response body when an invalid URL has been requested.

{
  "error": {
    "errors": [
      {
        "property": "",
        "message": "No route found for \"POST \/foo\"",
        "code": "0d528fb3-569c-45fa-b2b5-309b360bf9fa",
        "type": "not_found"
      }
    ],
    "message": "Not Found",
    "code": "404"
  }
}

Method Not Allowed (Code 405)

If there is an error accessing a resource using the given HTTP verb, you’ll receive a “405 Method Not Allowed“ http response. The body of the response will be JSON with the errors attribute containing an array of details of the error(s).

Sample JSON response body when an valid URL has been requested with an invalid request method.

{
  "error": {
    "errors": [
      {
        "property": "",
        "message": "No route found for \"POST \/foo\": Method Not Allowed (Allow: GET)",
        "code": "5fe5c44b-f299-4fa6-bda4-bf80fecf6093",
        "type": "routing_error"
      }
    ],
    "message": "Method Not Allowed",
    "code": "405"
  }
}

Too Many Requests (Code 429)

This error code indicates that too many requests were sent within a period of time. See Rate limits for more information on this.

Sample JSON response body when a rate limit is hit.

    {
      "error": {
        "errors": [
          {
            "property": "",
            "message": "You have made too many requests recently, please try again later.",
            "code": "3b22ff00-96a5-4fa4-96cc-f36e68dbd2e2",
            "type": "too_many_requests"
          }
        ],
        "message": "Too Many Requests",
        "code": "429"
      }
    }

Internal System Error (Code 500)

If there is an internal error, you’ll receive a “500 Internal Server Error“ http response. The body of the response will be JSON with the errors attribute containing an array of details of the error(s).

v3 API endpoints use ISO-8601 date time format.

Example:

2019-03-01T12:01:00+00:00 - this example represents 1 minute past midday on the 1st of March 2019 in UTC.

2019-03-01 - date only example