Get contract

GET /company/v1/contracts/{contractID}

The getContract operation enables you to view representations of your agreements with ICEYE in the form of contracts. A contract stores information regarding the validity of your agreement, its allowed values, and its defaults. Contracts are set by your ICEYE representative and grant you access to various aspects of the ICEYE API Platform.

Contract types

Contracts can be created with or without a pricing model. A pricing model is a set of rules that govern the price of a task. Pricing model contracts enable visibility on how much you will spend and how much you have spent in a contract using the getTaskPrice and getSummary operations.

These operations do not represent returns or penalties and ICEYE has a separate process for invoicing.

Contract resource

These configurations are read-only. In case of any discrepancies, please reach out to your COSP representative.
Field Description

id

The unique contractID, specified as a UUID, that is used for tasking.

name

The distinguishable name to identify the purpose of the contract.

start, end

The timestamps between which you are allowed to submit tasks.

deliveryLocations

The method and location where delivery has been approved

imagingModes.allowed

The imaging modes allowed to task with this contract.

imagingModeCapabilities

Per-imaging-mode capabilities detailing available product types. Each entry contains a mode identifier, and a productTypes object with allowed (all available product types) and slaApplicable (product types against which SLAs are measured). When you request products from the slaApplicable list, only the products you request are used for SLA measurement (e.g., if there are 3 slaApplicable products and you request 1, that 1 is used; if you request all 3, all 3 are used).

priority.allowed

The priorities allowed to task with this contract.

priority.default

The default priority used to task when not specified in the tasking request. This can be COMMERCIAL or BACKGROUND depending on what is allowed.

exclusivity.allowed

The exclusivities allowed to task with this contract.

exclusivity.default

The default exclusivity used to task when not specified in the tasking request. This can be PRIVATE or PUBLIC depending on what is allowed.

Delivery

To enable automatic delivery, you must request your COSP representative to set up a valid delivery location (SFTP and/or AWS S3) in your contract. After the setup is done, you can specify the delivery location(s) in the Tasking API.

Defaults

Your contracts dictate the defaults that will be used for all optional fields not specified when tasking. These defaults are implied when you only have one allowed value and are manually set only when multiple values are allowed.
For example, if you can only task with PRIVATE exclusivity, then the default will be PRIVATE. On the other hand, if both PRIVATE and PUBLIC exclusivities are allowed, then your default is set by your COSP representative at the time of contract initiation.

When you omit productTypes in a tasking request, the slaApplicable products from your contract’s imagingModeCapabilities are used as the default.

You must keep track of our default to ensure you do not erroneously apply an incorrect default when tasking. To avoid this always specify parameters explicitly.

Preexisting contracts

Before the Company API release in May 2024, ICEYE had a slightly different structure for contracts. Both the priority and exclusivity were added as part the new suite of APIs. All contracts created before these changes have:

  • priority.allowed and priority.default as COMMERCIAL

  • exclusivity.allowed as both PUBLIC and PRIVATE

To avoid any issues, it is recommended to use your exclusivity.default for any preexisting contracts.

Example

Request

Enter the following curl command, remembering to replace the ${VARNAME} variables with the appropriate values:

curl --location "${API_BASE_URL}/api/company/v1/contracts/${contractID}" \
--header "Accept: application/json, application/problem+json" \
--header "Authorization: Bearer ${API_ACCESS_TOKEN}"

Response

On success, returns a 200 status code and a JSON object containing the details of the customer contracts.

{
  "id": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
  "name": "string",
  "start": "2019-08-24T14:15:22Z",
  "end": "2019-09-24T14:15:22Z",
  "deliveryLocations": [
    {
      "method": "sftp",
      "path": "string"
    }
  ],
  "imagingModes": {
    "allowed": [
      [
          "SPOTLIGHT",
          "SCAN",
          "STRIPMAP"
      ]
    ]
  },
  "imagingModeCapabilities": [
    {
      "mode": "SPOTLIGHT",
      "productTypes": {
        "allowed": ["SLC", "GRD", "QUICKLOOK"],
        "slaApplicable": ["SLC", "GRD"]
      }
    },
    {
      "mode": "SCAN",
      "productTypes": {
        "allowed": ["GRD", "QUICKLOOK"],
        "slaApplicable": ["GRD"]
      }
    },
    {
      "mode": "STRIPMAP",
      "productTypes": {
        "allowed": ["SLC", "GRD", "QUICKLOOK"],
        "slaApplicable": ["SLC", "GRD"]
      }
    }
  ],
  "priority": {
    "allowed": [
      "BACKGROUND"
    ],
    "default": "BACKGROUND"
  },
  "exclusivity": {
    "allowed": [
      "PUBLIC"
    ],
    "default": "PUBLIC"
  }
}