Guide

SNIPE Setup (API Builder)

This page covers the Snipe-IT-specific implementation pattern for API Builder. Use this as the reference for contract rows, mapping structure, and validation gates when targeting Snipe-IT endpoints.

When to Use Builder vs Snipe Profile

Use Snipe Profile When

  • You want predefined Snipe behavior and fast setup.
  • You do not need custom endpoint, method, or body-format control.
  • You want the profile to provide expected default mapping semantics.

Use API Builder When

  • You need explicit control over API contract paths and HTTP methods.
  • You need to choose request format (JSON/XML) per contract endpoint.
  • You want to manually map destination fields from real destination samples.

Snipe API Builder Contract Example (Successful Pattern)

Recommended Contract Inputs

Contract Endpoint Method Formatter Example Path Notes
Computers - Required fetch API GET JSON /api/v1/hardware/byserial/{serial} Direct serial lookup returns asset row and avoids page traversal.
Computers - Required update API PUT JSON /api/v1/hardware/{id} Update endpoint uses resolved destination asset ID.
Computers - Optional detail lookup API GET JSON /api/v1/hardware/{id} Optional/collapsed detail endpoint for full payload hydration and lookup enrichment.
Mobile Devices - Required fetch API GET JSON /api/v1/hardware/byserial/{serial} Snipe is asset-centric; reuse same fetch path for mobile scope.
Mobile Devices - Required update API PUT JSON /api/v1/hardware/{id} Snipe uses the same asset update path for both scopes.
Mobile Devices - Optional detail lookup API GET JSON /api/v1/hardware/{id} Optional/collapsed detail endpoint for full payload hydration and lookup enrichment.

Important Contract Notes

  • Use {serial} token in fetch path for direct ID resolution.
  • Optional detail endpoints should also point to /api/v1/hardware/{id} for full sample hydration.
  • If update returns 404/405/415/400, verify path, method, and formatter pairing before changing mappings.

Snipe API Builder Mapping Example (Assets)

ABM Source to Destination Mapping Pattern

ABM Field Destination Field (Example) Action Formatter Notes
serialNumber serial Key String Lookup key. Do not treat as a writable business field.
orderNumber order_number Update String Snipe order number is typically a string field.
orderDateTime purchase_date.date or custom DB field Update Date (yyyy-MM-dd) Use date-only formatter when destination expects date-only values.
purchaseSourceType notes or custom DB field Update String Map based on your Snipe schema and business usage.
purchaseSourceId custom DB field (for example _snipeit_...) Update String or Integer Use DB field name for Snipe custom fields.
appleCareId custom DB field (for example _snipeit_...) Update String or Integer Formatter should match target field type.
warrantyDate custom_fields.Warranty Date.value or DB key _snipeit_... Update Date (yyyy-MM-dd) or Date (MM/dd/yyyy) For Snipe custom fields, DB key is authoritative; runtime rewiring can map custom_fields.*.value to DB key.
lifeExpectancy custom DB field (for example _snipeit_...) Update Integer Use Integer when destination rejects decorated values like “6 Years”.

Formatter Guidance

Builder formatters are explicit and important. Choose formatters based on destination expectations, not source display style. A date-time source may need date-only output, and a decorated numeric string may need Integer output.

Successful Snipe API Builder Setup Checklist

End-to-End Validation Gates

Stage What to Confirm Pass Condition If It Fails
API-Key Validation Connection test succeeds with current base URL and API key headers. Wizard advances to contract and mapping. Recheck host, API token, header name (usually Authorization), and prefix (usually Bearer).
Contract Save Contract rows are valid and persist after close and reopen. Method, formatter, and endpoint path rehydrate exactly. Reopen Update API Contract and verify each row, especially /byserial/{serial} and /{id} paths.
Mapping Save Mapped destination fields and formatters persist after Save. Update Mapping reopens with exact saved values. Validate key field mapping and required field mappings are still set.
Single Dry Run One target serial shows expected would-update and skip diagnostics. No endpoint or media-type errors in diagnostics. Check contract method/formatter pairing and mapped destination field names.
Single Live Run One target serial applies expected updates in Snipe destination. Destination reflects mapped values. Check response error details and confirm custom-field destination key is DB field name (_snipeit_...).
Full Run Jobs complete with expected update and skip counts across all records. No unexpected destination-missing spikes or payload format failures. Re-validate fetch endpoint serial visibility and action rules.