Overview & Prerequisites

The Printix API for partners currently supports these operations:

  • Listing active, managed tenants.

  • Creating a new tenant.

  • Viewing an existing tenant.

  • Viewing the billing information for a tenant.

Before using this API, you need to obtain a partnerId, clientId, and client secret for each environment you wish to test. These are provided by Printix through out-of-band methods like email.

Authentication

The authentication host is https://auth.printix.net. The API implements the OAuth2 client credentials flow. Clients exchange their credentials for authentication and refresh tokens at the token endpoint: https://auth.printix.net/oauth/token (production) or https://auth.testenv.printix.net/oauth/token (test environment).

Request Tokens

POST /oauth/token

POST /oauth/token HTTP/1.1
Host: auth.printix.net
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={clientId}&client_secret={clientSecret}

Response (200):

{
  "access_token": "5a8c4ec4-ff70-4f4c-b088-29a8cae38062",
  "refresh_token": "e6f05338-9d27-466b-afa8-0ce72945da7d",
  "expires_in": 599
}

Refresh Tokens

POST /oauth/token

POST /oauth/token HTTP/1.1
Host: auth.printix.net
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&client_id={clientId}&refresh_token={refreshToken}

Response (200):

{
  "access_token": "5a8c4ec4-ff70-4f4c-b088-29a8cae38062",
  "refresh_token": "e6f05338-9d27-466b-afa8-0ce72945da7d",
  "expires_in": 599
}

Tenants

List Tenants

Fetches a list of previously created tenants.

Table 1. /public/partners/{partnerId}/tenants
Parameter Description

partnerId

The id of the partner.
Parameter Description

include-inactive

Whether to include deactivated and deleted tenants. Defaults to false.
request
GET /public/partners/11111111-1111-1111-1111-111111111111/tenants?include-inactive=false HTTP/1.1
Accept: application/hal+json
Host: api.printix.net
response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 888

{
  "tenants" : [ {
    "_embedded" : { },
    "_links" : {
      "self" : {
        "href" : "https://api.printix.net/public/partners/11111111-1111-1111-1111-111111111111/tenants/22222222-2222-2222-2222-222222222222"
      },
      "px:billing-info" : {
        "href" : "https://api.printix.net/public/partners/11111111-1111-1111-1111-111111111111/tenants/22222222-2222-2222-2222-222222222222/billing-info"
      },
      "web:user_app" : {
        "href" : "acme.printix.net"
      },
      "web:administrator" : {
        "href" : "acme.printix.net/admin"
      }
    },
    "active" : true,
    "created_at" : "2017-11-24T16:15:10.480Z",
    "tenant_domain" : "acme.printix.net",
    "tenant_name" : "Acme Co."
  } ],
  "_links" : {
    "self" : {
      "href" : "https://api.printix.net/public/partners/11111111-1111-1111-1111-111111111111/tenants?include-inactive=true"
    }
  }
}
Path Type Description

tenants

Array

The list of previously created tenants. Each tenant has the fields described under Fetching a single tenant.

_links

Object

Link to this collection.

Create new tenant

To create a new tenant, perform a POST request to the tenants endpoint. The JSON payload must include at least a tenant_name and a tenant_domain.

  • tenant_name: The actual name of the tenant to create. A freeform string that can contain capital letters, spaces and special characters. Max size 100 characters.

  • tenant_domain: should be a (sub)domain name, it will be used to generate the Printix Home of the customer, where they can manage their solution and release documents. This value should include only lowercase alphanumeric characters and dashes. So, for example, for a customer named Acme C/O a logical tenant_domain would be acme, and the Printix administrator for the customer would then be available on https://acme.printix.net.

Optionally a client can also include:

  • initial_user: Useful if the client should be granted access to manage their own Printix solution. If this is not supplied, no users will be created on the tenant, and the partner would need to manually invite the users. If the user has never signed into Printix before, they will need to reset their password the first time they access either the Printix administrator or the user app. initial_user has the following properties:

  • email: The email of the user. This will also be their login name.

  • name: The name of the user.

  • create_as_admin: should the user be created as a Printix administrator, either true or false, the default is false.

Table 2. /public/partners/{partnerId}/tenants
Parameter Description

partnerId

The id of the partner.
Path Type Description

tenant_name

String

The actual name of the tenant to create. A freeform string that can contain capital letters, spaces and special characters. Max size 100 characters.

tenant_domain

String

Should be a (sub)domain name; it will be used to generate the Printix Home of the customer, where they can manage their solution and release documents. This value should include only lowercase alphanumeric characters and dashes.

initial_user

Object

Useful if the client should be granted access to manage their own Printix solution. If not supplied, no users are created and the partner must invite them manually.

initial_user.email

String

The email of the user. This will also be their login name.

initial_user.name

String

The name of the user.

initial_user.create_as_admin

Boolean

Whether the user is created as a Printix administrator, either true or false. The default is false.
request
POST /public/partners/11111111-1111-1111-1111-111111111111/tenants HTTP/1.1
Content-Type: application/json
Accept: application/hal+json
Content-Length: 178
Host: api.printix.net

{
  "tenant_name" : "Acme Co.",
  "tenant_domain" : "acme",
  "initial_user" : {
    "email" : "admin@acme.example",
    "name" : "Alex Admin",
    "create_as_admin" : true
  }
}
response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1315

{
  "_embedded" : {
    "billing_info" : {
      "_links" : {
        "self" : {
          "href" : "https://api.printix.net/public/partners/11111111-1111-1111-1111-111111111111/tenants/22222222-2222-2222-2222-222222222222/billing-info"
        }
      },
      "current_billing_period" : {
        "active_users" : 1,
        "period_end" : "2017-12-24T16:15:10.480Z",
        "period_start" : "2017-11-24T16:15:10.480Z",
        "printing_users" : 1
      },
      "previous_billing_period" : {
        "active_users" : 1,
        "period_end" : "2017-11-24T16:15:10.480Z",
        "period_start" : "2017-10-24T16:15:10.480Z",
        "printing_users" : 1
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "https://api.printix.net/public/partners/11111111-1111-1111-1111-111111111111/tenants/22222222-2222-2222-2222-222222222222"
    },
    "px:billing-info" : {
      "href" : "https://api.printix.net/public/partners/11111111-1111-1111-1111-111111111111/tenants/22222222-2222-2222-2222-222222222222/billing-info"
    },
    "web:user_app" : {
      "href" : "acme.printix.net"
    },
    "web:administrator" : {
      "href" : "acme.printix.net/admin"
    }
  },
  "active" : true,
  "created_at" : "2017-11-24T16:15:10.480Z",
  "tenant_domain" : "acme.printix.net",
  "tenant_name" : "Acme Co."
}
Path Type Description

tenant_name

String

The name of the created tenant.

active

Boolean

Whether the tenant is currently active.

created_at

String

When the tenant was created.

tenant_domain

String

The primary hosting domain of the tenant.

deactivated_time

String

When the tenant was deactivated, if applicable.

deleted_time

String

When the tenant was deleted, if applicable.

_embedded

Object

The tenant’s billing information; see Get billing information.

_links

Object

Links to the created tenant and its billing information.

Interacting with a single tenant

Fetching a single tenant

Viewing a single tenant is done by making a GET request to the tenant url.

Table 3. /public/partners/{partnerId}/tenants/{tenantId}
Parameter Description

partnerId

The id of the partner.

tenantId

The id of the tenant.
Parameter Description

embed

Set to billing-info to embed the tenant’s billing information in the response.
request
GET /public/partners/11111111-1111-1111-1111-111111111111/tenants/22222222-2222-2222-2222-222222222222?embed=billing-info HTTP/1.1
Accept: application/hal+json
Host: api.printix.net
response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 1315

{
  "_embedded" : {
    "billing_info" : {
      "_links" : {
        "self" : {
          "href" : "https://api.printix.net/public/partners/11111111-1111-1111-1111-111111111111/tenants/22222222-2222-2222-2222-222222222222/billing-info"
        }
      },
      "current_billing_period" : {
        "active_users" : 1,
        "period_end" : "2017-12-24T16:15:10.480Z",
        "period_start" : "2017-11-24T16:15:10.480Z",
        "printing_users" : 1
      },
      "previous_billing_period" : {
        "active_users" : 1,
        "period_end" : "2017-11-24T16:15:10.480Z",
        "period_start" : "2017-10-24T16:15:10.480Z",
        "printing_users" : 1
      }
    }
  },
  "_links" : {
    "self" : {
      "href" : "https://api.printix.net/public/partners/11111111-1111-1111-1111-111111111111/tenants/22222222-2222-2222-2222-222222222222"
    },
    "px:billing-info" : {
      "href" : "https://api.printix.net/public/partners/11111111-1111-1111-1111-111111111111/tenants/22222222-2222-2222-2222-222222222222/billing-info"
    },
    "web:user_app" : {
      "href" : "acme.printix.net"
    },
    "web:administrator" : {
      "href" : "acme.printix.net/admin"
    }
  },
  "active" : true,
  "created_at" : "2017-11-24T16:15:10.480Z",
  "tenant_domain" : "acme.printix.net",
  "tenant_name" : "Acme Co."
}
Path Type Description

tenant_name

String

The name of the tenant.

active

Boolean

Whether the tenant is currently active.

created_at

String

When the tenant was created.

tenant_domain

String

The primary hosting domain of the tenant.

deactivated_time

String

When the tenant was deactivated, if applicable.

deleted_time

String

When the tenant was deleted, if applicable.

_embedded

Object

Present when embed=billing-info is requested; see Get billing information.

_links

Object

Links to this tenant and its billing information.

Billing information

Get billing information

Table 4. /public/partners/{partnerId}/tenants/{tenantId}/billing-info
Parameter Description

partnerId

The id of the partner.

tenantId

The id of the tenant.
request
GET /public/partners/11111111-1111-1111-1111-111111111111/tenants/22222222-2222-2222-2222-222222222222/billing-info HTTP/1.1
Accept: application/hal+json
Host: api.printix.net
response
HTTP/1.1 200 OK
Content-Type: application/hal+json
Content-Length: 558

{
  "_links" : {
    "self" : {
      "href" : "https://api.printix.net/public/partners/11111111-1111-1111-1111-111111111111/tenants/22222222-2222-2222-2222-222222222222/billing-info"
    }
  },
  "current_billing_period" : {
    "active_users" : 1,
    "period_end" : "2017-12-24T16:15:10.480Z",
    "period_start" : "2017-11-24T16:15:10.480Z",
    "printing_users" : 1
  },
  "previous_billing_period" : {
    "active_users" : 1,
    "period_end" : "2017-11-24T16:15:10.480Z",
    "period_start" : "2017-10-24T16:15:10.480Z",
    "printing_users" : 1
  }
}
Path Type Description

current_billing_period.period_start

String

Start of the current billing period.

current_billing_period.period_end

String

End of the current billing period.

current_billing_period.printing_users

Number

Number of printing users in the current period.

current_billing_period.active_users

Number

Number of active users in the current period.

previous_billing_period

Object

The previous billing period, when one exists.

current_user_licenses

Number

The number of purchased user licenses, when set.

_links

Object

Link to this billing information.