Customer
Customers and projects
The Customer object
Example
Get customers
Get all customers
Query Parameters
| inactive | If supplied, inactive customers will be included | ||
| limit | Limit the number of returned objects | Integer | |
| offset | Skip the first N objects | Integer | |
| modified | Include only objects modified since this date/timestamp | Timestamp | 2015-10-05 |
- Method
- GET
- URL
- /customer
- Authentication
- Token
- Response
- List of Customer
Search customers
Search customers. Please note that the search representation contains only a subset of the detail and list representations.
Query Parameters
| q |
Search query. Required.
The default search behavior is an ElasticSearch query, each search term ORed, with some fields boosted.
|
||
| inactive | If supplied, inactive customers will be included | ||
Example
GET /customer/search?q=horse Content-type: application/json
- Method
- GET
- URL
- /customer/search
- Authentication
- Token
- Response
- CustomerSearchEntry object
Get a customer
Create a customer
Create a customer. The customer will be assigned a server-generated ID and UUID.
Example
POST /customer
{
"name": "Wendy Warner"
"customerProjects": [
{
"name": "Floor installation"
},
{
"name": "General maintenance"
}
]
}
Response
The created customer object.
- Method
- POST
- URL
- /customer
- Authentication
- Token
- Request
- Customer object
- Response
- Customer object
Update or create a customer
Update an existing customer or create it (if it doesn't exist and :id is a UUID).
Example
PUT /customer/0847ed17-b060-4599-a38c-be9a8b9cbb34
{
"name": "Wendy Warner"
"customerProjects": [
{
"name": "Floor installation"
},
{
"name": "General maintenance"
}
]
}
Response
The updated customer object.
- Method
- PUT
- URL
- /customer/:id
- Authentication
- Token
- Request
- Customer object
- Response
- Customer object
Delete a customer
Delete a customer.
Example
DELETE /customer/0847ed17-b060-4599-a38c-be9a8b9cbb34
- Method
- DELETE
- URL
- /customer/:id
- Authentication
- Token
- Response
- Status code only
Additional content
Link to an external document on a customer
To attach/link to an external document, accessible by a URL (i.e. a document uploaded to Dropbox or similar storage service), update the documents list of the customer.
Example
PUT /customer/123456 Content-type: application/json
{
"documents": [
{
"contentUrl": "http://www.cbu.edu.zm/downloads/pdf-sample.pdf",
"mimeType": "application/pdf",
"fileName": "pdf-sample.pdf",
"description": "Very important instructions"
}
]
}
The example above adds the URL as a "document" on the customer. The mimeType property ensures the correct icon is displayed (you can also use the thumbUrl property to specify your own).
Upload and attach a document to an customer
This operation is divided into two or (optionally) three requests:
- Upload the document content (i.e. an image or PDF file),
- (Optional) Update the document meta data (i.e. description),
- Attach the document to the customer.
1. Upload the document content
The actual document content (the image, PDF file or whatever) is uploaded using a standard (multipart/form-data) file upload using file as the form parameter name.
POST /document/content Content-type: multipart/form-data
Example using curl
curl -i 'https://app.coredination.net/api/1/document/content' \
-H 'API-Key: {my-api-key}' \
-F file=@myimage.jpg
HTTP/1.1 100 Continue
HTTP/1.1 200 OK
Content-Type: application/json
{
"success": true,
"document": {
"uuid": "8acac590-cc94-45aa-a237-18a9d268f431",
"thumbUrl": "/vault/thumbnail/8acac590-cc94-45aa-a237-18a9d268f431",
"size": 7911,
"mimeType": "image/jpeg",
"lastModified": 1447890986622,
"contentUrl": "/vault/document/8acac590-cc94-45aa-a237-18a9d268f431",
"creationTimeStamp": 1447890986484,
"creatorId": null,
"description": null,
"fileName": "myimage.jpg",
"groupId": 17,
"id": 26174165,
"internal": false
}
}
The response should contain the success flag set to true, indicating that the upload and backend storage was successful. It also contains the Document (meta data entity) itself, which you later need to refer to, so hang on to its UUID from here on.
- Method
- POST
- URL
- /document/content
- Authentication
- Token
- Response
- Upload DTO
2. (Optional) Update the document meta data
If you want to change any of the meta data (i.e. description, filename, the internal flag) of the document, you can update it using a PUT request:
Example
PUT /document/8acac590-cc94-45aa-a237-18a9d268f431 Content-type: application/json
{
"description": "Top secret map to customer site",
"internal": true
}
The response will contain the updated document (meta data).
- Method
- PUT
- URL
- /document/:did
- Authentication
- Token
- Response
- Document object
3. Attach the document to the customer
Attaching the document is a simple PUT request without content.
Example
PUT /customer/cbfc4b6f-ee81-4591-8e88-fd359cb2f967/document/8acac590-cc94-45aa-a237-18a9d268f431
The response has no content and should just return status code 200 (OK).
- Method
- PUT
- URL
- /customer/:id/document/:did
- Authentication
- Token
- Response
- Status code only
Detach a document from a customer
Detaching a document from a customer is a simple DELETE request without content.
Example
DELETE /customer/cbfc4b6f-ee81-4591-8e88-fd359cb2f967/document/8acac590-cc94-45aa-a237-18a9d268f431
The response has no content and should just return status code 200 (OK).
- Method
- DELETE
- URL
- /customer/:id/document/:did
- Authentication
- Token
- Response
- Status code only