Send a box from Clay.

1. Get your API key

Your workspace has a private API key (starts with bxli_). Find it in boxli → Settings → Integrations, or ask us on your shared Slack channel. Treat it like a password — it authorizes sends against your inventory.

2. Add an HTTP API column in Clay

In your Clay table, Add enrichment → HTTP API, then configure:

• Method: POST
• Endpoint: https://app.sendaboxli.com/api/integrations/clay/send
• Headers: add an API Request Headers account with Authorization set to Bearer YOUR_API_KEY. (You can also use the header x-boxli-key with the raw key.)
• Body: JSON, mapping your columns into the fields below.

3. Map the body

Use Clay column variables (e.g. {{First Name}}) for the values:

{
  "first_name": "{{First Name}}",
  "last_name": "{{Last Name}}",
  "email": "{{Email}}",
  "title": "{{Title}}",
  "company": "{{Company}}",
  "address_line_1": "{{Street}}",
  "city": "{{City}}",
  "state": "{{State}}",
  "zip": "{{Zip}}",
  "box_type_name": "ABM top target",
  "landing_page_url": "https://yoursite.com/welcome/{{Email}}",
  "booking_url": "https://cal.com/you/30min?email={{Email}}",
  "message": "Hi {{First Name}} — loved your post on pipeline efficiency.",
  "external_id": "{{Clay Row ID}}"
}

Mapping Clay's enriched address

Clay's Company Location → Address and Contact Location → Office Address enrichments return parsed location fields. Map them straight across:

• address_line → address_line_1
• locality → city
• admin_district → state
• postal_code → zip
• country_iso → country

For a company, this is the HQ / office (the is_primary location). For a person, Clay returns a city/region — ship to their office by mapping that to the company's address in their city. Clay can't supply home addresses; for those, use a boxli address-capture link instead.

Fields

• first_name, last_name — required (or pass a single name and we'll split it).
• address_line_1, city, state, zip — required. We can't ship without a deliverable address. address_line_2 and country (defaults to US) are optional.
• landing_page_url — required. The destination for the box's QR / NFC tap. Use a unique URL per row so every scan is tracked back to that recipient.
• booking_url — optional. Adds a second tracked QR (e.g. a calendar link).
• nfc_url — optional. Separate NFC-tap destination; falls back to landing_page_url.
• box_type_name or box_type_id — which design to ship. Optional if you only run one active design; required if you run several.
• message — optional handwritten-note text.
• email, title, company — optional. We upsert the contact by email and enrich any blank fields.
• video_id — optional. A video from your boxli library to play on the brochure (≤ 20 min).
• campaign_id — optional. Groups the send under a campaign.
• external_id — strongly recommended. Pass Clay's row ID; re-running the column won't double-ship, and later engagement signals match back to the row.

4. Response

{
  "send_id": "8f2c...",
  "contact_id": "1a9b...",
  "status": "pending",
  "box_design": "ABM top target",
  "idempotent": false
}

A new send returns 201. If the same external_id was already sent, you get 200 with "idempotent": true and the original send id — safe to re-run on the whole table.

What happens on a send

We upsert the contact, pull one box from that design's inventory, generate the tracked QR / NFC codes, queue the box for pick-pack-ship, and email the recipient the gift announcement. Delivery, opens, scans, and watch time then stream back into your CRM in real time.

Errors

• 401 — missing or invalid API key.
• 400 — a required field is missing, or the address is undeliverable.
• 409 — that design is out of stock. Re-order inventory and re-run.