Customer Management API documentation version v1
https://api.samplehost.com/api/{version}
API specification for managing customers
- version: required (v1)
Customer collection
Set of APIs to manage Customer resource.
Retrieve all customers. When query parameters are ommited, the API calls returns all customers. Using the optional query parameters, the result set could be narrowed further to the matching customers.
Create a new instance of customer
get /customers
Retrieve all customers. When query parameters are ommited, the API calls returns all customers. Using the optional query parameters, the result set could be narrowed further to the matching customers.
The APIs are protected by OAuth 2.0. All consumers will need to register their API clients with the API gateway in order to obtain the client_id and client_secret.
Query Parameters
- firstName: (string)
First name of customer
Example:
John - lastName: (string)
Last name of customer
Example:
Smith - address.streetLine1: (string)
Fuzzy search on street line 1
Example:
George Street - address.streetLine2: (string)
Fuzzy search on street line 2
Example:
Mountain%20Street - address.city: (string)
Fuzzy search address
Example:
Sydney, Bellevue%20Hill, Potts%20Point - address.postCode: (string)
Exact search by postcode
Example:
2000, 214 - lastUpdated: (string)
Only fetch customers items that were last updated since this timestamp
Example:
2017-12-03T10:15:30+11:00 - pageNo: (number - default: 0)
The page number to fetch
Example:
5 - pageSize: (number - default: 100)
The maximum number of records to fetch per page
Example:
5 - sortBy: (string)
Comma seperated list of fields to sort by with sort direction (optional). By default the server will sort in ascending order (asc). To override this, the sort order will need to be specified with a colon after the field.
Example:
- firstName,lastName - firstName:desc,lastName - firstName,lastName:desc
HTTP status code 200
A paginated list of customers
Body
Media type: application/json
Type: any
Example:
{
"success": true,
"status": 200,
"data": {
"pageSize": 3,
"pageNo": 0,
"totalPages": 224,
"first": true,
"last": false,
"totalElements": 1118,
"customers": [
{
"customerId": 588992,
"firstName": "Fraser",
"lastName": "Brendand",
"address": {
"addressLine1": "1 Charles Street",
"addressLine2": "",
"city": "Westmead",
"state": "NSW",
"postCode": "2145",
"country": "Australia"
}
},
{
"customerId": 588294,
"firstName": "Raymond",
"lastName": "Johnson",
"address": {
"addressLine1": "4/5 Dover Heights",
"addressLine2": "",
"city": "Tarens Point",
"state": "NSW",
"postCode": "2245",
"country": "Australia"
}
},
{
"customerId": 588214,
"firstName": "Albert",
"lastName": "Steve",
"address": {
"addressLine1": "4/5 Chestnut Place",
"addressLine2": "",
"city": "Burwood",
"state": "NSW",
"postCode": "2245",
"country": "Australia"
}
},
{
"customerId": 182842,
"firstName": "Albert",
"lastName": "Steve",
"address": {
"addressLine1": "1 Delhi Road",
"addressLine2": "",
"city": "North Ryde",
"state": "NSW",
"postCode": "2312",
"country": "Australia"
}
},
{
"customerId": 18284,
"firstName": "Amanda",
"lastName": "Bell",
"address": {
"addressLine1": "9 Mountain Street",
"addressLine2": "",
"city": "Wyong",
"state": "NSW",
"postCode": "2411",
"country": "Australia"
}
}
]
}
}
HTTP status code 403
Permission denied exception
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 403,
"data": {
"error": "You do not have permission to perform this action",
"request": "/api/v1/customers",
"method": "GET"
}
}
HTTP status code 404
Resource not found
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 404,
"data": {
"error": "Resource could not be located",
"request": "/api/v1/customers/899585",
"method": "GET"
}
}
HTTP status code 500
Internal server error
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 500,
"data": {
"error": "An internal server error has occured processing your request",
"request": "/api/v1/customers/44981",
"method": "DELETE"
}
}
Secured by oauth_2_0
Headers
- Authorization: required (string)
Used to send a valid OAuth 2 access token. Do not use with the "access_token" query string parameter.
Example:
Bearer 79c11a62df3d4d92c092314071941e4489c8f8e7
HTTP status code 401
Bad or expired access token.
HTTP status code 403
Unauthorized - If client with access token invokes API operation that they are not allowed.
post /customers
Create a new instance of customer
The APIs are protected by OAuth 2.0. All consumers will need to register their API clients with the API gateway in order to obtain the client_id and client_secret.
Body
Media type: application/json
Type: any
Example:
{
"firstName": "Fraser",
"lastName": "Brendand",
"address": {
"addressLine1": "1 Jessie street",
"addressLine2": "",
"city": "Sydney",
"state": "NSW",
"postCode": "2145",
"country": "Australia"
}
}
HTTP status code 201
Succesfully created a new customer
Headers
- Content-Location: (string)
Location of the newly created customer
Body
Media type: application/json
Type: any
Example:
{
"status": 200,
"success": true,
"data": {
"firstName": "Fraser",
"lastName": "Brendand",
"address": {
"addressLine1": "1 Jessie street",
"addressLine2": "",
"city": "Sydney",
"state": "NSW",
"postCode": "2145",
"country": "Australia"
}
}
}
HTTP status code 400
Invalid API request submitted for creating a new customer
Body
Media type: application/json
Type: any
Example:
{
"success": false,
"status": 400,
"data": {
"error": [
"'firstName' must be between 1 and 30 characters",
"'lastName' must be between 1 and 30 characters"
],
"request": "/api/v1/customers",
"method": "POST"
}
}
HTTP status code 403
Permission denied exception
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 403,
"data": {
"error": "You do not have permission to perform this action",
"request": "/api/v1/customers",
"method": "GET"
}
}
HTTP status code 500
Internal server error
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 500,
"data": {
"error": "An internal server error has occured processing your request",
"request": "/api/v1/customers/44981",
"method": "DELETE"
}
}
Secured by oauth_2_0
Headers
- Authorization: required (string)
Used to send a valid OAuth 2 access token. Do not use with the "access_token" query string parameter.
Example:
Bearer 79c11a62df3d4d92c092314071941e4489c8f8e7
HTTP status code 401
Bad or expired access token.
HTTP status code 403
Unauthorized - If client with access token invokes API operation that they are not allowed.
Operations on individual Customer resource
Retrieve a single customer
Allow partial modification of customer
Update an existing customer
Delete an existing customer
get /customers/{customerId}
Retrieve a single customer
The APIs are protected by OAuth 2.0. All consumers will need to register their API clients with the API gateway in order to obtain the client_id and client_secret.
URI Parameters
- customerId: required (string)
Headers
- If-None-Match: (string)
Set this optional header if you wish to make a conditional request. The ETag value should be derived from the last HTTP 200 response.
HTTP status code 200
Return the customer resource
Body
Media type: application/json
Type: any
Example:
{
"firstName": "Fraser",
"lastName": "Brendand",
"address": {
"addressLine1": "1 Jessie street",
"addressLine2": "",
"city": "Sydney",
"state": "NSW",
"postCode": "2145",
"country": "Australia"
}
}
HTTP status code 304
The resource has not been modified, the body is empty and the version cached by the API consumer may be used.
Headers
- Cache-Control: (string)
Example:
max-age 0
HTTP status code 403
Permission denied exception
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 403,
"data": {
"error": "You do not have permission to perform this action",
"request": "/api/v1/customers",
"method": "GET"
}
}
HTTP status code 404
Resource not found
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 404,
"data": {
"error": "Resource could not be located",
"request": "/api/v1/customers/899585",
"method": "GET"
}
}
HTTP status code 500
Internal server error
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 500,
"data": {
"error": "An internal server error has occured processing your request",
"request": "/api/v1/customers/44981",
"method": "DELETE"
}
}
Secured by oauth_2_0
Headers
- Authorization: required (string)
Used to send a valid OAuth 2 access token. Do not use with the "access_token" query string parameter.
Example:
Bearer 79c11a62df3d4d92c092314071941e4489c8f8e7
HTTP status code 401
Bad or expired access token.
HTTP status code 403
Unauthorized - If client with access token invokes API operation that they are not allowed.
patch /customers/{customerId}
Allow partial modification of customer
The APIs are protected by OAuth 2.0. All consumers will need to register their API clients with the API gateway in order to obtain the client_id and client_secret.
URI Parameters
- customerId: required (string)
Body
Media type: application/json
Type:
{
"address": {
"postCode": "2145"
}
}
HTTP status code 204
Return the updated customer resource
Body
Media type: application/json
Type: any
Example:
{
"firstName": "Fraser",
"lastName": "Brendand",
"address": {
"addressLine1": "1 Jessie street",
"addressLine2": "",
"city": "Sydney",
"state": "NSW",
"postCode": "2145",
"country": "Australia"
}
}
Secured by oauth_2_0
Headers
- Authorization: required (string)
Used to send a valid OAuth 2 access token. Do not use with the "access_token" query string parameter.
Example:
Bearer 79c11a62df3d4d92c092314071941e4489c8f8e7
HTTP status code 401
Bad or expired access token.
HTTP status code 403
Unauthorized - If client with access token invokes API operation that they are not allowed.
put /customers/{customerId}
Update an existing customer
The APIs are protected by OAuth 2.0. All consumers will need to register their API clients with the API gateway in order to obtain the client_id and client_secret.
URI Parameters
- customerId: required (string)
Body
Media type: application/json
Type: any
Example:
{
"firstName": "Fraser",
"lastName": "Brendand",
"address": {
"addressLine1": "1 Jessie street",
"addressLine2": "",
"city": "Sydney",
"state": "NSW",
"postCode": "2145",
"country": "Australia"
}
}
HTTP status code 204
Return the updated customer resource
Body
Media type: application/json
Type: any
Example:
{
"firstName": "Fraser",
"lastName": "Brendand",
"address": {
"addressLine1": "1 Jessie street",
"addressLine2": "",
"city": "Sydney",
"state": "NSW",
"postCode": "2145",
"country": "Australia"
}
}
HTTP status code 403
Permission denied exception
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 403,
"data": {
"error": "You do not have permission to perform this action",
"request": "/api/v1/customers",
"method": "GET"
}
}
HTTP status code 404
Resource not found
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 404,
"data": {
"error": "Resource could not be located",
"request": "/api/v1/customers/899585",
"method": "GET"
}
}
HTTP status code 500
Internal server error
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 500,
"data": {
"error": "An internal server error has occured processing your request",
"request": "/api/v1/customers/44981",
"method": "DELETE"
}
}
Secured by oauth_2_0
Headers
- Authorization: required (string)
Used to send a valid OAuth 2 access token. Do not use with the "access_token" query string parameter.
Example:
Bearer 79c11a62df3d4d92c092314071941e4489c8f8e7
HTTP status code 401
Bad or expired access token.
HTTP status code 403
Unauthorized - If client with access token invokes API operation that they are not allowed.
delete /customers/{customerId}
Delete an existing customer
The APIs are protected by OAuth 2.0. All consumers will need to register their API clients with the API gateway in order to obtain the client_id and client_secret.
URI Parameters
- customerId: required (string)
HTTP status code 204
Resource successfully deleted. No response body.
HTTP status code 403
Permission denied exception
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 403,
"data": {
"error": "You do not have permission to perform this action",
"request": "/api/v1/customers",
"method": "GET"
}
}
HTTP status code 404
Resource not found
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 404,
"data": {
"error": "Resource could not be located",
"request": "/api/v1/customers/899585",
"method": "GET"
}
}
HTTP status code 500
Internal server error
Body
Media type: application/json
Type: object
Example:
{
"success": false,
"status": 500,
"data": {
"error": "An internal server error has occured processing your request",
"request": "/api/v1/customers/44981",
"method": "DELETE"
}
}
Secured by oauth_2_0
Headers
- Authorization: required (string)
Used to send a valid OAuth 2 access token. Do not use with the "access_token" query string parameter.
Example:
Bearer 79c11a62df3d4d92c092314071941e4489c8f8e7
HTTP status code 401
Bad or expired access token.
HTTP status code 403
Unauthorized - If client with access token invokes API operation that they are not allowed.