🛸 Alien Order Gateway

Partner API Documentation

Paste into your AI agent and start building.

Contents

Prerequisites

Before you can use the Alien Order Gateway API, you need to complete the following steps:

1. Create a Customer Account

Register as a customer on our main website:

https://www.alienmilling.com/account/register

2. Request Partner Access

After creating your account, send an email to Saro to request API partner access. Include:

  • Your account email address
  • Your company/practice name
  • Brief description of your integration use case

3. Receive Your API Credentials

Once approved, you will receive:

  • Your API token for authentication
  • Your webhook secret (if you configure webhooks)
Webhook secret: By default we generate the secret and share it with you. If your system requires its own signing secret, you can provide one (minimum 16 characters) to your account manager during onboarding and we will use it instead. Either way, all webhooks we send are HMAC-SHA256 signed with this secret so you can verify they came from us.
Note: Partner approval typically takes 1-2 business days. You'll be notified via email when your account is ready.

Overview

The Alien Order Gateway API allows manufacturing partners to submit orders and receive fulfillment updates.

Base URL https://www.alienswagger.com
Protocol HTTPS Required
Content Type application/json
Rate Limit 100 requests/minute, 1000 requests/hour
HTTPS Required: All API requests must be made over HTTPS. HTTP requests are rejected.

Security

The API enforces strict security controls to protect partner data:

  • All endpoints require Authorization: Bearer <token>
  • Tokens are partner-scoped and validated server-side on every request
  • Partners can only submit orders and receive updates for their own data
  • Order listing or querying is not available — you receive updates via webhooks
  • All communication must use HTTPS

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer aln_your_api_token_here
Important: Your API token is provided when your partner account is created. Keep it secure and never expose it in client-side code.

Create Order

POST /v1/orders

Submit a new manufacturing order.

Request Body

{
  "partner_order_ref": "CUSTOMER-123-BATCH",
  "shipping_address": {
    "name": "Dr. John Smith",
    "company": "Smile Dental Clinic",
    "address1": "123 Main Street",
    "address2": "Suite 100",
    "city": "Los Angeles",
    "province": "CA",
    "postal_code": "90210",
    "country": "US",
    "phone": "+1-555-123-4567"
  },
  "line_items": [
    {
      "case_id": "John Doe #1234",
      "product_id": "zirconia-crown",
      "quantity": 1,
      "shade": "A2",
      "finishing_option_id": "high-polish",
      "tooth_numbers": [14],
      "notes": "Upper right molar",
      "files": [
        { "url": "https://storage.com/case1/upper_scan.stl", "name": "case1_upper.stl" },
        { "url": "https://storage.com/case1/lower_scan.stl", "name": "case1_lower.stl" }
      ]
    },
    {
      "case_id": "Jane Smith #5678",
      "product_id": "zirconia-crown",
      "quantity": 2,
      "shade": "B1",
      "tooth_numbers": [8, 9],
      "notes": "Front teeth veneers",
      "files": [
        { "url": "https://storage.com/case2/scan.stl", "name": "case2_scan.stl" }
      ]
    }
  ]
}

Request Fields

Field Type Required Description
partner_order_ref string Optional Your internal order reference
shipping_address.name string Required Recipient name
shipping_address.company string Optional Company/clinic name
shipping_address.address1 string Required Street address
shipping_address.address2 string Optional Apt, suite, unit, etc.
shipping_address.city string Required City
shipping_address.province string Required State/province code
shipping_address.postal_code string Required ZIP/postal code
shipping_address.country string Required ISO 2-letter country code
line_items[].case_id string Required Your identifier for this case (patient name, ID, etc.) — appears on printed RX
line_items[].product_id string Required Product ID from catalog
line_items[].quantity number Required Number of units (≥ 1)
line_items[].shade string Conditional Required if product has shades
line_items[].finishing_option_id string Optional Finishing option ID
line_items[].design_option_id string Optional Design service option ID (see Design Service)
line_items[].tooth_numbers number[] Optional Specific tooth numbers
line_items[].notes string Optional Special instructions for this case
line_items[].files array Required Files for this case (STL scans, photos, etc.)
line_items[].files[].url string Required Publicly accessible URL (http/https)
line_items[].files[].name string Optional Filename hint

File Attachments

Attach files to each line item (case). Files are organized in separate folders per case:

"line_items": [
  {
    "case_id": "Patient Name #123",
    "product_id": "zirconia-crown",
    "quantity": 1,
    "shade": "A2",
    "files": [
      { "url": "https://storage.com/case1/scan.stl", "name": "upper_arch.stl" }
    ]
  }
]

Files are automatically renamed to include case details: {LineItem}_{CaseID}_{Shade}_{ToothNumbers}_{Filename}.ext

Constraints

Constraint Value
Max files per order 100
Max file size 100 MB per file
Download timeout 5 minutes per file
Allowed types STL, OBJ, PLY, 3MF, PDF, JPG, PNG, TIFF, ZIP
Note: Files are downloaded asynchronously after the order is created. Ensure your URLs remain accessible for at least 30 minutes after submission.

Success Response 201

{
  "status": "success",
  "alien_order_ref": "ALN-20240115-X7K9M2",
  "files_queued": 3
}

The files_queued field indicates how many files are queued for download. Files are processed asynchronously after the order is created.

Error Response 400

{
  "status": "error",
  "errors": [
    "Line item 0: Invalid product_id 'invalid-sku'",
    "Line item 1: Invalid shade 'ZZ' for product 'zirconia-crown'"
  ]
}

Design Service Options

Some products offer optional design services for cases that require professional CAD/CAM design work. If your case requires design, you must select a design option and include the appropriate files.

When to Use Design Service

Select a design option when:

  • You don't have your own CAD design software
  • You need Alien Milling to design the restoration from your scans
  • Your case requires professional design work before manufacturing

Required Files for Design Service

When requesting design service, please include the following files with your case:

File Type Required Description
Upper Arch Scan Required STL/PLY scan of the upper arch
Lower Arch Scan Required STL/PLY scan of the lower arch
Bite Registration Recommended Bite scan or bite registration photos
Scan Body (if applicable) Conditional For implant cases, include scan body scan
Photos Optional Shade reference photos, existing restorations

Example: Order with Design Service

{
  "partner_order_ref": "DESIGN-CASE-001",
  "shipping_address": { ... },
  "line_items": [
    {
      "case_id": "Patient Smith #1234",
      "product_id": "zirconia-crown",
      "quantity": 1,
      "shade": "A2",
      "design_option_id": "full-design",
      "tooth_numbers": [14],
      "notes": "Please match existing crown on #15",
      "files": [
        { "url": "https://storage.com/case/upper_arch.stl", "name": "upper_arch.stl" },
        { "url": "https://storage.com/case/lower_arch.stl", "name": "lower_arch.stl" },
        { "url": "https://storage.com/case/bite.stl", "name": "bite_registration.stl" },
        { "url": "https://storage.com/case/shade_photo.jpg", "name": "shade_reference.jpg" }
      ]
    }
  ]
}
Important: Design service availability and pricing varies by product. Check the product catalog for available design options on each product.

Finishing Options

Products may offer different finishing options that affect the final appearance and surface quality of the restoration. When available, you can specify a finishing option for each line item.

Common Finishing Options

Option Description Best For
Standard Basic finish with no additional polishing Cases where you will do final finishing in-house
High Polish Mirror-like polished surface Anterior restorations, visible areas
Stain & Glaze Custom staining and glazing for natural appearance High-aesthetic anterior cases, matching adjacent teeth
Note: Available finishing options vary by product. Check the product catalog for the specific options available on each product.

Example: Order with Finishing Option

{
  "partner_order_ref": "FINISH-CASE-001",
  "shipping_address": { ... },
  "line_items": [
    {
      "case_id": "Patient Jones #5678",
      "product_id": "zirconia-crown",
      "quantity": 1,
      "shade": "A1",
      "finishing_option_id": "stain-glaze",
      "tooth_numbers": [8],
      "notes": "Central incisor - please match shade to adjacent #9",
      "files": [
        { "url": "https://storage.com/case/upper.stl", "name": "upper_arch.stl" },
        { "url": "https://storage.com/case/lower.stl", "name": "lower_arch.stl" },
        { "url": "https://storage.com/case/shade.jpg", "name": "shade_photo.jpg" }
      ]
    }
  ]
}

Combining Design and Finishing Options

You can specify both a design option and a finishing option for the same line item:

{
  "case_id": "Patient Brown #9999",
  "product_id": "zirconia-crown",
  "quantity": 1,
  "shade": "B1",
  "design_option_id": "full-design",
  "finishing_option_id": "high-polish",
  "tooth_numbers": [14],
  "files": [ ... ]
}

Batching Cases to Save on Shipping

If you have multiple cases ready, batch them into a single order instead of submitting each one separately — every order carries its own shipping charge, so one order with several cases ships for the price of one.

Important: All cases in an order ship together to the single shipping address on that order. We cannot split shipments or ship to multiple addresses for a single order — cases going to different addresses must be separate orders.

Why Batch?

  • Save on shipping - Multiple cases in one order ship together to one address
  • Simpler tracking - One tracking number per customer shipment
  • Better organization - Files are named with case details for easy identification

Recommended: Wait Before Submitting

When a new case is ready in your system, don't immediately call the API. Instead:

  1. Queue the case locally with a 5-10 minute timer
  2. If another case for the same shipping address comes in, restart the timer and add it to the queue
  3. When the timer expires (no new cases for 5-10 mins), submit all queued cases in a single API call
Example: Case A is ready at 2:00pm (timer starts). Case B at 2:05pm (timer restarts). Case C at 2:08pm (timer restarts). No more cases come in, so at 2:13-2:18pm the timer expires and all 3 cases are submitted as one order — paying one shipping charge instead of three.

Example: Multi-Case Order JSON

Here's a complete example of an order with 3 cases from the same customer, each with different products and their own files:

{
  "partner_order_ref": "CUSTOMER-456-BATCH",
  "shipping_address": {
    "name": "Dr. Sarah Johnson",
    "company": "Downtown Dental",
    "address1": "500 Market Street",
    "address2": "Suite 200",
    "city": "San Francisco",
    "province": "CA",
    "postal_code": "94105",
    "country": "US",
    "phone": "+1-415-555-1234"
  },
  "line_items": [
    {
      "case_id": "Alice Johnson #1001",
      "product_id": "zirconia-crown",
      "quantity": 1,
      "shade": "A2",
      "finishing_option_id": "high-polish",
      "tooth_numbers": [14],
      "notes": "Upper right first premolar, patient prefers natural look",
      "files": [
        { "url": "https://storage.example.com/case1/upper_arch.stl", "name": "upper_arch.stl" },
        { "url": "https://storage.example.com/case1/lower_arch.stl", "name": "lower_arch.stl" }
      ]
    },
    {
      "case_id": "Bob Williams #1002",
      "product_id": "pfm-crown",
      "quantity": 2,
      "shade": "B1",
      "tooth_numbers": [8, 9],
      "notes": "Central incisors, match existing laterals",
      "files": [
        { "url": "https://storage.example.com/case2/anterior_scan.stl", "name": "anterior_scan.stl" },
        { "url": "https://storage.example.com/case2/photo.jpg", "name": "shade_reference.jpg" }
      ]
    },
    {
      "case_id": "Carol Davis #1003",
      "product_id": "zirconia-bridge",
      "quantity": 1,
      "shade": "A3",
      "finishing_option_id": "stain-glaze",
      "tooth_numbers": [18, 19, 20],
      "notes": "Lower left bridge, pontic at #19",
      "files": [
        { "url": "https://storage.example.com/case3/full_arch.stl", "name": "full_arch.stl" }
      ]
    }
  ]
}

File Organization

Files are automatically renamed to include case details for easy identification:

orders/Partner-Name/ALN-20240115-X7K9M2/
├── 1_Alice_Johnson_1001_A2_14_upper_arch.stl
├── 1_Alice_Johnson_1001_A2_14_lower_arch.stl
├── 2_Bob_Williams_1002_B1_8-9_anterior_scan.stl
├── 2_Bob_Williams_1002_B1_8-9_shade_reference.jpg
└── 3_Carol_Davis_1003_A3_18-19-20_full_arch.stl

Filename format: {LineItem}_{CaseID}_{Shade}_{ToothNumbers}_{OriginalFilename}.ext

Shipping

A shipping fee is added to each order, based on the rates configured for your account. Because the fee is charged per order, batching multiple cases into one order is the easiest way to reduce shipping costs — see Batching Cases to Save on Shipping.

  • Orders ship via FedEx 2 Day by default
  • Your exact shipping rate (and any free-shipping threshold, if your account has one) is set on your account
  • The shipping charge appears on your invoice alongside the cases in the order
Note: Contact your account manager to confirm the shipping terms configured for your account.

Product Catalog

GET /v1/reference/products

Retrieve the product catalog for reference. Use this to get valid product IDs, shades, finishing options, and current list prices.

Note: Product identifiers are logical manufacturing references only and do not expose internal catalog structure. Products may change without notice. Always handle validation errors gracefully.
Pricing: price values are current list prices fetched live at the time of your request, and may change between calls. A null price means no charge is configured for that option. Partner-specific discounts are not reflected here - they are applied at invoicing.

Response 200

{
  "products": [
    {
      "id": "zirconia-crown",
      "name": "Zirconia Crown",
      "description": "High-strength zirconia crown",
      "category": "crowns",
      "price": 129.00,
      "shades": ["A1", "A2", "A3", "A3.5", "B1", "B2", "C1", "D2"],
      "finishing_options": [
        { "id": "standard", "name": "Standard Finish", "price": null },
        { "id": "high-polish", "name": "High Polish", "price": 15.00 },
        { "id": "stain-glaze", "name": "Stain & Glaze", "price": 25.00 }
      ],
      "design_options": [
        { "id": "full-design", "name": "Full Design Service", "price": 35.00 },
        { "id": "design-review", "name": "Design Review Only", "price": null }
      ],
      "metadata": {
        "material": "Zirconia",
        "translucency": "High",
        "strengthMPa": 1200,
        "yttriumContent": "3Y"
      }
    }
  ]
}

Webhooks

When configured, the gateway will send updates to your webhook endpoints. All webhooks are signed with HMAC-SHA256 for security.

Webhook Headers

Content-Type: application/json
X-Alien-Signature: <HMAC-SHA256 hex digest>
X-Alien-Timestamp: <ISO 8601 timestamp>

Signature Verification

Verify webhooks by computing HMAC-SHA256 of the raw request body using your webhook secret:

const crypto = require('crypto');

function verifyWebhook(rawBody, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature)
  );
}

// Express middleware example
app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const signature = req.headers['x-alien-signature'];
  const isValid = verifyWebhook(req.body, signature, WEBHOOK_SECRET);

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  const payload = JSON.parse(req.body);
  // Process webhook...
  res.status(200).send('OK');
});
WEBHOOK tracking.created

Sent when an order is shipped and tracking information is available.

{
  "event_type": "tracking.created",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "alien_order_ref": "ALN-20240115-X7K9M2",
    "partner_order_ref": "PO-12345",
    "carrier": "FedEx",
    "tracking_number": "794644790198",
    "tracking_url": "https://www.fedex.com/fedextrack/?trknbr=794644790198",
    "shipped_at": "2024-01-15T10:30:00Z"
  }
}
WEBHOOK order.status_changed

Sent when order status changes (if status webhook URL is configured).

{
  "event_type": "order.status_changed",
  "timestamp": "2024-01-15T09:00:00Z",
  "data": {
    "alien_order_ref": "ALN-20240115-X7K9M2",
    "partner_order_ref": "PO-12345",
    "previous_status": "pending",
    "status": "in_production"
  }
}

Order Statuses

pending validated in_production shipped delivered cancelled

Status Flow

Status Description
pending Order received and validated
validated Order accepted and scheduled for production
in_production Order is being manufactured (auto-transitions during business hours: Mon-Fri 8am-2pm PST)
shipped Order has been shipped (tracking info sent via webhook)
delivered Order has been delivered
cancelled Order was cancelled

Error Handling

Status Meaning
400 Bad Request - Validation errors in request body
401 Unauthorized - Invalid or missing API token
403 Forbidden - Partner account is inactive
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Contact support

Error Response Examples

401 Unauthorized

{
  "status": "error",
  "message": "Unauthorized"
}

403 Forbidden

{
  "status": "error",
  "message": "Access denied"
}

429 Too Many Requests

{
  "status": "error",
  "message": "Rate limit exceeded"
}