Inventory | Service Instances

List owned service instances

get

Can be used to get the inventory of your own organization. This endpoint excludes instances in status removed.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Query parameters

servicesinteger · int32[]Optional

Filter by one or multiple specific services

locationsinteger · int32[]Optional

Filter by one or multiple specific locations

employeesinteger · int32[]Optional

Filter by one or multiple specific employees

groupsinteger · int32[]Optional

Filter by one or multiple specific groups

statusesstring[]Optional

Filter by one or multiple specific statuses

activebooleanOptional

Filter the instances which are active or not active. When null, all instances will be returned. Default: null

subscriptionPeriodRenewalsinteger · int32[]Optional

Filter by one or multiple specific values for the period renewal, e.g. to filter all without a renewal use 0

modifiedSincestring · date-timeOptional

Filter the instances modified after the specified date. A modification is identified when: the assignment changed, the instance got activated, the instance got cancelled

expiresAfterstring · date-timeOptional

Filter the instances which expire after this date

expiresBeforestring · date-timeOptional

Filter the instances which expire before this date

searchstringOptional

Filter for id, service name, inventory number, employee first and last name, group, location name or metadata values

sortBystring · enumOptional

Sort the instances by a given criterion

Possible values:

sortOrderstring · enumOptional

Order in which the result of a list request is sorted.

Possible values:

offsetinteger · int32Optional

Specifies the index of the first instances to return

Default: 0

limitinteger · int32Optional

Specifies the maximum number of instances to return

Default: 100

Responses

200

OK: A list of service instances.

application/json

totalinteger · int32Required

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key.

application/json

403

Forbidden: Resource access denied or resource does not exist anymore.

application/json

get/v1/inventory/service-instances

GET /v1/inventory/service-instances HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "previous": {
    "href": "text",
    "method": "text"
  },
  "next": {
    "href": "text",
    "method": "text"
  },
  "items": [
    {
      "supplier": {
        "id": 4,
        "name": "foo Inc.",
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "service": {
        "id": 4,
        "name": "Basic Plan",
        "category": "text",
        "ean": "0194253408253",
        "externalId": "E54363",
        "supplierName": "text",
        "previewImageLink": "text",
        "type": "service",
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "customer": {
        "id": 4,
        "name": "foo Inc.",
        "customerNumber": "C00001",
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "location": {
        "id": 1,
        "name": "HQ New York",
        "type": "location",
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "group": {
        "id": 42,
        "name": "Project 1337",
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "employee": {
        "id": 1,
        "firstName": "Pierce",
        "lastName": "Bell",
        "fullName": "text",
        "email": "p.bell@foo.io",
        "username": "j.doe@foo.inc",
        "costCenter": "4645-2343",
        "costCenterId": 1,
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "activationDate": "2026-07-15T15:50:19.556Z",
      "lastModifiedDate": "2026-07-15T15:50:19.556Z",
      "expirationDate": "2026-07-15T15:50:19.556Z",
      "processStatus": "ordered",
      "active": true,
      "oneTimeCosts": 92.99,
      "recurringCosts": 109.9,
      "currencyCode": "EUR",
      "subscriptionPeriod": 12,
      "subscriptionPeriodRenewal": 1,
      "note": "This is just a <b>custom note</b>.",
      "metadata": [
        {
          "key": "Serial number",
          "value": "SN45346X2345",
          "scope": "public"
        }
      ],
      "id": 42,
      "inventoryNumber": "EQ642",
      "costCenter": "4645-2343",
      "self": {
        "href": "text",
        "method": "text"
      }
    }
  ],
  "total": 1,
  "self": {
    "href": "text",
    "method": "text"
  }
}

Retrieve a single service instance by its id

get

Can be used to get a single instance from the inventory of your own organization.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

Responses

200

OK: The requested service instance.

application/json

activationDatestring · date-time · nullableOptional

The date the service instance was activated.

lastModifiedDatestring · date-time · nullableOptional

The date the service instance was last modified.

expirationDatestring · date-time · nullableOptional

The date when the service instance should expire.

processStatusstring · nullableOptional

The processing status of the service instance.

Example: ordered

activebooleanOptional

True if the service instance is active, otherwise false.

Example: true

oneTimeCostsnumber · doubleOptional

One-time purchase costs of the instance in its life cycle to date.

Example: 92.99

recurringCostsnumber · doubleOptional

The current recurring costs for the service instance. Only calculated for active instances.

Example: 109.9

currencyCodestring · nullableOptional

Currency in ISO 4217

Example: EUR

subscriptionPeriodinteger · int32 · nullableOptional

The minimum subscription period (in months) for the services instance.

Example: 12

subscriptionPeriodRenewalinteger · int32 · nullableOptional

Number of months a subscription is renewed after its expiration time if it has not been terminated.

Example: 1

notestring · nullableOptional

A note on the service instance. Supports html formatted text including inline css styles.

Example: This is just a <b>custom note</b>.

idinteger · int32Required

The id to identify the service instance in the system.

Example: 42

inventoryNumberstring · max: 50 · nullableOptional

The inventory number of the service instance.

Example: EQ642

costCenterstring · nullableOptional

The name of the cost center to which the service instance belongs.

Example: 4645-2343

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

get/v1/inventory/service-instances/{instanceId}

GET /v1/inventory/service-instances/{instanceId} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "supplier": {
    "id": 4,
    "name": "foo Inc.",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "service": {
    "id": 4,
    "name": "Basic Plan",
    "category": "text",
    "ean": "0194253408253",
    "externalId": "E54363",
    "supplierName": "text",
    "previewImageLink": "text",
    "type": "service",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "customer": {
    "id": 4,
    "name": "foo Inc.",
    "customerNumber": "C00001",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "location": {
    "id": 1,
    "name": "HQ New York",
    "type": "location",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "group": {
    "id": 42,
    "name": "Project 1337",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "employee": {
    "id": 1,
    "firstName": "Pierce",
    "lastName": "Bell",
    "fullName": "text",
    "email": "p.bell@foo.io",
    "username": "j.doe@foo.inc",
    "costCenter": "4645-2343",
    "costCenterId": 1,
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "activationDate": "2026-07-15T15:50:19.556Z",
  "lastModifiedDate": "2026-07-15T15:50:19.556Z",
  "expirationDate": "2026-07-15T15:50:19.556Z",
  "processStatus": "ordered",
  "active": true,
  "oneTimeCosts": 92.99,
  "recurringCosts": 109.9,
  "currencyCode": "EUR",
  "subscriptionPeriod": 12,
  "subscriptionPeriodRenewal": 1,
  "note": "This is just a <b>custom note</b>.",
  "metadata": [
    {
      "key": "Serial number",
      "value": "SN45346X2345",
      "scope": "public"
    }
  ],
  "id": 42,
  "inventoryNumber": "EQ642",
  "costCenter": "4645-2343",
  "self": {
    "href": "text",
    "method": "text"
  }
}

Remove a service instance from the inventory

delete

Sets the service instance to status 'removed' including all processes to remove the instance (e.g. stop and refund billing). The instance history still remains. Behavior is the same as when the service is canceled and termination gets processed.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance to be removed.

Query parameters

processingDatestring · date-timeOptional

The date on which the deletion is processed. Value must not be in the future

Responses

204

NoContent: Remove successful.

No content

400

Bad request: Body validation failed. See response message for details.

application/json

401

Unauthorized: Invalid api key.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

409

Conflict: Can not remove, because there are unprocessed changes or transition is invalid because of current status or open dependencies. See response message for details.

delete/v1/inventory/service-instances/{instanceId}

DELETE /v1/inventory/service-instances/{instanceId} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

No content

List metadata of a service instance

get

Retrieves the metadata of a service instance as a list of key/value pairs.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

Responses

200

OK: Service instance meta data.

application/json

keystring · max: 150Required

Key of the metadata entry.

Example: Serial number

valuestring · max: 500Required

The value of the metadata entry.

Example: SN45346X2345

scopestring · enumOptional

Defines for whom a metadata entry is visible. public: visible to all who have access to the service instance | internal: visible only to the author tenant

Possible values:

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

get/v1/inventory/service-instances/{instanceId}/metadata

GET /v1/inventory/service-instances/{instanceId}/metadata HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

[
  {
    "key": "Serial number",
    "value": "SN45346X2345",
    "scope": "public"
  }
]

Create or update the metadata of a service instance

put

The provided request body has to be a list of key/value pairs (see schema below).

A metadata key has to be unique within a service instance. If you provide the same key twice, the value of the first entry will just be overwritten.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

Bodyobject · MetadataEntry[]

keystring · max: 150Required

Key of the metadata entry.

Example: Serial number

valuestring · max: 500Required

The value of the metadata entry.

Example: SN45346X2345

scopestring · enumOptional

Defines for whom a metadata entry is visible. public: visible to all who have access to the service instance | internal: visible only to the author tenant

Possible values:

Responses

204

NoContent: Request has succeeded.

No content

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

put/v1/inventory/service-instances/{instanceId}/metadata

PUT /v1/inventory/service-instances/{instanceId}/metadata HTTP/1.1
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 65

[
  {
    "key": "Serial number",
    "value": "SN45346X2345",
    "scope": "public"
  }
]

No content

Delete all metadata of a service instance

delete

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

Responses

204

NoContent: Request has succeeded.

No content

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

delete/v1/inventory/service-instances/{instanceId}/metadata

DELETE /v1/inventory/service-instances/{instanceId}/metadata HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

No content

Retrieve a metadata entry of a service instance by its specified key

get

Retrieves a single metadata entry of a service instance as a key/value pair.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

keystringRequired

The key of the metadata value to retrieve.

Responses

200

OK: Service instance meta data value.

application/json

keystring · max: 150Required

Key of the metadata entry.

Example: Serial number

valuestring · max: 500Required

The value of the metadata entry.

Example: SN45346X2345

scopestring · enumOptional

Defines for whom a metadata entry is visible. public: visible to all who have access to the service instance | internal: visible only to the author tenant

Possible values:

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

get/v1/inventory/service-instances/{instanceId}/metadata/{key}

GET /v1/inventory/service-instances/{instanceId}/metadata/{key} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "key": "Serial number",
  "value": "SN45346X2345",
  "scope": "public"
}

Create or update a single metadata entry of a service instance

put

The provided request body has to be a metadata value(see schema below).

A metadata key is unique within a service instance. If you want to add the same information but with a different key, remove the existing and add the data as a new entry.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

keystring · max: 150Required

The key of the metadata value to create or update.

Body

valuestring · max: 500Required

The value of the metadata entry.

Example: SN45346X2345

scopestring · enumOptional

Defines for whom a metadata entry is visible. public: visible to all who have access to the service instance | internal: visible only to the author tenant

Possible values:

Responses

204

NoContent: Request has succeeded.

No content

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

put/v1/inventory/service-instances/{instanceId}/metadata/{key}

PUT /v1/inventory/service-instances/{instanceId}/metadata/{key} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "value": "SN45346X2345",
  "scope": "public"
}

No content

Delete a single metadata entry of a service instance.

delete

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

keystringRequired

The key of the metadata value to delete.

Responses

204

NoContent: Request has succeeded.

No content

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

delete/v1/inventory/service-instances/{instanceId}/metadata/{key}

DELETE /v1/inventory/service-instances/{instanceId}/metadata/{key} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

No content

Last updated 3 hours ago

Was this helpful?