New - Expand example descriptions

Contract Management API (1.3.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.2.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

Overview

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

Authorization

One of the following Scopes is needed to access this endpoint:- 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
name
required
string

Name for the billing address

phone
required
string

Phone for the billing address

city
required
string

City for the billing address

country
required
string

Country for the billing address

line_1
required
string

First line for the billing address

line_2
required
string

Second line for the billing address

post_code
required
string

Post code for the billing address

state
required
string

State for the billing address

required
object

Response samples

Content type
application/json
{
  • "name": "Partner name",
  • "phone": "+49175551219",
  • "city": "Koeln",
  • "country": "DE",
  • "line_1": "Im Mediapark 5",
  • "line_2": "Haus II",
  • "post_code": "50668",
  • "state": "Nordrhein-Westfalen",
  • "_links": {
    }
}

Partner

Overview

If you have access to a partner, then you can update all the relevant billing address information here.

Authorization

One of the following Scopes is needed to access this endpoint:- 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
name
required
string

Name for the billing address

phone
required
string

Phone for the billing address

city
required
string

City for the billing address

country
required
string

Country for the billing address

line_1
required
string

First line for the billing address

line_2
required
string

Second line for the billing address

post_code
required
string

Post code for the billing address

state
required
string

State for the billing address

required
object

Response samples

Content type
application/json
{
  • "name": "Partner name",
  • "phone": "+49175551219",
  • "city": "Koeln",
  • "country": "DE",
  • "line_1": "Im Mediapark 5",
  • "line_2": "Haus II",
  • "post_code": "50668",
  • "state": "Nordrhein-Westfalen",
  • "_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