Regmarks API

Instruction for integrating with your site

API Documentation

Integration guide for submitting orders, valuations, and wants from your website.

Contents

Authentication

All API requests require an X-Api-Token header. Your token is available in the admin panel under Settings → API Integration.

X-Api-Token: your-api-token-here

Every request must also include:

Content-Type: application/json

Keep your API token secret. Do not expose it in client-side JavaScript. API calls should be made from your server (e.g. from a PHP backend, Node.js server, or similar).

Order Submission API

Use this endpoint to submit completed orders from your website. This is typically called from your "thank you" or order confirmation page after payment has been taken. The order will appear in the Sales admin panel ready for processing.

POST /api/orders

Request Body

Customer Object REQUIRED

Field Type Required Description
name string Yes Customer full name (max 200)
email string Yes Customer email address
phone string No Phone number (max 50)
company string No Company name (max 200)
address_line_1 string Yes First line of address
address_line_2 string No Second line of address
address_line_3 string No Third line of address
town string Yes Town/city (max 100)
county string No County (max 100)
postcode string Yes Postcode (max 15)

Items Array REQUIRED

At least one item is required. Each item can be a registration number, a product, or a physical plate — identified by its code.

Field Type Required Description
code string Yes Registration number (e.g. "A1 ABC") or product/plate code
price number Yes Selling price excluding VAT
vat number Yes VAT amount (include VAT on postage if applicable)
dot_fee number No DoT transfer fee (registrations only, typically £80)
postage number No Postage & packaging charge (ex-VAT)
qty integer No Quantity (default 1)
children array No Linked products/plates for this registration (see below)

Item code resolution: The system checks the code against products first, then physical plates. If neither match, it treats it as a registration number and validates the format.

Children Items

Items such as physical plates or products that are linked to a specific registration should be placed in the children array of that registration's item. Children accept the same fields as items (except dot_fee and children).

Payment Object OPTIONAL

Include if a payment has already been taken. Omit entirely if nothing has been paid yet.

Field Type Required Description
amount number Yes* Amount paid
type string Yes* full, deposit, or finance_deposit
reference string No Your payment/transaction reference

* Required when payment object is provided.

Additional Options

Field Type Default Description
send_confirmation boolean false Send order confirmation email to the customer
notes string — Internal notes (stored in audit log, not shown to customer)

Response

Success (201 Created)

Returns order details including reference, status, and balance.

{
  "order_ref": "K7F2M9X1",
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "order",
  "payment_status": "paid",
  "total_gross": 1234.56,
  "balance_outstanding": 0.00,
  "user_created": true,
  "message": "Order created successfully"
}

Validation Error (422)

Returned when request data fails validation.

{
  "message": "The customer.email field is required.",
  "errors": {
    "customer.email": ["The customer.email field is required."]
  }
}

Authentication Error (401)

{
  "error": "Invalid API token"
}

Order Examples

Example 1: Single Registration with Linked Products

Customer buys registration A1 ABC with T-shirts and security screws.

{
  "customer": {
    "name": "Sarah Johnson",
    "email": "sarah@example.com",
    "phone": "07700100200",
    "address_line_1": "42 Oak Avenue",
    "town": "Birmingham",
    "county": "West Midlands",
    "postcode": "B1 1AA"
  },
  "items": [
    {
      "code": "A1 ABC",
      "price": 2500.00,
      "vat": 500.00,
      "dot_fee": 80.00,
      "children": [
        {
          "code": "TSHIRT-REG",
          "price": 19.99,
          "vat": 4.00,
          "qty": 2
        },
        {
          "code": "SECURITY-SCREWS",
          "price": 12.99,
          "vat": 2.60
        }
      ]
    }
  ],
  "payment": {
    "amount": 3119.58,
    "type": "full",
    "reference": "TXN-20260312-001"
  },
  "send_confirmation": true
}

Example 2: Multiple Registrations with a Standalone Product

Customer buys two registrations (AA51 ABC and ABC 123) plus a standalone Car Cleaning Kit, paying a deposit only.

{
  "customer": {
    "name": "Mark Thompson",
    "email": "mark.t@example.com",
    "phone": "07700300400",
    "company": "Thompson Motors Ltd",
    "address_line_1": "Unit 5, Industrial Estate",
    "address_line_2": "Riverside Road",
    "town": "Leeds",
    "county": "West Yorkshire",
    "postcode": "LS1 4AP"
  },
  "items": [
    {
      "code": "AA51 ABC",
      "price": 1200.00,
      "vat": 240.00,
      "dot_fee": 80.00
    },
    {
      "code": "ABC 123",
      "price": 8500.00,
      "vat": 1700.00,
      "dot_fee": 80.00
    },
    {
      "code": "CLEANING-KIT",
      "price": 29.99,
      "vat": 6.00,
      "postage": 4.99
    }
  ],
  "payment": {
    "amount": 500.00,
    "type": "deposit",
    "reference": "DEP-87654"
  },
  "notes": "Customer will pay balance by BACS within 7 days"
}

Example 3: Registration with Plates and Postage

Customer buys ABC 1A with physical plates that include postage. Remember that VAT applies to the postage as well, so include it in the vat amount.

{
  "customer": {
    "name": "Lisa Chen",
    "email": "lisa.chen@example.com",
    "address_line_1": "15 Park Lane",
    "town": "Bristol",
    "postcode": "BS1 5AH"
  },
  "items": [
    {
      "code": "ABC 1A",
      "price": 3200.00,
      "vat": 640.00,
      "dot_fee": 80.00,
      "children": [
        {
          "code": "STD-PLAIN",
          "price": 24.00,
          "vat": 5.60,       // VAT on £24 (£4.80) + VAT on £3.99 P&P (£0.80)
          "postage": 3.99
        }
      ]
    }
  ],
  "payment": {
    "amount": 3953.59,
    "type": "full",
    "reference": "PP-ABC1A-2026"
  }
}

Example 4: No Payment Yet

Order confirmed but payment will be arranged separately. Simply omit the payment object.

{
  "customer": {
    "name": "David Williams",
    "email": "david@example.com",
    "address_line_1": "8 High Street",
    "town": "Edinburgh",
    "postcode": "EH1 1YZ"
  },
  "items": [
    {
      "code": "AA51 ABC",
      "price": 1200.00,
      "vat": 240.00,
      "dot_fee": 80.00
    }
  ]
}

The response will show "payment_status": "none" and the full amount as balance_outstanding.

Valuation Submission API

Use this endpoint to submit valuation requests from your website. When a customer wants to sell their registration number, submit their details here and the valuation will appear in the admin panel for processing.

POST /api/valuations

Request Body

Field Type Required Description
first_name string Yes Customer first name (max 100)
last_name string Yes Customer last name (max 100)
email string Yes Customer email address (max 200)
vrn string Yes Registration number to value (max 10)
location_of_registration string Yes Where the registration is held. One of:
vehicle_with_tax — On a taxed vehicle
vehicle_without_tax — On an untaxed vehicle
certificate — On a retention certificate
address string No Customer address
landline string No Landline number (max 200)
mobile string No Mobile number (max 200)
notes string No Additional notes

Response

Success (201 Created)

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Valuation created successfully"
}

Invalid Registration (422)

{
  "error": "Invalid registration number format",
  "detail": "Invalid registration. Format AAAA not found"
}

Valuation Examples

Example 1: Registration on a Taxed Vehicle

{
  "first_name": "James",
  "last_name": "Wilson",
  "email": "james.wilson@example.com",
  "mobile": "07700500600",
  "vrn": "A1 ABC",
  "location_of_registration": "vehicle_with_tax",
  "notes": "Inherited from my father, looking for a quick sale"
}

Example 2: Registration on a Retention Certificate

{
  "first_name": "Emma",
  "last_name": "Brown",
  "email": "emma.b@example.com",
  "landline": "01onal234567",
  "mobile": "07700700800",
  "vrn": "ABC 123",
  "location_of_registration": "certificate",
  "address": "29 Queen Street, Cardiff, CF10 2BX"
}

Example 3: Minimal Submission

{
  "first_name": "Tom",
  "last_name": "Price",
  "email": "tom@example.com",
  "vrn": "AA51 ABC",
  "location_of_registration": "vehicle_without_tax"
}

Registration formats accepted: Dateless (e.g. A 1, ABC 123, 123 ABC), Prefix (e.g. A1 ABC), Suffix (e.g. ABC 1A), Current (e.g. AA51 ABC). The system validates the format automatically.

Want Submission API

Use this endpoint to submit "want" requests from your website. When a customer is looking for a specific registration number or pattern, submit their details here and the system will match against available stock.

POST /api/wants

Request Body

Field Type Required Description
match_string string Yes Registration pattern to search for (max 20). Use * as a wildcard. Must contain at least 2 letters or numbers.
format string Yes Registration format. One of:
current — Current style (e.g. AB12 CDE)
prefix — Prefix style (e.g. A123 BCD)
dateless — Dateless (e.g. ABC 123)
suffix — Suffix style (e.g. ABC 1A)
contact_name string Yes Customer name (max 200)
email string Yes Customer email address (max 200)
telephone string No Telephone number (max 200)
mobile string No Mobile number (max 200)
notes string No Additional notes

Match string patterns: Use * as a wildcard for any number of characters, and _ for a single character. For example, WIL* matches anything starting with WIL, *7007* matches anything containing 7007, AB_ matches ABA, ABB, ABC etc, and ABC 123 searches for an exact match. Spaces between individual characters are automatically removed (e.g. W I L becomes WIL).

Registration formatting: If the match string is a valid registration number (without wildcards), the system will format it correctly — for example WIL911 becomes WIL 911. If it is not a valid registration, it is stored as-is for pattern matching.

Validation: The match string must contain at least 2 letters or numbers (excluding wildcards). Submissions containing only asterisks or spaces will be rejected.

Response

Success (201 Created)

{
  "id": 42,
  "match_string": "WIL*",
  "message": "Want created successfully"
}

Invalid Match String (422)

{
  "error": "Invalid match string",
  "detail": "Match string must contain at least 2 letters or numbers (excluding wildcards)."
}

Want Examples

Example 1: Wildcard Search — Starts With

Customer is looking for any current-style registration starting with WIL.

{
  "match_string": "WIL*",
  "format": "current",
  "contact_name": "William Scott",
  "email": "will@example.com",
  "mobile": "07700900100"
}

Example 2: Wildcard Search — Contains

Customer wants any dateless registration containing 7007.

{
  "match_string": "*7007*",
  "format": "dateless",
  "contact_name": "James Bond",
  "email": "james@example.com",
  "telephone": "01onal234567",
  "notes": "Budget up to £5,000"
}

Example 3: Exact Match

Customer wants a specific suffix-style registration.

{
  "match_string": "ABC 123",
  "format": "suffix",
  "contact_name": "Claire Adams",
  "email": "claire@example.com",
  "mobile": "07700200300"
}

Example 4: Minimal Submission

{
  "match_string": "*911*",
  "format": "prefix",
  "contact_name": "Pete Walker",
  "email": "pete@example.com"
}