schemas.fastbound.org

When to use this

Push a transfer when the sending FFL's system is the system of record and the receiving dealer should see the firearms before they arrive.

Idempotency

Retries carrying the same idempotency_key are recognised as the same request. Keys are compared case-insensitively, so 6e2b3ad0 and 6E2B3AD0 are one key, not two.

Routing to the right account

transferee_emails is how a transfer finds its destination account. At least one address must be the email of a FastBound user with access to the receiving account.

If you want to route transfers to a shared address such as orders@example.com or returns@example.com instead of individual FastBound users, contact support@fastbound.com to set that up.

Matching is case-insensitive and duplicates are ignored. If no address matches, the transfer cannot be routed.

Declaring conformance

Every payload must carry $schema set to the canonical URL of the version it was written against:

"$schema": "https://schemas.fastbound.org/transfers-push-v1.json"

This is how a request states which contract it is honoring. It pins the payload to a known version, so one written for a different version is rejected outright instead of being partially accepted and silently misread. A future version is published at its own URL and carries its own value.

Properties

$schemastringrequired
Declares that this payload conforms to this schema. Must be exactly https://schemas.fastbound.org/transfers-push-v1.json, the canonical URL of the version the payload is written against. Stating conformance pins the request to a known version, so a payload built for a different version is rejected outright rather than partially accepted. A future version is published at its own URL and is a different value.
- consthttps://schemas.fastbound.org/transfers-push-v1.json
idempotency_keystringrequired
A unique key we use to recognize subsequent retries of the same request. We recommend UUIDs, hashes, or another high-entropy random string to prevent collisions. Keys may be up to 255 characters and are compared case-insensitively, so 6e2b3ad039f958c8 and 6E2B3AD039F958C8 are the same key.
- minLength1
- maxLength255
transferorstringrequired
Transferor's full Federal Firearms License (FFL) number, with or without dashes. FastBound auto-completes transferor information from FFLs.com; the FFL must be current and valid there or the request is rejected, and some FFL types are not supported. Check a number at https://www.ffls.com/ffl/{fflNumber}.
- pattern^[1345689]-?\d{2}-?\d{3}-?(?:01|02|03|06|07|08|09|10|11)-?\d[A-HJ-M]-?\d{5}$
transfereestringrequired
Transferee's full Federal Firearms License (FFL) number, with or without dashes. Must correspond to an existing FastBound account, matched together with transferee_emails.
- pattern^[1345689]-?\d{2}-?\d{3}-?(?:01|02|03|06|07|08|09|10|11)-?\d[A-HJ-M]-?\d{5}$
transferee_emailsarrayrequired
One or more email addresses used to route the transfer to the transferee's FastBound account. At least one must be the email of a FastBound user with access to that account. If you want to route transfers to a shared address such as orders@example.com or returns@example.com instead of individual FastBound users, contact support@fastbound.com to set that up. If no address matches, the transfer cannot be routed. Addresses are compared case-insensitively and duplicates are ignored.
- minItems1
- uniqueItemstrue
tracking_numberstring | null
Tracking number. Any value is accepted, but only UPS, FedEx, and USPS formats render as a tracking link in the FastBound UI.
- maxLength100
po_numberstring | null
Purchase Order number.
- maxLength100
invoice_numberstring | null
Invoice number.
- maxLength100
acquire_typestring | null
Acquisition Type (e.g., Purchase).
- maxLength100
notestring | null
A note relating to all of the firearms in this transfer.
- maxLength1000
itemsarrayrequired
- minItems1
- manufacturerstringrequired
  The manufacturer marked on the firearm.
  - minLength1
  - maxLength100
- importerstring | null
  The importer marked on the firearm.
  - maxLength100
- countrystring | null
  The country of manufacture. Required only when the transferee's account settings require country of manufacture; optional otherwise.
  - maxLength100
- modelstringrequired
  The model marked on the firearm.
  - minLength1
  - maxLength100
- caliberstringrequired
  The caliber or gauge marked on the firearm.
  - minLength1
  - maxLength100
- typestringrequired
  Type of the item (e.g., Pistol). Use an approved item type where possible; see https://fastb.co/unapproved-item-type for details.
  - minLength1
  - maxLength100
- serialstringrequired
  The serial number marked on the firearm.
  - minLength1
  - maxLength100
- skustring | null
  Stock Keeping Unit.
  - maxLength50
- mpnstring | null
  Manufacturer's Part Number.
  - maxLength50
- upcstring | null
  Universal Product Code (UPC). Null, or a string of 11 to 18 digits.
  - pattern^\d{11,18}$
- barrelLengthnumber | null
  The length of the barrel in inches (i.e., 4.48). A value of 0.0 is discarded and stored as null.
  - minimum0
- overallLengthnumber | null
  The overall length in inches (i.e., 8.03). A value of 0.0 is discarded and stored as null.
  - minimum0
- costnumber | string | null
  Cost of the item. Accepts a number or a currency string such as $1,299.00. A value of 0.0 is discarded and stored as null.
  - minimum0
- pricenumber | string | null
  Selling price of the item. Accepts a number or a currency string such as $1,299.00. A value of 0.0 is discarded and stored as null.
  - minimum0
- conditionstring | null
  Condition of the item (e.g., New or Used).
  - maxLength50
- notestring | null
  A note concerning just this firearm.
  - maxLength1000

Examples

Minimal transfer

{
  "$schema": "https://schemas.fastbound.org/transfers-push-v1.json",
  "idempotency_key": "example-transfer-0001",
  "transferor": "1-12-345-01-2A-34567",
  "transferee": "3-98-765-09-9B-11111",
  "transferee_emails": [
    "orders@example.com"
  ],
  "items": [
    {
      "manufacturer": "Example Arms Co",
      "model": "EX-9",
      "caliber": "9mm Luger",
      "type": "Pistol",
      "serial": "EXAMPLE0001"
    }
  ]
}

Schema source

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://schemas.fastbound.org/transfers-push-v1.json",
  "title": "Transfer Push Schema",
  "description": "This schema defines the structure for submitting a firearm transfer to FastBound, including the transferor and transferee Federal Firearms License (FFL) numbers, an idempotency key, and the firearms being transferred.",
  "documentation": "https://fastbound.help/en/articles/10732676-transfers-push-api",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "Declares that this payload conforms to this schema. Must be exactly https://schemas.fastbound.org/transfers-push-v1.json, the canonical URL of the version the payload is written against. Stating conformance pins the request to a known version, so a payload built for a different version is rejected outright rather than partially accepted. A future version is published at its own URL and is a different value.",
      "const": "https://schemas.fastbound.org/transfers-push-v1.json"
    },
    "idempotency_key": {
      "type": "string",
      "description": "A unique key we use to recognize subsequent retries of the same request. We recommend UUIDs, hashes, or another high-entropy random string to prevent collisions. Keys may be up to 255 characters and are compared case-insensitively, so 6e2b3ad039f958c8 and 6E2B3AD039F958C8 are the same key.",
      "maxLength": 255,
      "minLength": 1
    },
    "transferor": {
      "type": "string",
      "description": "Transferor's full Federal Firearms License (FFL) number, with or without dashes. FastBound auto-completes transferor information from FFLs.com; the FFL must be current and valid there or the request is rejected, and some FFL types are not supported. Check a number at https://www.ffls.com/ffl/{fflNumber}.",
      "pattern": "^[1345689]-?\\d{2}-?\\d{3}-?(?:01|02|03|06|07|08|09|10|11)-?\\d[A-HJ-M]-?\\d{5}$",
      "$comment": "The pattern encodes the valid region digits (2 and 7 do not exist) and the nine valid type codes."
    },
    "transferee": {
      "type": "string",
      "description": "Transferee's full Federal Firearms License (FFL) number, with or without dashes. Must correspond to an existing FastBound account, matched together with transferee_emails.",
      "pattern": "^[1345689]-?\\d{2}-?\\d{3}-?(?:01|02|03|06|07|08|09|10|11)-?\\d[A-HJ-M]-?\\d{5}$",
      "$comment": "Same region and type-code rules as transferor."
    },
    "transferee_emails": {
      "type": "array",
      "description": "One or more email addresses used to route the transfer to the transferee's FastBound account. At least one must be the email of a FastBound user with access to that account. If you want to route transfers to a shared address such as orders@example.com or returns@example.com instead of individual FastBound users, contact support@fastbound.com to set that up. If no address matches, the transfer cannot be routed. Addresses are compared case-insensitively and duplicates are ignored.",
      "items": {
        "type": "string",
        "format": "email"
      },
      "minItems": 1,
      "uniqueItems": true
    },
    "tracking_number": {
      "type": [
        "string",
        "null"
      ],
      "description": "Tracking number. Any value is accepted, but only UPS, FedEx, and USPS formats render as a tracking link in the FastBound UI.",
      "maxLength": 100
    },
    "po_number": {
      "type": [
        "string",
        "null"
      ],
      "description": "Purchase Order number.",
      "maxLength": 100
    },
    "invoice_number": {
      "type": [
        "string",
        "null"
      ],
      "description": "Invoice number.",
      "maxLength": 100
    },
    "acquire_type": {
      "type": [
        "string",
        "null"
      ],
      "description": "Acquisition Type (e.g., Purchase).",
      "maxLength": 100,
      "examples": [
        "Purchase"
      ]
    },
    "note": {
      "type": [
        "string",
        "null"
      ],
      "description": "A note relating to all of the firearms in this transfer.",
      "maxLength": 1000
    },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "manufacturer": {
            "type": "string",
            "description": "The manufacturer marked on the firearm.",
            "maxLength": 100,
            "minLength": 1
          },
          "importer": {
            "type": [
              "string",
              "null"
            ],
            "description": "The importer marked on the firearm.",
            "maxLength": 100
          },
          "country": {
            "type": [
              "string",
              "null"
            ],
            "description": "The country of manufacture. Required only when the transferee's account settings require country of manufacture; optional otherwise.",
            "maxLength": 100
          },
          "model": {
            "type": "string",
            "description": "The model marked on the firearm.",
            "maxLength": 100,
            "minLength": 1
          },
          "caliber": {
            "type": "string",
            "description": "The caliber or gauge marked on the firearm.",
            "maxLength": 100,
            "minLength": 1
          },
          "type": {
            "type": "string",
            "description": "Type of the item (e.g., Pistol). Use an approved item type where possible; see https://fastb.co/unapproved-item-type for details.",
            "maxLength": 100,
            "minLength": 1
          },
          "serial": {
            "type": "string",
            "description": "The serial number marked on the firearm.",
            "maxLength": 100,
            "minLength": 1
          },
          "sku": {
            "type": [
              "string",
              "null"
            ],
            "description": "Stock Keeping Unit.",
            "maxLength": 50
          },
          "mpn": {
            "type": [
              "string",
              "null"
            ],
            "description": "Manufacturer's Part Number.",
            "maxLength": 50
          },
          "upc": {
            "type": [
              "string",
              "null"
            ],
            "description": "Universal Product Code (UPC). Null, or a string of 11 to 18 digits.",
            "pattern": "^\\d{11,18}$"
          },
          "barrelLength": {
            "type": [
              "number",
              "null"
            ],
            "description": "The length of the barrel in inches (i.e., 4.48). A value of 0.0 is discarded and stored as null.",
            "minimum": 0
          },
          "overallLength": {
            "type": [
              "number",
              "null"
            ],
            "description": "The overall length in inches (i.e., 8.03). A value of 0.0 is discarded and stored as null.",
            "minimum": 0
          },
          "cost": {
            "type": [
              "number",
              "string",
              "null"
            ],
            "description": "Cost of the item. Accepts a number or a currency string such as $1,299.00. A value of 0.0 is discarded and stored as null.",
            "minimum": 0
          },
          "price": {
            "type": [
              "number",
              "string",
              "null"
            ],
            "description": "Selling price of the item. Accepts a number or a currency string such as $1,299.00. A value of 0.0 is discarded and stored as null.",
            "minimum": 0
          },
          "condition": {
            "type": [
              "string",
              "null"
            ],
            "description": "Condition of the item (e.g., New or Used).",
            "maxLength": 50,
            "examples": [
              "New",
              "Used"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "description": "A note concerning just this firearm.",
            "maxLength": 1000
          }
        },
        "required": [
          "manufacturer",
          "model",
          "caliber",
          "type",
          "serial"
        ],
        "title": "Transfer Item",
        "description": "A single firearm included in the transfer."
      },
      "minItems": 1
    }
  },
  "required": [
    "$schema",
    "idempotency_key",
    "transferor",
    "transferee",
    "transferee_emails",
    "items"
  ]
}

schemas.FastBound.org

Transfer Push Schema