In the platform, a customer is an account (person or organization) that purchases and consumes services provided by its sales vendor. Before requesting a product, the external system that works on behalf of a sales vendor must identify a customer in the platform or create one.

The platform exposes operations with its customers on the /customers endpoints.

List Customers

To get a list of all customers, the system must send the following request:

GET /customers HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16
JSON

If successful, the response looks like this:

HTTP/1.1 200 OK

{
  "data": [
    {
      "id": "1000001",
      "externalId": "externalId1",
      "name": "RBCustomer",
      "status": "active"
    },
    {
      "id": "1000002",
      "externalId": "externalId2",
      "name": "RBCustomer2",
      "status": "active"            },
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 10,
    "total": 2
  }
}
JSON

Create Customers

To create a customer, the system must send a POST request with the JSON representation of the customer as in this example:

POST /customers HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16

{
             "id": "string",
             "externalId": "EXTERNAL-A1S2D3",
             "attributes": {
                          "property1": "string",
                          "property2": "string"
             },
   "name": "John Smith",
        "externalId": "jsmith101",
   "taxRegId": "1357",
   "address": {
      "streetAddress": "101, Any Street",
      "addressExtension": "extension",
      "postalCode": "12345",
      "city": "Herndon",
      "state": "VA",
      "countryCode": "US"
   },
   "contactPersons": [
      {
         "type": "admin",
         "firstName": "John",
         "lastName": "Smith",
         "email": "js@aps.test",
         "phoneNumber": "88##18881234567#"
      },
      {
         "type": "technical",
         "firstName": "John",
         "lastName": "Smith",
         "email": "js@aps.test",
         "phoneNumber": "88##18881234567#"
      },
      {
         "type": "billing",
         "firstName": "John",
         "lastName": "Smith",
         "email": "cbdemoisv@aps.test",
         "phoneNumber": "88##18881234567#"
      }
   ],
   "language": "en"
}
JSON

Note: The countryCode property must be the two uppercase character country code (Alpha-2 code) as specified by ISO.3166-1 .

If successful, the response must look as follows:

HTTP/1.1 200 OK

{
  "id": "1000240",
  "externalId": "jsmith101",
            "attributes": {
              "property1": "string",
              "property2": "string"
            },
  "name": "John Smith",
  "status": "pending",
  "address": {
    "streetAddress": "101, Any Street",
    "addressExtension": "extension",
    "postalCode": "12345",
    "city": "Herndon",
    "state": "VA",
    "countryCode": "US"
  },
  "contactPersons": [
    {
      "type": "admin",
      "firstName": "John",
      "lastName": "Smith",
      "email": "js@aps.test",
      "phoneNumber": "88##18881234567#"
    },
    {
      "type": "technical",
      "firstName": "John",
      "lastName": "Smith",
      "email": "js@aps.test",
      "phoneNumber": "88##18881234567#"
    },
    {
      "type": "billing",
      "firstName": "John",
      "lastName": "Smith",
      "email": "cbdemoisv@aps.test",
      "phoneNumber": "88##18881234567#"
    }
  ],
  "language": "en"
}
JSON

Note

You can specify the login and password of the customer’s admin user when creating a customer. The customer will be able to use these credentials to access the user control panel. To do this, add the login and password properties to the contactPerson structure of type admin. For security reasons, these properties are not returned in a POST or GET response. For more details, refer to the createCustomer specification.

Get Customer Details

To get the full representation of a customer, the system must specify the customer ID as in this example:

GET /customers/1000240 HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16
JSON

The response must look as follows:

HTTP/1.1 200 OK

{
  "id": "1000240",
  "externalId": "jsmith101",
            "attributes": {
                   "property1": "string",
                   "property2": "string"
            },
  "name": "John Smith",
  "taxRegId": "1357",
  "status": "active",
  "address": {
    "streetAddress": "101, Any Street",
    "addressExtension": "extension",
    "postalCode": "12345",
    "city": "Herndon",
    "state": "VA",
    "countryCode": "US"
  },
  "contactPersons": [
    {
      "type": "admin",
      "firstName": "John",
      "lastName": "Smith",
      "email": "js@aps.test",
      "phoneNumber": "88##18881234567#"
    },
    {
      "type": "technical",
      "firstName": "John",
      "lastName": "Smith",
      "email": "js@aps.test",
      "phoneNumber": "88##18881234567#"
    },
    {
      "type": "billing",
      "firstName": "John",
      "lastName": "Smith",
      "email": "cbdemoisv@aps.test",
      "phoneNumber": "88##18881234567#"
    }
  ],
  "language": "en"
}
JSON

Update Customers

To create a customer, the system must send a PATCH request with the JSON representation of the customer details and specify the customer ID as in this example:

PATCH /customers/100234 HTTP/1.1
Content-Type: application/json
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16

          {
            "externalId": "EXTERNAL-A1S2D3",
            "name": "Acme Inc.",
            "taxRegId": "00-0000000",
            "address": {
                  "streetAddress": "555 Main Street",
                  "addressExtension": "Suite 100",
                  "postalCode": "92612",
                  "city": "Irvine",
                  "state": "CA",
                  "countryCode": "US"
            },
            "contactPersons": [
                  {
                    "type": "admin",
                    "firstName": "Jane",
                    "lastName": "Doe",
                    "email": "jane.doe@email.com",
                    "phoneNumber": "81##18881234567#",
                    "login": "someadmin@example.com",
                    "password": "Ecx$cvdazv"
                  }
            ],
            "id": "string"
          }
JSON

The response must look as follows:

HTTP/1.1 200 OK

          {
            "id": "string",
            "externalId": "EXTERNAL-A1S2D3",
            "attributes": {
                  "property1": "string",
                  "property2": "string"
            },
            "status": "active",
            "name": "Acme Inc.",
            "address": {
                  "streetAddress": "555 Main Street",
                  "addressExtension": "Suite 100",
                  "postalCode": "92612",
                  "city": "Irvine",
                  "state": "CA",
                  "countryCode": "US"
            },
            "contactPersons": [
                  {
                    "type": "admin",
                    "firstName": "Jane",
                    "lastName": "Doe",
                    "email": "jane.doe@email.com",
                    "phoneNumber": "81##18881234567#"
                  }
            ],
            "language": "string",
            "taxRegId": "00-0000000",
            "resellerId": "string"
          }
JSON

Conclusion

After this phase, the external system has all the necessary data to order selected products for certain customers.