PII Access API

These endpoints provide controlled access to personally identifiable information (PII) with comprehensive audit logging and rate limiting.

Enterprise Compliance Required. Direct PII access requires Enterprise-level compliance, which includes a detailed questionnaire review, enhanced audit requirements, and additional security attestations. Most integrations should use the Label Proxy instead, which handles PII injection without exposing customer data to your systems.

Prefer Label Proxy. In most cases, use the Label Proxy instead of direct PII access. The label proxy handles PII injection automatically without exposing data to your WMS.

Get PII Data

Retrieves customer address information for a specific order.

GET /api/pii/getPII/{orderId}

Authentication

Header	Required	Description
`x-seller-access-token`	Yes	Valid seller access token
`x-amazon-token-secret`	Yes	Secret used during OAuth

Path Parameters

Parameter	Type	Description
`orderId`	string	Amazon order ID (e.g., `123-4567890-1234567`)

Response

{
  "piiData": {
    "ShippingAddress": {
      "Name": "John Doe",
      "AddressLine1": "123 Main Street",
      "AddressLine2": "Apt 4B",
      "AddressLine3": "",
      "City": "Anytown",
      "StateOrRegion": "CA",
      "PostalCode": "12345",
      "CountryCode": "US",
      "Phone": "+1-555-123-4567"
    }
  },
  "piiSignedUrl": "https://storage.example.com/...",
  "piiFileName": "file-123-4567890-1234567"
}

Field	Description
`piiData`	Customer shipping address from Amazon
`piiSignedUrl`	Pre-signed URL for uploading files (valid 1 hour)
`piiFileName`	File key for storage operations

Example

curl -X GET "https://adb.example.com/api/pii/getPII/123-4567890-1234567" \
  -H "x-seller-access-token: YOUR_SELLER_TOKEN" \
  -H "x-amazon-token-secret: YOUR_TOKEN_SECRET"

Errors

Status	Message	Cause
401	`Invalid seller access token`	Token expired or invalid
403	`PII access blocked for this order`	Order blocked or completed
404	`Order not found`	Order doesn't exist for this seller
429	`PII access throttled`	Already accessed within the last hour

Rate Limiting

1 request per hour per order - Prevents bulk extraction
Throttle resets 1 hour after last successful access
Blocked/completed orders return 403, not 429

Block PII Access

Permanently blocks PII access for an order.

POST /api/pii/blockPII

Authentication

Same as Get PII Data.

Request Body

{
  "orderId": "123-4567890-1234567"
}

Response

{
  "success": true,
  "data": {
    "message": "Order blocked from further PII access"
  }
}

Example

curl -X POST "https://adb.example.com/api/pii/blockPII" \
  -H "Content-Type: application/json" \
  -H "x-seller-access-token: YOUR_SELLER_TOKEN" \
  -H "x-amazon-token-secret: YOUR_TOKEN_SECRET" \
  -d '{"orderId": "123-4567890-1234567"}'

When to Block

When you've finished processing an order
When a customer requests data deletion
When an order is cancelled
When PII is no longer needed for any purpose

Complete Order

Marks an order as complete and blocks further PII access.

POST /api/pii/completeOrder

Authentication

Same as Get PII Data.

Request Body

{
  "orderId": "123-4567890-1234567"
}

Response

{
  "success": true,
  "data": {
    "message": "Order marked complete"
  }
}

Difference from Block PII

Action	Effect	Use Case
`blockPII`	Blocks access, no status change	Cancel, manual block
`completeOrder`	Blocks access + marks shipped	Normal fulfillment

File Operations

Data Border provides secure file storage tied to orders for documents like customs forms or invoices.

Get File

Retrieves a stored file.

GET /api/pii/getFile?orderId={orderId}&fileName={fileName}

curl -X GET "https://adb.example.com/api/pii/getFile?orderId=123-456&fileName=invoice.pdf" \
  -H "x-seller-access-token: YOUR_SELLER_TOKEN" \
  -H "x-amazon-token-secret: YOUR_TOKEN_SECRET" \
  -o invoice.pdf

Write File

Uploads a file associated with an order.

PUT /api/pii/writeFile?orderId={orderId}&fileName={fileName}

Prerequisites

Must have accessed PII for this order within the last hour
Requires piiSignedUrl from Get PII response (alternative method)

curl -X PUT "https://adb.example.com/api/pii/writeFile?orderId=123-456&fileName=customs.pdf" \
  -H "x-seller-access-token: YOUR_SELLER_TOKEN" \
  -H "x-amazon-token-secret: YOUR_TOKEN_SECRET" \
  -H "Content-Type: application/pdf" \
  --data-binary @customs.pdf

Delete File

Removes a stored file.

DELETE /api/pii/deleteFile

Request Body

{
  "orderId": "123-4567890-1234567",
  "fileName": "customs.pdf"
}

Response

HTTP 204 No Content on success.

Example

curl -X DELETE "https://adb.example.com/api/pii/deleteFile" \
  -H "Content-Type: application/json" \
  -H "x-seller-access-token: YOUR_SELLER_TOKEN" \
  -H "x-amazon-token-secret: YOUR_TOKEN_SECRET" \
  -d '{"orderId": "123-456", "fileName": "customs.pdf"}'

Audit Logging

All PII operations are logged with:

Field	Description
`type`	`pii_access`
`action`	`getPII`, `blockPII`, `completeOrder`, `getFile`, `writeFile`, `deleteFile`
`orderId`	Amazon order ID
`sellerId`	Data Border seller ID
`tenantId`	Data Border tenant ID
`success`	Whether the operation succeeded
`ip`	Request source IP
`userAgent`	Request user agent
`timestamp`	ISO 8601 timestamp

Example log entry:

{
  "type": "pii_access",
  "action": "getPII",
  "orderId": "123-4567890-1234567",
  "sellerId": "seller_abc123",
  "tenantId": "tenant_xyz789",
  "success": true,
  "ip": "203.0.113.42",
  "userAgent": "WMS-Client/2.1",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Best Practices

Minimize PII Access

// Bad: Fetch PII for every order
for (const order of orders) {
  const pii = await getPII(order.id) // Avoid this!
  // ...
}

// Good: Use Label Proxy (no PII exposure)
for (const order of orders) {
  await createLabel(order.id, {
    name: '{{ship_to_name}}',
    street: '{{ship_to_address1}}'
  })
}

Always Complete Orders

async function shipOrder(orderId) {
  // Generate label
  const label = await createLabel(orderId)
  
  // Ship the package
  await carrier.ship(label.trackingNumber)
  
  // Mark complete - blocks future PII access
  await adb.post('/api/pii/completeOrder', { orderId })
}

Handle Rate Limits Gracefully

async function getPII(orderId) {
  try {
    return await adb.get(`/api/pii/getPII/${orderId}`)
  } catch (error) {
    if (error.status === 429) {
      // Already accessed recently - use cached data or skip
      return cache.get(`pii:${orderId}`)
    }
    throw error
  }
}

Next Steps

Label Proxy

Generate labels without exposing PII.

Audit & Compliance

Understand the full audit trail.