Customer Service (tenant-managed)

Download OpenAPI specification:Download

Emporix: documentation@emporix.com URL: https://emporix.com

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 colons. 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_manage
    • 

  • 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.


 
id
string  [ 1 .. 66 ] characters ^[a-zA-Z0-9_-]$
Custom customer identifier. If not provided, it will be automatically generated.


 
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
{
  • "id": "34751075"
}
Upserting a customer profile
Updates a specified customer's profile or creates a new one if it doesn't exist yet.


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




Required scopes


    

  • customer.customer_manage or 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.


 
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: 
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 
201
Created


204
No Content - update has been successful


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
put/{tenant}/customers/{customerNumber}
Request samples 
{
  • "contactEmail": "example@customer.com"
}
Response samples 
application/json
{
  • "id": "34751075"
}
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_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,
  • "businessModel": "B2B",
  • "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_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.


 
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_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
{
  • "id": "13869000"
}
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_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
Custom customer's address identifier. If not provided, it is automatically generated.


 
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.


409
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
{
  • "id": "e6eae2c789"
}
Upserting a customer address
Updates a specified customer's address or creates a new one if it doesn't exist yet.




Required scopes


    

  • 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.


 
Request Body schema: application/json
contactName
string
required if address does not exist and should be created in upsert operation.


 
companyName
string
 
street
string
 
streetNumber
string
 
streetAppendix
string
 
extraLine1
string
 
extraLine2
string
 
extraLine3
string
 
extraLine4
string
 
zipCode
string
 
city
string
 
country
string
2 letter country code compliant with the ISO 3166-1 alpha-2 standard.


 
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 
201
Created


204
No Content - update has been successful


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.


put/{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
{
  • "id": "e6eae2c789"
}
Partially updating a customer address
Updates a specified customer address.




Required scopes


    

  • 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.


 
Request Body schema: application/json
contactName
string
required if address does not exist and should be created in upsert operation.


 
companyName
string
 
street
string
 
streetNumber
string
 
streetAppendix
string
 
extraLine1
string
 
extraLine2
string
 
extraLine3
string
 
extraLine4
string
 
zipCode
string
 
city
string
 
country
string
2 letter country code compliant with the ISO 3166-1 alpha-2 standard.


 
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_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_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_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.


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."
}