Company

The Company API provides readonly access to your company’s contracts with ICEYE.

Role of contracts in the API

An ICEYE contract effectively defines a kind of profile, with settings that regulate and affect the behavior of the API. The contract affects API invocations in the following ways:

Defines the level of service your company is contracted for.
Unlocks specific tasking options.
Defines default settings for some of the tasking options.
Provides a collection of delivery locations for delivering tasking data products and purchased catalog items.

One company can potentially have multiple contracts with ICEYE. For example, when an authenticated user retrieves a list of contracts from the API, the response can contain more than one contract. This means that, in addition to selecting ICEYE as a SAR provider, the end user needs to specify which contract to use for API invocations during a session.

You cannot create a new contract using the APIs. At the time when your company negotiates a new contract with ICEYE, the Customer Operations and Satellite Planning (COSP) team creates a new contract object, as part of the process of setting up your company’s account.

Rules for tasking options

The contract defines a set of rules for the tasking parameters, constraining the options you can select when submitting a task and also defining default values.

Allowed options

The following tasking operations are affected by parameter rules in the contract (and require you to include a contract ID in the request):

For each specified parameter that is subject to a contract rule, the relevant rule is applied as follows:

If the specified parameter value is listed as an allowed value in the contract, the parameter value is accepted.
If the specified parameter value is not listed as an allowed value in the contract, the invocation is interrupted and an error response is returned.

If an optional parameter is not specified when invoking createTask, the default behavior is explained in Default options.

For example, consider the priority parameter from createTask which can take one of the values BACKGROUND or COMMERCIAL. Given a contract that allows only the BACKGROUND option:

"priority": {
  "allowed": [
    "BACKGROUND"
  ],
  "default": "BACKGROUND"
},

If you invoke createTask with this contract and specify the COMMERCIAL option:

"priority": "COMMERCIAL",

The invocation fails and returns an error response.

Default options

The createTask operation has multiple optional parameters. If you do not specify the value of an optional parameter in a createTask invocation, the following rules are used to select a default:

If the contract allows only a single value for the parameter, this value is used as the default.
If the contract allows multiple values for the parameter, the contract-defined default value is used.

For example, consider the exclusivity parameter from createTask, which can take one of the values PUBLIC or PRIVATE.

You have a contract that allows only the PUBLIC option:
```
"exclusivity": {
  "allowed": [
    "PUBLIC"
  ],
  "default": "PUBLIC"
}
```
In this case, the parameter defaults to PUBLIC.
You have a contract that allows both the PUBLIC and PRIVATE options, and the contract defines a default value:
```
"exclusivity": {
  "allowed": [
    "PUBLIC",
    "PRIVATE"
  ],
  "default": "PUBLIC"
}
```
In this case, the parameter defaults to PUBLIC.

Delivery locations

At the time when your company negotiates a new contract with ICEYE, your company can request COSP to set up specific delivery locations (AWS S3 or SFTP) for receiving delivery of tasking data products and purchased catalog items. You can access the list of delivery locations by invoking either getContract or listContracts.

Delivery locations are returned in the form of a list, for example:

"deliveryLocations": [
  {
    "method": "sftp",
    "path": "url-string"
  }
],

You can choose specific delivery locations by providing a list of delivery locations to the relevant operations (for example, createTask).

Pricing scope

A contract can define a scope for the calculation of prices.

Contracts are integrated with the pricing model and different contracts can be associated with different pricing plans (or not be associated with any pricing plan). Because of this, when you request a quotation for a task (by invoking getTaskPrice), it matters which contract ID you send with the request. Similarly, the cost of a task created by invoking the createTask operation is affected by the contract ID.

Accessing a contract budget

The company API gives you readonly access to the details of a contract’s budget, by calling the getSummary operation.

For example, a typical response to getSummary is:

{
  "contractID": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXX",
  "consolidatedSpent" : 900000,
  "currency" : "USD",
  "onHold" : 1000000,
  "spendLimit" : 2000000
}

For more details, see getSummary and Pricing model.

The getSummary operation is available, only if your contract is associated with a pricing plan. Otherwise it returns the HTTP 404 - not found error.