New - Expand example descriptions

Contract Management API (1.1.0)

Download OpenAPI specification:Download

Introduction

The Contract Management API allows you to manage your gridscale contracts.

This API includes the following functions/areas:

  • Provides you with an overview of your contracts & partner.
  • Provides you with the current payment/billing information and valid prices for your contracts.
  • Allows you to manage your price lists and assign them to your contracts.
  • WIP: Provides you with an overview of your invoices.
  • WIP: Allows you to manage your payment/billing information for your contracts.

Authentification & Authorization

To access this API, you need an valid X-Auth-Token and your X-Auth-UserId. As Partner, you get them in the API Keys section in your Partner Panel. As a regular user, you can find them in your API Token seciton in your panel and there you need to create an unlimited token.

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

After you have successfully authenticated against the API, you still need the appropriate authorization for the various endpoints. Which authorizations you have depends on your user roles, with which you have created the API token. You can set different access rights for the contracts you have access to. The required scopes for a request can be found in the endpoint description.

You can have multiple of this scopes:

    - PARTNER_READ
    - PARTNER_WRITE
    - PARTNER_ADMIN
    - CONTRACT_READ
    - CONTRACT_WRITE
    - CONTRACT_ADMIN
    - CONTRACT_OWNER

Errors

This API uses traditional HTTP response codes to indicate the success or failure of an API request. Therefore, the following applies: Codes in the 2xx range indicate successful processing of the request. Codes in the 4xx range indicate an error. Codes in the 5xx range indicate a very rare error at gridscale and are reported to gridscale fully automatically.

HTTP response codes in the 4xx range return a JSON response based on the RFC-7807 standard. The response can contain several individual problems that describe the error in more detail. For most of the errors, you can find more information if you follow the link in the type resource.

Example:

{
  "errors": [
    {
      "type": "https:\/\/my.gridscale.io\/schema\/problem\/not-found",
      "title": "Not Found",
      "status": 404,
      "detail": "The requested resource was not found. Read the API DOC https:\/\/https://api.gridscale.io/management\/management\/v1\/schema.json for more information.",
      "instance": "\/management\/v1\/",
      "data": [

      ]
    }
  ]
}

Request Identifier

Each API request contains a Correlate ID in the response. This ID can be found in the response headers under: x-correlate-id . If you ever need to contact the gridscale support for a query, please include this x-correlate-id if possible.

Versioning

The Contract Management API is currently available in major version 1.1.0 You decide which version of the API you use via the API endpoint path.

When a new backwards incompatible version of the API appears, a new major version is provided. Once a new major version is released, an deprecation & sunset date is set for the previous version. They can be found in this document, as well as in the response headers of each request.

Minor API changes that are backwards compatible will be rolled out periodically. Detailed information can be found in the changelog. The currently used API version can be found in the X-Api-Version header.

Deprecation: unknown
Sunset: unknown

Partner

The partner area allows you to manage your partner contract relationship

Partner

Overview

If you have access to a partner, then you will get all the relevant billing information displayed here.

Authorization

One of the following Scopes is needed to access this endpoint:

  • PARTNER_READ
  • PARTNER_WRITE
  • PARTNER_ADMIN

Responses

Response Headers
X-Powered-By
required
string
Example: "Contract Management API"

API Name

X-Api-Version
required
string
Example: "1.1.0"

API Version

Content-Type
required
string
Example: "application/json"

Content Type

X-Correlate-Id
required
string
Example: "bca9bdf1-43fb-4d40-81d2-5e78a3ea766d"

Correlation UUID

Sunset
string
Example: "Tue, 01 Nov 2000 12:45:26 GMT"

Sunset date of this API version if known

Deprecation
string
Example: "Tue, 01 Nov 2000 12:45:26 GMT"

Deprecation date of this API Version if known

Response Schema: application/json
partner_uuid
required
string <uuid> (UuidPartner)

Unique UUID of the partner

name
required
string

Name of the Partner Account

billing_info
required
string (BillingInfo)

Postal address as it will be found on the next invoice.

billing_email
required
string <email> (BillingEmail)

Commaseperated e-mail addresses, which will be sent the invoice.

vat_id
required
string (VatId)

VAT ID, which is entered for the record. It will be found on the next invoice when billing is activated.

required
object

Response samples

Content type
application/json
{
  • "partner_uuid": "fd24b847-6008-4ac3-a638-a89be42053d4",
  • "name": "Partner name",
  • "billing_info": "Company Gmbh Musterstrasse 111 12345 Musterstadt",
  • "billing_email": "billing@company.com",
  • "vat_id": "12/345/67890",
  • "_links": {
    }
}

Partner Prices

Overview

Get Partner Prices

Authorization

One of the following Scopes is needed to access this endpoint:

  • PARTNER_READ
  • PARTNER_WRITE
  • PARTNER_ADMIN

Responses

Response Headers
X-Powered-By
required
string
Example: "Contract Management API"

API Name

X-Api-Version
required
string
Example: "1.1.0"

API Version

Content-Type
required
string
Example: "application/json"

Content Type

X-Correlate-Id
required
string
Example: "bca9bdf1-43fb-4d40-81d2-5e78a3ea766d"

Correlation UUID

Sunset
string
Example: "Tue, 01 Nov 2000 12:45:26 GMT"

Sunset date of this API version if known

Deprecation
string
Example: "Tue, 01 Nov 2000 12:45:26 GMT"

Deprecation date of this API Version if known

Response Schema: application/json
required
Array of objects (PriceListLocationListItem)

Response samples

Content type
application/json
{
  • "locations": [
    ]
}

Price Lists

Manage your price lists

Price lists

Overview

Will return all your price lists

Authorization

One of the following Scopes is needed to access this endpoint:

  • PARTNER_READ
  • PARTNER_WRITE
  • PARTNER_ADMIN

Responses

Response Headers
X-Powered-By
required
string
Example: "Contract Management API"

API Name

X-Api-Version
required
string
Example: "1.1.0"

API Version

Content-Type
required
string
Example: "application/json"

Content Type

X-Correlate-Id
required
string
Example: "bca9bdf1-43fb-4d40-81d2-5e78a3ea766d"

Correlation UUID

Sunset
string
Example: "Tue, 01 Nov 2000 12:45:26 GMT"

Sunset date of this API version if known

Deprecation
string
Example: "Tue, 01 Nov 2000 12:45:26 GMT"

Deprecation date of this API Version if known

Response Schema: application/json
Array ()
price_list_uuid
required
string <uuid> (UuidPriceList)

Unique UUID of the price list

name
required
string (PriceListName)

Name of the price list. It is visible in the panel for the users.

is_default_price_list
required
boolean (IsDefaultPriceList)

The default price list is automatically assigned to new contracts. There can only be one default price list. If you set the flag for a price list, it will be removed from the previous one. You are not able to patch this field to "false". You need to set it to true to a different price list.

contracts
required
Array of strings <uuid> (Contracts)

All contracts listed here are currently assigned to this price list.

required
object

Response samples

Content type
application/json
[
  • {
    }
]

Price list

Overview

Authorization

One of the following Scopes is needed to access this endpoint:

  • PARTNER_WRITE
  • PARTNER_ADMIN
Request Body schema: application/json

The payload for creating a new price list for a partner.

name
required
string (PriceListName)

Name of the price list. It is visible in the panel for the users.

is_default_price_list
boolean (IsDefaultPriceList)

The default price list is automatically assigned to new contracts. There can only be one default price list. If you set the flag for a price list, it will be removed from the previous one. You are not able to patch this field to "false". You need to set it to true to a different price list.

contracts
Array of strings <uuid> (Contracts)

All contracts listed here are currently assigned to this price list.

Responses

Response Headers
X-Powered-By
required
string
Example: "Contract Management API"

API Name

X-Api-Version
required
string
Example: "1.1.0"

API Version

Content-Type
required
string
Example: "application/json"

Content Type

X-Correlate-Id
required
string
Example: "bca9bdf1-43fb-4d40-81d2-5e78a3ea766d"

Correlation UUID

Sunset
string
Example: "Tue, 01 Nov 2000 12:45:26 GMT"