Skip to main content

Customers API

The Customers API provides endpoints for managing your customer database.

Endpoints Overview​

MethodEndpointDescription
GET/api/v1/CustomersList customers
POST/api/v1/CustomersCreate customer
GET/api/v1/Customers/{customerId}Get customer
PUT/api/v1/Customers/{customerId}Update customer
DELETE/api/v1/Customers/{customerId}Delete customer
PATCH/api/v1/Customers/{customerId}/referencesAdd reference
DELETE/api/v1/Customers/{customerId}/references/{referenceId}Remove reference
POST/api/v1/Customers/{customerId}/contactsAdd contact
PATCH/api/v1/Customers/{customerId}/contacts/{contactId}Update contact
DELETE/api/v1/Customers/{customerId}/contacts/{contactId}Delete contact
GET/api/v1/Customers/{customerId}/recent-shipmentsGet recent shipments
GET/api/v1/Customers/{customerId}/sales-analyticsGet sales analytics
POST/api/v1/Customers/uploadUpload customers
GET/api/v1/Customers/confirm-uploadConfirm upload

List Customers​

Get a paginated list of customers.

GET /api/v1/Customers

Query Parameters​

ParameterTypeDescription
PageintegerPage number (default: 1)
PageSizeintegerItems per page (max: 100)
$orderbystringSort order
$filterstringFilter expression
$searchstringSearch text

Example Request​

GET /api/v1/Customers?Page=1&PageSize=25&$search=john

Response​

{
  "data": [
    {
      "guid": "customer-uuid",
      "name": "John Doe",
      "email": "john@example.com",
      "phone": "+1234567890",
      "company": "Acme Corp",
      "address": {
        "street": "123 Main St",
        "city": "City",
        "state": "State",
        "postalCode": "12345",
        "country": "Country"
      }
    }
  ],
  "page": 1,
  "pageSize": 25,
  "totalCount": 150,
  "success": true
}

Create Customer​

Create a new customer.

POST /api/v1/Customers

Request Body​

{
  "name": "Jane Smith",
  "email": "jane@example.com",
  "phone": "+1234567890",
  "company": "Smith Co",
  "address": {
    "street": "456 Oak Ave",
    "city": "Town",
    "state": "State",
    "postalCode": "67890",
    "country": "Country"
  }
}

Response​

{
  "data": {
    "guid": "new-customer-uuid",
    "name": "Jane Smith",
    "email": "jane@example.com"
  },
  "success": true
}

Get Customer​

Retrieve a specific customer.

GET /api/v1/Customers/{customerId}

Path Parameters​

ParameterTypeDescription
customerIduuidCustomer identifier

Response​

{
  "data": {
    "guid": "customer-uuid",
    "name": "John Doe",
    "email": "john@example.com",
    "phone": "+1234567890",
    "company": "Acme Corp",
    "address": {
      "street": "123 Main St",
      "city": "City",
      "state": "State",
      "postalCode": "12345",
      "country": "Country"
    },
    "contacts": [],
    "references": []
  },
  "success": true
}

Update Customer​

Update an existing customer.

PUT /api/v1/Customers/{customerId}

Request Body​

{
  "name": "John Doe Updated",
  "email": "john.updated@example.com",
  "phone": "+1234567890"
}

Response​

{
  "data": {
    "guid": "customer-uuid",
    "name": "John Doe Updated",
    "email": "john.updated@example.com"
  },
  "success": true
}

Delete Customer​

Remove a customer.

DELETE /api/v1/Customers/{customerId}

Response​

{
  "success": true
}

Add Customer Reference​

Add an external reference to a customer.

PATCH /api/v1/Customers/{customerId}/references

Request Body​

{
  "type": "external_id",
  "value": "EXT-12345"
}

Response​

{
  "data": {
    "guid": "customer-uuid",
    "references": [
      {
        "guid": "reference-uuid",
        "type": "external_id",
        "value": "EXT-12345"
      }
    ]
  },
  "success": true
}

Remove Customer Reference​

Delete a customer reference.

DELETE /api/v1/Customers/{customerId}/references/{referenceId}

Response​

{
  "data": {
    "guid": "customer-uuid"
  },
  "success": true
}

Add Customer Contact​

Add a contact to a customer.

POST /api/v1/Customers/{customerId}/contacts

Request Body​

{
  "name": "Contact Name",
  "email": "contact@example.com",
  "phone": "+1234567890",
  "role": "Shipping Manager"
}

Response​

{
  "data": {
    "guid": "contact-uuid",
    "name": "Contact Name",
    "email": "contact@example.com"
  },
  "success": true
}

Update Customer Contact​

Update an existing contact.

PATCH /api/v1/Customers/{customerId}/contacts/{contactId}

Request Body​

{
  "name": "Updated Contact Name",
  "email": "updated.contact@example.com"
}

Response​

{
  "data": {
    "guid": "contact-uuid",
    "name": "Updated Contact Name"
  },
  "success": true
}

Delete Customer Contact​

Remove a contact from a customer.

DELETE /api/v1/Customers/{customerId}/contacts/{contactId}

Response​

{
  "data": {
    "guid": "contact-uuid"
  },
  "success": true
}

Get Recent Shipments​

Get recent shipments for a customer.

GET /api/v1/Customers/{customerId}/recent-shipments

Response​

{
  "data": [
    {
      "guid": "shipment-uuid",
      "trackingNumber": "TRK123456",
      "status": "delivered",
      "deliveryDate": "2024-01-15T14:30:00Z"
    }
  ],
  "success": true
}

Get Sales Analytics​

Get sales analytics for a customer.

GET /api/v1/Customers/{customerId}/sales-analytics

Response​

{
  "data": {
    "totalOrders": 45,
    "totalShipments": 52,
    "totalValue": 12500.00,
    "averageOrderValue": 277.78,
    "onTimeDeliveryRate": 0.96
  },
  "success": true
}

Upload Customers​

Upload customers via file.

POST /api/v1/Customers/upload

Request​

Send as multipart/form-data with file.

Response​

{
  "data": "upload-guid",
  "success": true
}

Confirm Upload​

Confirm a customer upload.

GET /api/v1/Customers/confirm-upload?guid=upload-guid

Response​

{
  "success": true
}

Error Responses​

404 Not Found​

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Customer not found"
  }
}

409 Conflict​

{
  "success": false,
  "error": {
    "code": "CONFLICT",
    "message": "Customer with this email already exists"
  }
}