Customer Service (tenant-managed)

Download OpenAPI specification:Download

Create, manage, and delete customer profiles.

Note: This part of the Customer Service is managed by tenant's employees on behalf of the customers. Actions can be performed in Emporix Management Dashboard directly, or by integrating the Emporix API Customer Service with a third-party application.


Key Features:

  • Rich customer profiles that are extensible with custom fields
  • Multiple addresses for payment and delivery
  • Social login with Twitter, Facebook, and others

Key Benefits:

  • Self-service for customers to manage profile information
  • Convenient login and removal of login barriers with SSO for social logins
  • Capture data that is important for your business to serve your customers better
  • Secure login for your customers to their profile

Account and profile

Retrieving a list of customers

Retrieves a list of customer profiles.

customer.customer_read_own scope allows customers to read profiles from another customers within the same company.


Required scopes

  • customer.customer_read
  • customer.customer_read_own
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
q
string

A standard query parameter used to search for specific values.

Example: q=contactEmail:{email}
sort
string

List of properties used to sort the results, separated by commas. Possible values:

  • {fieldName}
  • {fieldName}.asc
  • {fieldName}.desc

Note: If you want to sort the results by localized properties, the possible values are:

  • {fieldName}.{language}
  • {fieldName}.{language}.asc
  • {fieldName}.{language}.desc

By default, the fields are sorted in ascending order.

pageNumber
integer >= 1
Default: 1

Page number to be retrieved. The number of the first page is 1.

Note: If the pageNumber parameter is passed, size of the pages must be specified in the pageSize parameter.

pageSize
integer >= 1
Default: 60

Number of customers to be retrieved per page.

expand
string

List of additional attributes to be retrieved, separated by commas. Possible values to be passed in this parameter are:

  • addresses
  • accounts *mixin:* Order of the attributes has no influence on the response.
Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

get/{tenant}/customers
Request samples
Response samples
application/json
[
  • {
    }
]

Creating a customer

Creates a new customer.

customer.customer_manage_own scope allow customers to create a new customer. Such customer will be automatically assigned to the customer's company.


Required scopes

  • customer.customer_create
  • customer.customer_manage_own
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
sendPasswordResetNotifications
boolean
Default: true

Flag indicating whether the customer should receive an email with a password reset link once their account is created.

Request Body schema: application/json
title
string
firstName
string
middleName
string
lastName
string
contactPhone
string
company
string
preferredLanguage
string
Default: "en_US"

Customer's preferred language.

preferredCurrency
string = 3 characters
Default: "USD"

Customer's preferred currency, compliant with the ISO 4217 standard.

preferredSite
string
Default: "main"

Customer's preferred site.

type
string

User type. Supported values are: CUSTOMER and CONTACT. If the field is empty then theuser is considered as a customer.

photoUrl
string

Url of a picture.

object

Additional properties for B2B customer.

object (DefaultDtoMetadata)

Links to mixin schemas.

mixins
object

Customer account's additional properties. The property is not returned by default. In order to return the mixins property use expand=mixin:* query param.

contactEmail
string
Responses
201

Created

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

409
post/{tenant}/customers
Request samples
application/json
{
  • "contactEmail": "john.doe@emporix.com",
  • "title": "MR",
  • "firstName": "John",
  • "lastName": "Doe",
  • "contactPhone": "123456789",
  • "company": "Emporix",
  • "preferredLanguage": "en_US",
  • "preferredCurrency": "EUR",
  • "preferredSite": "main",
  • "b2b": {
    }
}
Response samples
application/json

Updating a customer profile

Updates a specified customer's profile.

customer.customer_manage_own scope allows to update customer's profiles from the same company.


Required scopes

  • customer.customer_update or customer.customer_manage
  • customer.customer_manage_own
SecurityOAuth2
Request
path Parameters
customerNumber
required
string

Customer's unique identifier generated when the customer's profile is created.

tenant
required
string

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema:
title
string
firstName
string
middleName
string
lastName
string
contactPhone
string
company
string
preferredLanguage
string
Default: "en_US"

Customer's preferred language.

preferredCurrency
string = 3 characters
Default: "USD"

Customer's preferred currency, compliant with the ISO 4217 standard.

preferredSite
string
Default: "main"

Customer's preferred site.

type
string

User type. Supported values are: CUSTOMER and CONTACT. If the field is empty then theuser is considered as a customer.

photoUrl
string

Url of a picture.

object

Additional properties for B2B customer.

object (DefaultDtoMetadata)

Links to mixin schemas.

mixins
object

Customer account's additional properties. The property is not returned by default. In order to return the mixins property use expand=mixin:* query param.

contactEmail
string
active
boolean
onHold
boolean
Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

Customer with the specified customerNumber doesn't exist.

patch/{tenant}/customers/{customerNumber}
Request samples
{
  • "contactEmail": "example@customer.com",
  • "active": true
}
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Retrieving a customer profile

Retrieves a specified customer's profile.


customer.customer_read_own scope allows customers to read the specified profiles from another customers within the same company.


Required scopes

  • customer.customer_read
  • customer.customer_read_own
SecurityOAuth2
Request
path Parameters
customerNumber
required
string

Customer's unique identifier generated when the customer's profile is created.

tenant
required
string

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
expand
string

List of additional attributes to be retrieved, separated by commas. Possible values to be passed in this parameter are:

  • addresses
  • accounts *mixin:* Order of the attributes has no influence on the response.
Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

Customer with the specified customerNumber doesn't exist.

get/{tenant}/customers/{customerNumber}
Request samples
Response samples
application/json
{
  • "title": "MR",
  • "firstName": "John",
  • "lastName": "Doe",
  • "contactPhone": "123456789",
  • "company": "Emporix",
  • "preferredLanguage": "en_US",
  • "preferredCurrency": "EUR",
  • "preferredSite": "main",
  • "metadata": {
    },
  • "customerNumber": "13869000",
  • "id": "13869000",
  • "contactEmail": "example@customer.com",
  • "active": true,
  • "onHold": false,
  • "b2b": {
    }
}

Deleting a customer profile

Deletes a specified customer's profile and accounts associated with it.


customer.customer_manage_own scope allows customers to delete a customer only if the customer has been assigned to the same company.

Required scopes

  • customer.customer_update or customer.customer_delete
  • customer.customer_manage_own
SecurityOAuth2
Request
path Parameters
customerNumber
required
string

Customer's unique identifier generated when the customer's profile is created.

tenant
required
string

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Responses
202

Accepted

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

Customer with the specified customerNumber doesn't exist.

delete/{tenant}/customers/{customerNumber}
Request samples
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Assigning an account to an existing customer profile

Assigns a customer account to an existing customer profile.


Required scopes

  • customer.customer_update or customer.customer_manage
SecurityOAuth2
Request
path Parameters
customerNumber
required
string

Customer's unique identifier generated when the customer's profile is created.

tenant
required
string

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
sendPasswordResetNotifications
boolean
Default: true

Flag indicating whether the customer should receive an email with a password reset link once their account is created.

Request Body schema: application/json
email
required
string

Customer's email address.

Responses
201

Created

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

Customer with the specified customerNumber doesn't exist.

409
post/{tenant}/customers/{customerNumber}/accounts/internal
Request samples
application/json
{
  • "email": "john.doe@example.com"
}
Response samples
application/json

Addresses

Retrieving a customer's addresses

Retrieves a list of addresses for a specified customer.


Required scopes

  • customer.customer_read
SecurityOAuth2
Request
path Parameters
customerNumber
required
string

Customer's unique identifier generated when the customer's profile is created.

tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

Not Found

get/{tenant}/customers/{customerNumber}/addresses
Request samples
Response samples
application/json
[
  • {
    }
]

Adding a customer address

Adds an address to a specified customer's profile.


Required scopes

  • customer.customer_update or customer.customer_manage.
SecurityOAuth2 or OAuth2
Request
path Parameters
customerNumber
required
string

Customer's unique identifier generated when the customer's profile is created.

tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema: application/json
id
string

Customer address' unique identifier generated when the address is added to the customer's account.

contactName
required
string
companyName
string
street
string
streetNumber
string
streetAppendix
string
extraLine1
string
extraLine2
string
extraLine3
string
extraLine4
string
zipCode
string
city
string
country
string = 2 characters
state
string
contactPhone
string
isDefault
boolean
Default: false

Flag indicating whether the address is the customer's default address.

tags
Array of strings
object

Links to mixin schemas.

mixins
object

Customer address' additional properties.

Responses
201

Created

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

Customer with the specified customerNumber doesn't exist.

post/{tenant}/customers/{customerNumber}/addresses
Request samples
application/json
{
  • "contactName": "John Doe",
  • "companyName": "Emporix",
  • "street": "Platz der Republik",
  • "streetNumber": "1",
  • "streetAppendix": "",
  • "extraLine1": "",
  • "extraLine2": "",
  • "extraLine3": "",
  • "extraLine4": "",
  • "zipCode": "11011",
  • "city": "Berlin",
  • "country": "DE",
  • "state": "Berlin",
  • "contactPhone": "123456789",
  • "tags": [
    ],
  • "isDefault": true
}
Response samples
application/json

Updating a customer address

Updates a specified customer address.


Required scopes

  • customer.customer_update or customer.customer_manage
SecurityOAuth2 or OAuth2
Request
path Parameters
addressId
required
string

Address' unique identifier generated when the address is added to a customer's profile.

customerNumber
required
string

Customer's unique identifier generated when the customer's profile is created.

tenant
required
string

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Request Body schema: application/json
contactName
string
companyName
string
street
string
streetNumber
string
streetAppendix
string
extraLine1
string
extraLine2
string
extraLine3
string
extraLine4
string
zipCode
string
city
string
country
string
state
string
contactPhone
string
tags
Array of strings
object (DefaultDtoMetadata)

Links to mixin schemas.

mixins
object

Customer address' additional properties.

isDefault
boolean

Flag indicating whether the address is the customer's default address.

Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

patch/{tenant}/customers/{customerNumber}/addresses/{addressId}
Request samples
application/json
{
  • "contactName": "John Doe",
  • "companyName": "Emporix",
  • "street": "Platz der Republik",
  • "streetNumber": "1",
  • "streetAppendix": "",
  • "extraLine1": "",
  • "extraLine2": "",
  • "extraLine3": "",
  • "extraLine4": "",
  • "zipCode": "11011",
  • "city": "Berlin",
  • "country": "DE",
  • "state": "Berlin",
  • "contactPhone": "123456789",
  • "tags": [
    ],
  • "isDefault": true
}
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Retrieving a customer address

Retrieves a specified customer address and its details.


Required scopes

  • customer.customer_read
SecurityOAuth2
Request
path Parameters
addressId
required
string

Address' unique identifier generated when the address is added to a customer's profile.

customerNumber
required
string

Customer's unique identifier generated when the customer's profile is created.

tenant
required
string

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Responses
200

OK

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

get/{tenant}/customers/{customerNumber}/addresses/{addressId}
Request samples
Response samples
application/json
{
  • "contactName": "John Doe",
  • "companyName": "Emporix",
  • "street": "Platz der Republik",
  • "streetNumber": "1",
  • "streetAppendix": "",
  • "extraLine1": "",
  • "extraLine2": "",
  • "extraLine3": "",
  • "extraLine4": "",
  • "zipCode": "11011",
  • "city": "Berlin",
  • "country": "DE",
  • "state": "Berlin",
  • "contactPhone": "123456789",
  • "tags": [
    ],
  • "id": "b05c20e034",
  • "isDefault": true
}

Deleting a customer address

Deletes a specified customer address.


Required scopes

  • customer.customer_update or customer.customer_manage.
SecurityOAuth2 or OAuth2
Request
path Parameters
addressId
required
string

Address' unique identifier generated when the address is added to a customer's profile.

customerNumber
required
string

Customer's unique identifier generated when the customer's profile is created.

tenant
required
string

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

Responses
204

No Content

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

delete/{tenant}/customers/{customerNumber}/addresses/{addressId}
Request samples
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Adding tags to a customer address

Adds tags to a specified customer address.


Required scopes

  • customer.customer_update or customer.customer_manage.
SecurityOAuth2
Request
path Parameters
addressId
required
string

Address' unique identifier generated when the address is added to a customer's profile.

customerNumber
required
string

Customer's unique identifier generated when the customer's profile is created.

tenant
required
string

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
tags
required
string

List of address tags, separated by commas.

Example: tags=BILLING,SHIPPING
Responses
204

No Content

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

post/{tenant}/customers/{customerNumber}/addresses/{addressId}/tags
Request samples
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}

Deleting tags from a customer address

Deletes tags from a specified customer address.


Required scopes

  • customer.customer_update or customer.customer_manage.
SecurityOAuth2 or OAuth2
Request
path Parameters
addressId
required
string

Address' unique identifier generated when the address is added to a customer's profile.

customerNumber
required
string

Customer's unique identifier generated when the customer's profile is created.

tenant
required
string

Your Emporix tenant's name.

Note: The tenant should always be written in lowercase.

query Parameters
tags
required
string

List of address tags, separated by commas.

Example: tags=BILLING,SHIPPING
Responses
204

No Content

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Unauthorized

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

404

The requested resource does not exist.

delete/{tenant}/customers/{customerNumber}/addresses/{addressId}/tags
Request samples
Response samples
application/json
{
  • "type": "bad_request",
  • "status": 400,
  • "message": "The tenant information provided with the request is not valid."
}