Sales | Customers

List your customers

get

Retrieve a list of customers.

You can only access customers of your provider entity.

Authorizations

ApiKey

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

activebooleanOptional

If null, all customers are returned. True: only active | false: only inactive customers are returned.

createdAfterstring · date-timeOptional

Filter the customers created after the specified date.

namesstring[]Optional

Filter the customers by one or multiple names

customerNumbersstring[]Optional

Filter the customers by one or multiple customer numbers

sortBystring · enumOptional

Parameters according to which a customer can be sorted.

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 item to return

Default: 0

limitinteger · int32Optional

Specifies the maximum number of items to return (min: 1; max: 1000)

Default: 100

Responses

200

OK: A list of customers.

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/sales/customers

HTTPcURLJavaScriptPython

GET /v1/sales/customers HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "previous": {
    "href": "text",
    "method": "text"
  },
  "next": {
    "href": "text",
    "method": "text"
  },
  "items": [
    {
      "uuid": "123e4567-e89b-12d3-a456-426614174000",
      "description": "text",
      "active": true,
      "contactName": "John Doe",
      "contactEmail": "[e-mail]",
      "contactPhone": "[phone]",
      "customAttribute1": "text",
      "customAttribute2": "text",
      "customAttribute3": "text",
      "accountManager": {
        "id": 1,
        "firstName": "Pierce",
        "lastName": "Bell",
        "fullName": "text",
        "email": "[e-mail]",
        "username": "[e-mail]",
        "costCenter": "4645-2343",
        "costCenterId": 1,
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "language": "en",
      "companyAddress": {
        "line1": "equipme GmbH",
        "street": "W 55th St",
        "number": 240,
        "addition": "3rd floor",
        "city": "New York",
        "postalCode": 10019,
        "countryCode": "US",
        "regionCode": "NY",
        "regionName": "New York",
        "dependentLocality": "Chilmington Green",
        "phoneNumber": "[phone]",
        "id": 83,
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "referredBy": {
        "referredOn": "2026-07-15T17:06:53.197Z",
        "company": {
          "id": 4,
          "name": "foo Inc.",
          "customerNumber": "C00001",
          "self": {
            "href": "text",
            "method": "text"
          }
        },
        "employee": {
          "id": 1,
          "firstName": "Pierce",
          "lastName": "Bell",
          "fullName": "text",
          "email": "[e-mail]",
          "username": "[e-mail]",
          "costCenter": "4645-2343",
          "costCenterId": 1,
          "self": {
            "href": "text",
            "method": "text"
          }
        }
      },
      "id": 4,
      "name": "foo Inc.",
      "customerNumber": "C00001",
      "self": {
        "href": "text",
        "method": "text"
      }
    }
  ],
  "total": 1,
  "self": {
    "href": "text",
    "method": "text"
  }
}

Create a customer

post

You can only create customers for your provider entity.

When a customer is created, an instance of the "Customer Account" system service is also always added to the customer's approval cart.

Note: active customers are allowed to place orders.

Authorizations

ApiKey

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.

Body

application/json

namestring · max: 100Required

The name of the customer.

Example: foo Inc.

customerNumberstring · max: 50 · nullableOptional

Optional identifier of the customer defined by the supplier.

Example: C00001

descriptionstring · max: 500 · nullableOptional

The description of the customer.

activebooleanOptional

True if the customer is active and is allowed to place orders, false otherwise.

Example: true

customAttribute1string · max: 100 · nullableOptional

Value of the first custom attribute as defined in the settings

customAttribute2string · max: 100 · nullableOptional

Value of the second custom attribute as defined in the settings

customAttribute3string · max: 100 · nullableOptional

Value of the third custom attribute as defined in the settings

contactNamestring · max: 200 · nullableOptional

The name of the contact person at the customer.

Example: John Doe

contactEmailstring · max: 100 · nullableOptional

The mail of the contact person at the customer.

Example: [e-mail]

contactPhonestring · max: 50 · nullableOptional

The phone number of the contact person at the customer.

Example: [phone]

languagestring · enumOptional

Language options for a customer or user interaction

Possible values:

accountManagerinteger · int32 · nullableOptional

The id of the responsible sales person for the customer. This employee receives planner access to the customer, when not specified otherwise through the tenant permissions.

Responses

201

Created: The created customer.

application/json

uuidstring · uuidOptional

The identifier of the customer.

descriptionstring · nullableOptional

The description of the customer.

activebooleanOptional

True if the customer is active, false otherwise.

Example: true

contactNamestring · nullableOptional

The name of the contact person at the customer.

Example: John Doe

contactEmailstring · nullableOptional

The email address of the contact person at the customer.

Example: [e-mail]

contactPhonestring · nullableOptional

The phone number of the contact person at the customer.

Example: [phone]

customAttribute1string · nullableOptional

Value of the first custom attribute as defined in the settings

customAttribute2string · nullableOptional

Value of the second custom attribute as defined in the settings

customAttribute3string · nullableOptional

Value of the third custom attribute as defined in the settings

languagestring · enumOptional

Language options for a customer or user interaction

Possible values:

idinteger · int32Required

The identifier of the customer.

Example: 4

namestring · min: 1Required

The name of the customer.

Example: foo Inc.

customerNumberstring · nullableOptional

Optional identifier of the customer defined by the supplier.

Example: C00001

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

post/v1/sales/customers

HTTPcURLJavaScriptPython

POST /v1/sales/customers HTTP/1.1
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 882

{
  "name": "foo Inc.",
  "customerNumber": "C00001",
  "description": "text",
  "active": true,
  "customAttribute1": "text",
  "customAttribute2": "text",
  "customAttribute3": "text",
  "contactName": "John Doe",
  "contactEmail": "[e-mail]",
  "contactPhone": "[phone]",
  "language": "en",
  "tenantPermissions": [
    {
      "employeeId": 42,
      "role": "administrator"
    }
  ],
  "accountManager": 1,
  "companyAddress": {
    "line1": "equipme GmbH",
    "street": "W 55th St",
    "number": 240,
    "addition": "3rd floor",
    "city": "New York",
    "postalCode": 10019,
    "countryCode": "US",
    "regionCode": "NY",
    "regionName": "New York",
    "dependentLocality": "Chilmington Green",
    "phoneNumber": "[phone]"
  },
  "billingAddress": {
    "line1": "equipme GmbH",
    "street": "W 55th St",
    "number": 240,
    "addition": "3rd floor",
    "city": "New York",
    "postalCode": 10019,
    "countryCode": "US",
    "regionCode": "NY",
    "regionName": "New York",
    "dependentLocality": "Chilmington Green",
    "phoneNumber": "[phone]"
  }
}

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "description": "text",
  "active": true,
  "contactName": "John Doe",
  "contactEmail": "[e-mail]",
  "contactPhone": "[phone]",
  "customAttribute1": "text",
  "customAttribute2": "text",
  "customAttribute3": "text",
  "accountManager": {
    "id": 1,
    "firstName": "Pierce",
    "lastName": "Bell",
    "fullName": "text",
    "email": "[e-mail]",
    "username": "[e-mail]",
    "costCenter": "4645-2343",
    "costCenterId": 1,
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "language": "en",
  "companyAddress": {
    "line1": "equipme GmbH",
    "street": "W 55th St",
    "number": 240,
    "addition": "3rd floor",
    "city": "New York",
    "postalCode": 10019,
    "countryCode": "US",
    "regionCode": "NY",
    "regionName": "New York",
    "dependentLocality": "Chilmington Green",
    "phoneNumber": "[phone]",
    "id": 83,
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "referredBy": {
    "referredOn": "2026-07-15T17:06:53.197Z",
    "company": {
      "id": 4,
      "name": "foo Inc.",
      "customerNumber": "C00001",
      "self": {
        "href": "text",
        "method": "text"
      }
    },
    "employee": {
      "id": 1,
      "firstName": "Pierce",
      "lastName": "Bell",
      "fullName": "text",
      "email": "[e-mail]",
      "username": "[e-mail]",
      "costCenter": "4645-2343",
      "costCenterId": 1,
      "self": {
        "href": "text",
        "method": "text"
      }
    }
  },
  "id": 4,
  "name": "foo Inc.",
  "customerNumber": "C00001",
  "self": {
    "href": "text",
    "method": "text"
  }
}

Retrieve a single customer by its id

get

You can only access customers of your provider entity.

Authorizations

ApiKey

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

customerIdinteger · int32Required

The identifier of the customer.

Responses

200

OK: The requested customer.

application/json

uuidstring · uuidOptional

The identifier of the customer.

descriptionstring · nullableOptional

The description of the customer.

activebooleanOptional

True if the customer is active, false otherwise.

Example: true

contactNamestring · nullableOptional

The name of the contact person at the customer.

Example: John Doe

contactEmailstring · nullableOptional

The email address of the contact person at the customer.

Example: [e-mail]

contactPhonestring · nullableOptional

The phone number of the contact person at the customer.

Example: [phone]

customAttribute1string · nullableOptional

Value of the first custom attribute as defined in the settings

customAttribute2string · nullableOptional

Value of the second custom attribute as defined in the settings

customAttribute3string · nullableOptional

Value of the third custom attribute as defined in the settings

languagestring · enumOptional

Language options for a customer or user interaction

Possible values:

idinteger · int32Required

The identifier of the customer.

Example: 4

namestring · min: 1Required

The name of the customer.

Example: foo Inc.

customerNumberstring · nullableOptional

Optional identifier of the customer defined by the supplier.

Example: C00001

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

404

NotFound: Requested resource could not be found.

application/json

get/v1/sales/customers/{customerId}

HTTPcURLJavaScriptPython

GET /v1/sales/customers/{customerId} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "uuid": "123e4567-e89b-12d3-a456-426614174000",
  "description": "text",
  "active": true,
  "contactName": "John Doe",
  "contactEmail": "[e-mail]",
  "contactPhone": "[phone]",
  "customAttribute1": "text",
  "customAttribute2": "text",
  "customAttribute3": "text",
  "accountManager": {
    "id": 1,
    "firstName": "Pierce",
    "lastName": "Bell",
    "fullName": "text",
    "email": "[e-mail]",
    "username": "[e-mail]",
    "costCenter": "4645-2343",
    "costCenterId": 1,
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "language": "en",
  "companyAddress": {
    "line1": "equipme GmbH",
    "street": "W 55th St",
    "number": 240,
    "addition": "3rd floor",
    "city": "New York",
    "postalCode": 10019,
    "countryCode": "US",
    "regionCode": "NY",
    "regionName": "New York",
    "dependentLocality": "Chilmington Green",
    "phoneNumber": "[phone]",
    "id": 83,
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "referredBy": {
    "referredOn": "2026-07-15T17:06:53.197Z",
    "company": {
      "id": 4,
      "name": "foo Inc.",
      "customerNumber": "C00001",
      "self": {
        "href": "text",
        "method": "text"
      }
    },
    "employee": {
      "id": 1,
      "firstName": "Pierce",
      "lastName": "Bell",
      "fullName": "text",
      "email": "[e-mail]",
      "username": "[e-mail]",
      "costCenter": "4645-2343",
      "costCenterId": 1,
      "self": {
        "href": "text",
        "method": "text"
      }
    }
  },
  "id": 4,
  "name": "foo Inc.",
  "customerNumber": "C00001",
  "self": {
    "href": "text",
    "method": "text"
  }
}

Deprecated

Update an existing customer (deprecated - please use the PATCH route instead)

put

Overwrites all existing data with that from the request body.

Note: active customers are allowed to place orders.

Authorizations

ApiKey

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

customerIdinteger · int32Required

The identifier of the customer.

Body

application/json

namestring · max: 100Required

The name of the customer.

Example: foo Inc.

customerNumberstring · max: 50 · nullableOptional

Optional identifier of the customer defined by the supplier.

Example: C00001

descriptionstring · max: 500 · nullableOptional

The description of the customer. Note: Value null won't override the current value. You can provide an empty string to clear this field.

activebooleanOptional

True if the customer is active and is allowed to place orders, false otherwise.

Example: true

customAttribute1string · max: 100 · nullableOptional

Value of the first custom attribute as defined in the settings Note: Value null won't override the current value. You can provide an empty string to clear this field.

customAttribute2string · max: 100 · nullableOptional

Value of the second custom attribute as defined in the settings Note: Value null won't override the current value. You can provide an empty string to clear this field.

customAttribute3string · max: 100 · nullableOptional

Value of the third custom attribute as defined in the settings Note: Value null won't override the current value. You can provide an empty string to clear this field.

accountManagerIdinteger · int32 · nullableOptional

Id of the responsible sales person for the customer. On update, this employee receives planner access to the customer.

contactNamestring · max: 200 · nullableOptional

The name of the contact person at the customer.

Example: John Doe

contactEmailstring · max: 100 · nullableOptional

The email address of the contact person at the customer.

Example: [e-mail]

contactPhonestring · max: 50 · nullableOptional

The phone number of the contact person at the customer.

Example: [phone]

Responses

204

NoContent: Request has succeeded.

No content

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

404

NotFound: Requested resource could not be found.

application/json

put/v1/sales/customers/{customerId}

HTTPcURLJavaScriptPython

PUT /v1/sales/customers/{customerId} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 267

{
  "name": "foo Inc.",
  "customerNumber": "C00001",
  "description": "text",
  "active": true,
  "customAttribute1": "text",
  "customAttribute2": "text",
  "customAttribute3": "text",
  "accountManagerId": 1,
  "contactName": "John Doe",
  "contactEmail": "[e-mail]",
  "contactPhone": "[phone]"
}

No content

Partially updates an existing customer

patch

Please provide a valid JSON Patch document with the allowed fields to update. See example below for further details.

Authorizations

ApiKey

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

customerIdinteger · int32Required

The identifier of the customer.

Bodyobject · Operation[]

application/json

valueany · nullableOptional

pathstring · nullableOptional

opstring · nullableOptional

fromstring · nullableOptional

Responses

204

NoContent: Customer successfully updated.

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 or resource does not exist anymore.

application/json

404

NotFound: Requested resource could not be found.

application/json

patch/v1/sales/customers/{customerId}

HTTPcURLJavaScriptPython

PATCH /v1/sales/customers/{customerId} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 663

[
  {
    "op": "add",
    "path": "/active",
    "value": "true"
  },
  {
    "op": "add",
    "path": "/name",
    "value": "foo Inc."
  },
  {
    "op": "add",
    "path": "/customerNumber",
    "value": "C00001"
  },
  {
    "op": "add",
    "path": "/description",
    "value": "stringValue"
  },
  {
    "op": "add",
    "path": "/active",
    "value": "true"
  },
  {
    "op": "add",
    "path": "/customAttribute1",
    "value": "stringValue"
  },
  {
    "op": "add",
    "path": "/customAttribute2",
    "value": "stringValue"
  },
  {
    "op": "add",
    "path": "/customAttribute3",
    "value": "stringValue"
  },
  {
    "op": "add",
    "path": "/accountManagerId",
    "value": 123
  },
  {
    "op": "add",
    "path": "/contactName",
    "value": "John Doe"
  },
  {
    "op": "add",
    "path": "/contactEmail",
    "value": "[e-mail]"
  },
  {
    "op": "add",
    "path": "/contactPhone",
    "value": "[phone]"
  }
]

No content

Get all metadata items for a customer

get

Retrieve all metadata items for a customer.

Note: The metadata is not versioned.

Authorizations

ApiKey

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

customerIdinteger · int32Required

The identifier of the customer.

Responses

200

OK: The requested metadata items.

application/json

valuestring · max: 500 · nullableOptional

Metadata value

Example: EQ1337555

scopestring · nullableOptional

Metadata scope. Can be Customer or Supplier to indicate the metadata is specific to a customer or supplier.

Example: Supplier

keystring · max: 150Required

Metadata key used as a unique identifier for the metadata item.

Example: ExternalSystemId

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

404

NotFound: Requested resource could not be found.

application/json

get/v1/sales/customers/{customerId}/metadata

HTTPcURLJavaScriptPython

GET /v1/sales/customers/{customerId}/metadata HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

[
  {
    "value": "EQ1337555",
    "scope": "Supplier",
    "key": "ExternalSystemId",
    "self": {
      "href": "text",
      "method": "text"
    }
  }
]

Create metadata for a customer

post

If the metadata key already exists, the value will be updated.

Note: The metadata is not versioned.

Authorizations

ApiKey

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

customerIdinteger · int32Required

The identifier of the customer.

Body

application/json

DTO for creating a new metadata entry for a given resource which implements the logic

keystring · max: 150 · nullableOptional

Key for the new metadata entry

valuestring · max: 500 · nullableOptional

Metadata value

Responses

201

Created: The created metadata entry.

application/json

valuestring · max: 500 · nullableOptional

Metadata value

Example: EQ1337555

scopestring · nullableOptional

Metadata scope. Can be Customer or Supplier to indicate the metadata is specific to a customer or supplier.

Example: Supplier

keystring · max: 150Required

Metadata key used as a unique identifier for the metadata item.

Example: ExternalSystemId

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

404

Not Found

application/json

post/v1/sales/customers/{customerId}/metadata

HTTPcURLJavaScriptPython

POST /v1/sales/customers/{customerId}/metadata HTTP/1.1
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 29

{
  "key": "text",
  "value": "text"
}

{
  "value": "EQ1337555",
  "scope": "Supplier",
  "key": "ExternalSystemId",
  "self": {
    "href": "text",
    "method": "text"
  }
}

Get metadata item for a customer

get

Retrieve the metadata item for a customer.

Note: The metadata is not versioned.

Authorizations

ApiKey

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

customerIdinteger · int32Required

The identifier of the customer.

keystringRequired

The metadata key to be retrieved.

Responses

200

OK: The requested metadata item.

application/json

valuestring · max: 500 · nullableOptional

Metadata value

Example: EQ1337555

scopestring · nullableOptional

Metadata scope. Can be Customer or Supplier to indicate the metadata is specific to a customer or supplier.

Example: Supplier

keystring · max: 150Required

Metadata key used as a unique identifier for the metadata item.

Example: ExternalSystemId

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

404

NotFound: Requested resource could not be found.

application/json

get/v1/sales/customers/{customerId}/metadata/{key}

HTTPcURLJavaScriptPython

GET /v1/sales/customers/{customerId}/metadata/{key} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "value": "EQ1337555",
  "scope": "Supplier",
  "key": "ExternalSystemId",
  "self": {
    "href": "text",
    "method": "text"
  }
}

Delete a metadata item for a customer by key

delete

Authorizations

ApiKey

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

customerIdinteger · int32Required

keystringRequired

Responses

204Success

No content

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

404

NotFound: Requested resource could not be found.

application/json

delete/v1/sales/customers/{customerId}/metadata/{key}

HTTPcURLJavaScriptPython

DELETE /v1/sales/customers/{customerId}/metadata/{key} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

No content