Customer Service (Tenant Managed) Tutorial

Manage your customers conveniently using the Emporix API.

How to manage a customer's profile

The steps described in this tutorial demonstrate how you, as an employee, can manage the accounts of your customers on their behalf.

1

Get an employee access token

Firstly, obtain a relevant access token to be able to perform operations as an employee on behalf of a customer. Call the OAuth Service Requesting a service access token endpoint to get credetials of a technical client with the customer.customer_manage and customer.customer_manage_own scopes assigned. The customer.customer_manage_own is required only when you ant to let a customer manage customer profiles from the same company.

API Reference

curl -L 
  --request POST 
  --url 'https://api.emporix.io/oauth/token' 
  --header 'Content-Type: application/x-www-form-urlencoded' 
  --data 'grant_type=client_credentials&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&scope=customer.customer_manage customer.customer_manage_own'

The returned access_token is required in the steps that follow.

2

Create a customer account

Crete a new customer by calling the Creating a customer endpoint.

API Reference

curl -X POST "https://api.emporix.io/customer/{tenant}/customers?sendPasswordResetNotifications=true" 
  -H "Authorization: Bearer YOUR_OAUTH2_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "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"
    }
  }'

The successful response returns the 201 Created status and the customer's assigned ID, for example:

{
  "id": "47718865"
}

3

Update the customer account

If you need to update any information in the customer's profile, send the request to the Upserting a customer profile endpoint. The endpoint performs the upsert operation replacing the primary data or creating a new customer's account if it doesn't exist.

For example, update the customer's email:

curl -X PUT "https://api.emporix.io/customer/mytenant/customers/{customerNumber}" 
  -H "Authorization: Bearer YOUR_OAUTH2_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "contactEmail": "[email protected]",
    "firstName": "John",
    "lastName": "Doe",
    "preferredLanguage": "de_DE"
  }'

4

Add addresses to the profile

To add an address to the customer's profile, call the Adding a customer address endpoint:

curl -X POST "https://api.emporix.io/customer/{tenant}/customers/{customerNumber}/addresses" 
  -H "Authorization: Bearer YOUR_OAUTH2_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "contactName": "John Doe",
    "companyName": "Emporix",
    "street": "Platz der Republik",
    "streetNumber": "1",
    "zipCode": "11011",
    "city": "Berlin",
    "country": "DE",
    "state": "Berlin",
    "contactPhone": "123456789",
    "tags": ["BILLING", "SHIPPING"],
    "isDefault": true
  }'

The response (201 Created) returns the id of the created address, for example:

{
  "id": "e6eae2c789"
}

5

Add tags to customer addresses

To add any tags to the address for easier address management, send the request to the Adding tags to a customer address endpoint.

curl -X POST "https://api.emporix.io/customer/{tenant}/customers/{customerNumber}/addresses/{addressId}/tags?tags=PRIMARY_CONTACT" \
  -H "Authorization: Bearer YOUR_OAUTH2_TOKEN"

To remove tags later, call the same path with DELETE operation.

6

Activate the customer

As the customer's account preparation is complete, activate their account. To do so, update the customer status using the PATCH endpoint for Updating a customer profile.

curl -X PATCH "https://api.emporix.io/customer/{tenant}/customers/{customerNumber}" 
  -H "Authorization: Bearer YOUR_OAUTH2_TOKEN" 
  -H "Content-Type: application/json" 
  -d '{
    "active": true,
    "onHold": false
  }'

7

Retrieve the customer's profile

Verify the customer's details assigned to their profile by calling the Retrieving a customer profile endpoint.

curl -X GET "https://api.emporix.io/customer/{tenant}/customers/{customerNimber}?expand=addresses,accounts" 
  -H "Authorization: Bearer YOUR_OAUTH2_TOKEN"

Example successful response includes all the assigned details:

{
  "title": "MR",
  "firstName": "John",
  "lastName": "Doe",
  "contactPhone": "123456789",
  "company": "Emporix",
  "preferredLanguage": "de_DE",
  "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"
      }
    ]
  },
  "addresses": [
    {
      "id": "e6eae2c789",
      "contactName": "John Doe",
      "street": "Platz der Republik",
      "streetNumber": "1",
      "zipCode": "11011",
      "city": "Berlin",
      "country": "DE",
      "state": "Berlin",
      "contactPhone": "123456789",
      "tags": ["BILLING", "SHIPPING", "PRIMARY_CONTACT"],
      "isDefault": true
    }
  ]
}