Account and profile

Retrieving a list of customers

get

Retrieves a list of customer profiles.

Required scopes

This endpoint requires the following scopes:

: Needed to retrieve customer profiles.
: Needed by customer to retrieve customer profiles from the same company.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Query parameters

qstringOptional

A standard query parameter used to search for specific values.

Example: contactEmail:{email}

sortstringOptional

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.

pageNumberinteger · min: 1Optional

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.

Default: 1

pageSizeinteger · min: 1Optional

Number of customers to be retrieved per page.

Default: 60

expandstringOptional

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

addresses
accounts
`mixin``
The order of the attributes has no influence on the response.

Responses

200

application/json

400

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

application/json

401

Unauthorized

application/json

403

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

application/json

get

/customer/{tenant}/customers

GET /customer/{tenant}/customers HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "title": "MR",
    "firstName": "John",
    "lastName": "Doe",
    "contactPhone": "123456789",
    "company": "Emporix",
    "preferredLanguage": "en_US",
    "preferredCurrency": "EUR",
    "preferredSite": "main",
    "mixins": {},
    "metadata": {
      "mixins": {},
      "version": 6
    },
    "customerNumber": "13869000",
    "id": "13869000",
    "contactEmail": "[email protected]",
    "active": true,
    "onHold": false,
    "businessModel": "B2B",
    "b2b": {
      "companyRegistrationId": "123-456-789",
      "legalEntities": [
        {
          "id": "D165356",
          "name": "Emporix",
          "contactAssignmentId": "D436432"
        }
      ]
    }
  }
]

Creating a customer

post

Creates a new customer.

Required scopes

This endpoint requires the following scopes:

: Needed to manage customer profiles.
: Needed by customer to manage customer profiles from the same company.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstring · min: 3 · max: 16Required

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Pattern: ^[a-z][a-z0-9]+$

Query parameters

sendPasswordResetNotificationsbooleanOptional

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

Default: true

Body

titlestringOptional

firstNamestringOptional

middleNamestringOptional

lastNamestringOptional

contactPhonestringOptional

companystringOptional

preferredLanguagestringOptional

Customer preferred language.

Default: en_US

preferredCurrencystring · min: 3 · max: 3Optional

Customer preferred currency, compliant with the ISO 4217 standard.

Default: USD

preferredSitestringOptional

Customer preferred site.

Default: main

typestringOptional

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

photoUrlstringOptional

Url of a picture.

restrictionstring · nullableOptional

Access control identifier that determines who can view or manage the customer.

Purpose: Restricts customer visibility based on scope permissions. Only users/applications with matching restriction scopes can access customers with a specific restriction value.

Access Control:

Reading: Users can only query and view customers with the restriction value that matches one of their authorized restrictions.

Validation: The value must exist in the tenant's configured list of valid restrictions.

Site Synchronization: If the restriction property is not set with tenant configuration property enableSyncBetweenRestrictionsAndSiteCodes set to true, the restriction field automatically syncs with preferredSite property.

Example: DE

idstring · min: 1 · max: 66Optional

Custom customer identifier. If not provided, it is automatically generated.

Pattern: ^[a-zA-Z0-9_-]$

contactEmailstringOptional

passwordstringOptional

Initial password for customer

Responses

201

Created

application/json

400

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

application/json

401

Unauthorized

application/json

403

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

application/json

409Error

application/json

post

/customer/{tenant}/customers

POST /customer/{tenant}/customers HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 258

{
  "contactEmail": "[email protected]",
  "title": "MR",
  "firstName": "John",
  "lastName": "Doe",
  "contactPhone": "123456789",
  "company": "Emporix",
  "preferredLanguage": "en_US",
  "preferredCurrency": "EUR",
  "preferredSite": "main",
  "b2b": {
    "companyRegistrationId": "123-456-789"
  }
}

{
  "id": "34751075"
}

Searching for customers

post

Searches for customer profiles.

Required scopes

This endpoint requires the following scopes:

: Needed to retrieve customer profiles.
: Needed by customer to retrieve customer profiles from the same company.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

tenantstringRequired

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Query parameters

sortstringOptional

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.

pageNumberinteger · min: 1Optional

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.

Default: 1

pageSizeinteger · min: 1Optional

Number of customers to be retrieved per page.

Default: 60

expandstringOptional

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

addresses
accounts
`mixin``
The order of the attributes has no influence on the response.

Body

qstringOptional

A standard query parameter is used to search for specific values.

See: Standard practises - Query parameter

Responses

200

application/json

400

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

application/json

401

Unauthorized

application/json

403

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

application/json

post

/customer/{tenant}/customers/search

POST /customer/{tenant}/customers/search HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22

{
  "q": "firstName:John"
}

[
  {
    "title": "MR",
    "firstName": "John",
    "lastName": "Doe",
    "contactPhone": "123456789",
    "company": "Emporix",
    "preferredLanguage": "en_US",
    "preferredCurrency": "EUR",
    "preferredSite": "main",
    "mixins": {},
    "metadata": {
      "mixins": {},
      "version": 6
    },
    "customerNumber": "13869000",
    "id": "13869000",
    "contactEmail": "[email protected]",
    "active": true,
    "onHold": false,
    "businessModel": "B2B",
    "b2b": {
      "companyRegistrationId": "123-456-789",
      "legalEntities": [
        {
          "id": "D165356",
          "name": "Emporix",
          "contactAssignmentId": "D436432"
        }
      ]
    }
  }
]

Retrieving a customer profile

get

Retrieves a specified customer profile.

Required scopes

This endpoint requires the following scopes:

: Needed to retrieve customer profiles.
: Needed by customer to retrieve customer profiles from the same company.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

customerNumberstringRequired

Customer unique identifier generated when the customer profile is created.

tenantstringRequired

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Query parameters

expandstringOptional

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

addresses
accounts
`mixin``
The order of the attributes has no influence on the response.

Responses

200

application/json

titlestringOptional

firstNamestringOptional

middleNamestringOptional

lastNamestringOptional

contactPhonestringOptional

companystringOptional

preferredLanguagestringOptional

Customer preferred language.

Default: en_US

preferredCurrencystring · min: 3 · max: 3Optional

Customer preferred currency, compliant with the ISO 4217 standard.

Default: USD

preferredSitestringOptional

Customer preferred site.

Default: main

typestringOptional

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

photoUrlstringOptional

Url of a picture.

restrictionstring · nullableOptional

Access control identifier that determines who can view or manage the customer.

Purpose: Restricts customer visibility based on scope permissions. Only users/applications with matching restriction scopes can access customers with a specific restriction value.

Access Control:

Reading: Users can only query and view customers with the restriction value that matches one of their authorized restrictions.

Validation: The value must exist in the tenant's configured list of valid restrictions.

Example: DE

customerNumberstringOptional

Customer unique number generated when the customer profile is created.

idstringOptional

Customer unique identifier generated when the customer profile is created.

contactEmailstringOptional

activebooleanOptional

Flag indicating whether the customer profile is active.

onHoldbooleanOptional

Flag indicating whether the customer profile is suspended.

emailstringOptional

Customer email address.

businessModelstring · enumOptional

Property indicating business model of customer. When customer is assigned to any company then it is B2B. Otherwise it is B2C.

Possible values:

metadataCreatedAtstringOptional

Customer creation date.

400

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

application/json

401

Unauthorized

application/json

403

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

application/json

404

Customer with the specified customerNumber doesn't exist.

application/json

get

/customer/{tenant}/customers/{customerNumber}

GET /customer/{tenant}/customers/{customerNumber} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "title": "MR",
  "firstName": "John",
  "lastName": "Doe",
  "contactPhone": "123456789",
  "company": "Emporix",
  "preferredLanguage": "en_US",
  "preferredCurrency": "EUR",
  "preferredSite": "main",
  "metadata": {
    "version": 6
  },
  "customerNumber": "13869000",
  "id": "13869000",
  "contactEmail": "[email protected]",
  "active": true,
  "onHold": false,
  "businessModel": "B2B",
  "b2b": {
    "companyRegistrationId": "123-456-789",
    "legalEntities": [
      {
        "id": "D165356",
        "name": "Emporix",
        "contactAssignmentId": "D436432"
      }
    ]
  }
}

Upserting a customer profile

put

Updates a specified customer profile or creates a new one if it doesn't exist yet.

Required scopes

This endpoint requires the following scopes:

: Needed to manage customer profiles.
: Needed by customer to manage customer profiles from the same company.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

customerNumberstringRequired

Customer unique identifier generated when the customer profile is created.

tenantstringRequired

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Query parameters

sendPasswordResetNotificationsbooleanOptional

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

Default: true

Body

titlestringOptional

firstNamestringOptional

middleNamestringOptional

lastNamestringOptional

contactPhonestringOptional

companystringOptional

preferredLanguagestringOptional

Customer preferred language.

Default: en_US

preferredCurrencystring · min: 3 · max: 3Optional

Customer preferred currency, compliant with the ISO 4217 standard.

Default: USD

preferredSitestringOptional

Customer preferred site.

Default: main

typestringOptional

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

photoUrlstringOptional

Url of a picture.

restrictionstring · nullableOptional

Access control identifier that determines who can view or manage the customer.

Purpose: Restricts customer visibility based on scope permissions. Only users/applications with matching restriction scopes can access customers with a specific restriction value.

Access Control:

Reading: Users can only query and view customers with the restriction value that matches one of their authorized restrictions.

Validation: The value must exist in the tenant's configured list of valid restrictions.

Example: DE

contactEmailstringOptional

activebooleanOptional

onHoldbooleanOptional

Responses

201

Created

application/json

204

No Content - update has been successful

400

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

application/json

401

Unauthorized

application/json

403

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

application/json

409Error

application/json

put

/customer/{tenant}/customers/{customerNumber}

PUT /customer/{tenant}/customers/{customerNumber} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "contactEmail": "[email protected]"
}

{
  "id": "34751075"
}

Deleting a customer profile

delete

Deletes a specified customer profile and accounts associated with it.

Required scopes

This endpoint requires the following scopes:

: Needed to manage customer profiles.
: Needed by customer to manage customer profiles from the same company.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

customerNumberstringRequired

Customer unique identifier generated when the customer profile is created.

tenantstringRequired

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Body

objectOptional

Responses

202

Accepted

400

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

application/json

401

Unauthorized

application/json

403

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

application/json

404

Customer with the specified customerNumber doesn't exist.

application/json

delete

/customer/{tenant}/customers/{customerNumber}

DELETE /customer/{tenant}/customers/{customerNumber} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2

{}

No content

Updating a customer profile

patch

Updates a specified customer profile.

Required scopes

This endpoint requires the following scopes:

: Needed to manage customer profiles.
: Needed by customer to manage customer profiles from the same company.

Authorizations

OAuth2clientCredentialsRequired

Token URL:

Path parameters

customerNumberstringRequired

Customer unique identifier generated when the customer profile is created.

tenantstringRequired

Your Emporix tenant name.

Note: The tenant should always be written in lowercase.

Body

titlestringOptional

firstNamestringOptional

middleNamestringOptional

lastNamestringOptional

contactPhonestringOptional

companystringOptional

preferredLanguagestringOptional

Customer preferred language.

Default: en_US

preferredCurrencystring · min: 3 · max: 3Optional

Customer preferred currency, compliant with the ISO 4217 standard.

Default: USD

preferredSitestringOptional

Customer preferred site.

Default: main

typestringOptional

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

photoUrlstringOptional

Url of a picture.

restrictionstring · nullableOptional

Access control identifier that determines who can view or manage the customer.

Purpose: Restricts customer visibility based on scope permissions. Only users/applications with matching restriction scopes can access customers with a specific restriction value.

Access Control:

Reading: Users can only query and view customers with the restriction value that matches one of their authorized restrictions.

Validation: The value must exist in the tenant's configured list of valid restrictions.

Example: DE

contactEmailstringOptional

activebooleanOptional

onHoldbooleanOptional

Responses

200

No content

400

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

application/json

401

Unauthorized

application/json

403

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

application/json

404

Customer with the specified customerNumber doesn't exist.

application/json

patch

/customer/{tenant}/customers/{customerNumber}

PATCH /customer/{tenant}/customers/{customerNumber} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 53

{
  "contactEmail": "[email protected]",
  "active": true
}

No content

PreviousCustomer (Tenant Managed)NextAddresses

Last updated 1 month ago

Was this helpful?

Good evening

hashtagRetrieving a list of customers

hashtagCreating a customer

hashtagSearching for customers

hashtagRetrieving a customer profile

hashtagUpserting a customer profile

hashtagDeleting a customer profile

hashtagUpdating a customer profile

Retrieving a list of customers

Creating a customer

Searching for customers

Retrieving a customer profile

Upserting a customer profile

Deleting a customer profile

Updating a customer profile