Customers

Customers store contact information, type classification, and multiple addresses. Each customer belongs to an organization and can be looked up by email or phone.

The Customer Object

{
  "id": "cust_abc123xyz789",
  "organization_id": "org_123",
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+966501234567",
  "birthdate": "1990-05-15",
  "gender": "male",
  "type": "individual",
  "status": "active",
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-16T14:22:00Z"
}

Fields

Field	Type	Description
`id`	string	Internal Linkit ID
`first_name`	string	Customer's first name
`last_name`	string	Customer's last name
`email`	string	Email address (normalized, case-insensitive)
`phone`	string	Phone number (normalized with country code)
`birthdate`	string	Date of birth (YYYY-MM-DD)
`gender`	string	`male`, `female`, or `other`
`type`	string	Customer type
`status`	string	Account status

Customer Types

Type	Description
`individual`	Regular consumer
`corporate`	Business customer
`vip`	Premium customer

Customer Statuses

Status	Description
`active`	Normal active account
`inactive`	Dormant account
`pending`	Awaiting verification
`suspended`	Temporarily blocked
`blocked`	Permanently blocked

List Customers

GET /api/v1/customers

Query Parameters

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	20	Items per page (max 100)
`status`	string	-	Filter by status
`type`	string	-	Filter by type
`search`	string	-	Search in name, email, phone

Required Headers

Header	Description
`Authorization`	Bearer token
`X-Organization-ID`	Organization ID

Example Request

curl -X GET "https://linkit.works/api/v1/customers?status=active&limit=25" \
  -H "Authorization: Bearer your_token_here" \
  -H "X-Organization-ID: org_123"

const response = await fetch(
  'https://linkit.works/api/v1/customers?status=active&limit=25',
  {
    headers: {
      'Authorization': 'Bearer your_token_here',
      'X-Organization-ID': 'org_123'
    }
  }
);
const customers = await response.json();

import requests

response = requests.get(
    'https://linkit.works/api/v1/customers',
    params={'status': 'active', 'limit': 25},
    headers={
        'Authorization': 'Bearer your_token_here',
        'X-Organization-ID': 'org_123'
    }
)
customers = response.json()

Get Single Customer

GET /api/v1/customers/{id}

Returns the full customer object.

Customer Lookup

Find a customer by email or phone. Useful for checking if a customer already exists before creating.

GET /api/v1/customers/lookup

Parameter	Type	Description
`email`	string	Email address to search
`phone`	string	Phone number to search

Provide either email or phone (or both). Email lookups are case-insensitive, phone lookups normalize to digits only.

Returns the customer object if found, or 404 if no match.

Advanced Search

POST /api/v1/customers/search

Request Body

{
  "query": "john",
  "status": ["active", "pending"],
  "type": ["individual", "vip"],
  "created_from": "2024-01-01",
  "created_to": "2024-12-31",
  "page": 1,
  "limit": 25
}

All fields are optional. The query field searches across name, email, and phone simultaneously.

Create Customer

POST /api/v1/customers

Request Body

{
  "first_name": "Sarah",
  "last_name": "Smith",
  "email": "sarah@example.com",
  "phone": "+966509876543",
  "birthdate": "1992-08-20",
  "gender": "female",
  "type": "individual",
  "status": "active"
}

Required Fields

Field	Type	Constraints
`first_name`	string	Max 100 chars
`last_name`	string	Max 100 chars
`email`	string	Valid email
`phone`	string	10–20 chars
`status`	string	`active`, `inactive`, `pending`, `banned`
`type`	string	`individual`, `corporate`, `vip`

Email and phone are normalized and checked for duplicates within your organization.

Update Customer

PUT /api/v1/customers/{id}

Full replacement — include all fields you want to keep.

Delete Customer

DELETE /api/v1/customers/{id}

Permanent deletion

Deleting a customer removes all their data including addresses. Consider setting status to inactive instead.

Response (204 No Content)

Customer Addresses

Customers can have multiple addresses. One address can be the default.

The Address Object

{
  "id": "addr_abc123",
  "customer_id": "cust_xyz789",
  "label": "Home",
  "address_line1": "123 Main Street",
  "address_line2": "Apt 4B",
  "city": "Riyadh",
  "state": "Riyadh",
  "country": "SA",
  "is_default": true,
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-16T14:22:00Z"
}

List Addresses

GET /api/v1/customers/{customerId}/addresses

Add Address

POST /api/v1/customers/{customerId}/addresses

Required Fields

Field	Type	Constraints
`label`	string	1–50 chars
`address_line1`	string	1–200 chars
`city`	string	1–100 chars
`state`	string	1–100 chars
`country`	string	2-letter ISO code

Setting is_default to true automatically unsets the default flag on all other addresses for this customer.

Update Address

PUT /api/v1/customers/{customerId}/addresses/{addressId}

Delete Address

DELETE /api/v1/customers/{customerId}/addresses/{addressId}

Error Responses

409 Conflict (Duplicate Email)

{
  "code": 409,
  "error": "Customer with this email already exists",
  "details": { "email": "john@example.com" }
}

404 Not Found

{
  "code": 404,
  "error": "Customer not found",
  "details": { "id": "nonexistent" }
}

Customer Groups

Organize customers into segments.

Orders

Orders linked to customer profiles.

Customers

Customer Groups

Orders

On this page