Customer data

In this tutorial, you will learn how to create customer-specific data, i.e. a contact and an account. In your plentymarkets system, you will then find this data in the customer data record in the Customers ยป Edit customers menu. You will also learn how to retrieve this data. Open the REST Account page where you find - besides many other calls - all calls that are needed for this tutorial. For example, it is possible to retrieve the data of all contacts at the same time or the data of just one specific contact.

Let's assume you use a marketing software and you would like to import the data contained in this software into your plentymarkets system. After you have retrieved some basic information, you need to create a contact. A contact is equivalent to a person. Then you need to create an account. An account contains company-related data. By the way, you can assign multiple contacts to an account.

Step 1: Retrieving basic information

Before you create a contact and the corresponding account, it might be useful to retrieve some general information: the contact class and the contact type.

As long as you do not create further contact classes and types in your plentymarkets system, these are REST calls you only need to retrieve once.

Retrieving the contact class

It is most likely that the IDs and names of the contact classes that you use in the external tool deviate from the IDs and names of those in plentymarkets. Therefore, retrieve the contact class data with the GET call /rest/accounts/contacts/classes. This will list the names and IDs of all contact classes that are saved in your plentymarkets system.

Retrieving the contact type

Now you retrieve all contact types that are saved in plentymarkets. To do so, use the GET call /rest/accounts/contacts/types. Note that there are six contact types available by default that cannot be deleted. All other contact types that you have created will be subsequently given an ID and added to the end of the list of the default contact types.

Step 2: Creating a new contact

After you have retrieved the data described in Step 1, you can create a new contact. To do so, use the following REST call. A contact is nothing else than a person. Of course, it is possible to assign multiple contacts to an account.

/rest/accounts/contacts

Step 3: Creating a new account

Use the following REST call to create a new account. An account contains company-related data such as the company name and the tax number ID. As already mentioned above, an account can have multiple contacts.

/rest/accounts

Step 4: Updating an address of the contact

Once your customer informs you that his or her address data has changed, e.g. that he or she wants to have the ordered items shipped to another delivery address, use the following REST call to update the address. The ID of the contact and the ID of the address must be specified here.

/rest/accounts/contacts/{contactId}/addresses/{addressId}

Step 5: Listing all contacts

Use the following REST call to list all contacts that are saved in your plentymarkets system.

/rest/accounts/contacts

Code example

{
    "number": "12XA44BC",
    "externalId": "102030",
    "typeId": 4,
    "firstName": "John",
    "lastName": "Doe",
    "gender": "male",
    "formOfAddress": "",
    "newsletterAllowanceAt": "2014-04-09 23:18:24",
    "classId": 1,
    "blocked": 0,
    "rating": 3,
    "bookAccount": "",
    "lang": "de",
    "referrerId": 1,
    "plentyId": 0,
    "userId": 1,
    "birthdayAt": "1984-03-19 00:00:00",
    "lastLoginAt": "2014-04-09 23:18:24",
    "lastOrderAt": "2014-04-09 23:18:24",
    "createdAt": "2014-04-09 23:18:24",
    "updatedAt": "2016-07-22 23:12:15",
    "options": [
        {
            "typeId": 1,
            "subTypeId": 4,
            "value": "030 12312234",
            "priority": 0
        },
        {
            "typeId": 1,
            "subTypeId": 3,
            "value": "030 98898",
            "priority": 0
        },
        {
            "typeId": 2,
            "subTypeId": 4,
            "value": "John@account.com",
            "priority": 0
        }
    ]
}

Step 6: Listing all accounts

Use the following REST call to list all accounts that are saved in your plentymarkets system.

/rest/accounts

Step 7: Listing all contacts of an account

Use the following REST call to list all contacts of an account. The ID of the account must be specified here.

/rest/accounts/{accountId}/contacts

Step 8: Listing contact options of a contact

A contact option is composed of the contact ID, the type ID, the sub-type ID and the actual value. There are some types and sub-types available by default that cannot be deleted. Each type and sub-type is assigned an ID. You can also add new types and sub-types. They will be subsequently given an ID and added to the end of the list of the default types and sub-types.

Let's illustrate this with two examples: type ID 2 is the "email address", sub-type ID 4 is "private". Thus, the actual value is the combination of both types ("email address", "private"), e.g. John@account.com. Another example: type ID 1 is the "telephone number", sub-type ID 1 is "work". Thus, the corresponding value is the business phone number of the contact, e.g. 123-456-7890. Of course, a contact may have various contact options as long as the type ID and the sub-type ID are unique. That means that the same combination of IDs cannot be used twice. Thus, a contact may have one private email address, one business email address, one private phone number, one business phone number and so on.

Use the following REST call to list the contact options of a contact. The ID of the contact must be specified here.

/rest/accounts/contacts/{contactId}/options