Simple API
Manage Customers¶
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.
In this document:
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
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
}
}
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"
}
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"
}
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
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"
}
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"
}
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"
}
Conclusion¶
After this phase, the external system has all the necessary data to order selected products for certain customers.