# For Sellers

# Join the Waitlist

The Floom market isn't yet open to all developers. Please email directly at rob@floom.app if you'd like to get your product listed.

# How it Works

# Direct Response APIs

Direct response APIs respond directly to requests with a response containing the output. You'll receive a request that looks like this:

// sent to your-api.com/input-endpoint
{
  "id": "81d6cc31-b6d5-4425-9d3f-77a8c8563484", // Floom order id
  "input": {
    // contains user input
    "videoSrc": "storage.floom.app/customer-upload.mp4", // customer uploaded video
    "videoTitle": "Awesome Video" // more customer input
  }
}

It will contain the attributes that you specify as required for your API (e.g. videoSrc and videoTitle).

If you list your API as a direct response API, you must respond to this request with the order output value.

# Order Direct Response (preferred)

[
  {
    "key": "vid",
    "type": "VIDEO",
    "value": "https://s3.amazonaws.com/your-bucket/customer-video.mp4",
    "label": "Your Video Trailer"
  }
]

You'll notice that we use an array structure here instead of a simple map. This allows you, as a vendor, to associate a type for each output value. For instance, here we specify that we are outputting a VIDEO, which allows Floom to present this to the customer as a video, instead of just a URL. The available types are TEXT, IMAGE, VIDEO, LINK, and AUDIO.

Similarly, the label is a customer facing attribute which labels each output value. The key attribute exists as a good practice for vendor bookkeeping purposes.

Alternatively, if required, the vendor can send a response in the following simplified form

# Order Direct Response (alternate)

{
  "vid": "https://s3.amazonaws.com/your-bucket/customer-video.mp4"
}

# Webhook (push) APIs

Webhook, or push, services:

1. Accept an order and start processing
2. Fulfill the order through a webhookk when done processing

You'll receive a request that looks like this:

// sent to your-api.com/input-endpoint
{
  "id": "81d6cc31-b6d5-4425-9d3f-77a8c8563484", // Floom order id
  "input": {
    // contains user input
    "videoSrc": "storage.floom.app/customer-upload.mp4", // customer uploaded video
    "videoTitle": "Awesome Video" // more customer input
  }
}

It will contain the attributes that you specify as required for your API (e.g. videoSrc and videoTitle).

To notify Floom that you are processing the order you must send a response that contains status set to received.

{
  "status": "received"
}

If you would like to reject the order (for instance if the an input is not valid), you can send a response with "status": "reject".

{
  "status": "reject",
  "description": "Optional reason for rejection that will display to customer"
}

When you are done processing the order, you can fullfil it by sending the out to Floom's endpoint at https://api.floom.app/fulfill.

The available output types are TEXT, IMAGE, VIDEO, LINK, and AUDIO.

Importantly, you must include your seller API key in the header as an x-api-key key value pair.

// POST to https://api.floom.app/fulfill
// with x-api-key: your-api-key
{
  "id": "order-id",
  "status": "complete",
  "output": [
    {
      "key": "vid",
      "type": "VIDEO",
      "value": "https://s3.amazonaws.com/your-bucket/customer-video.mp4",
      "label": "Your Video Trailer"
    }
  ]
}

You can also send progress updates which will be shown to the customer.

// POST to https://api.floom.app/fulfill
// with x-api-key: your-api-key
{
  "id": "order-id",
  "status": "pending",
  "description": "Rendering 58% complete"
}

If an order fails, respond with a "failed" status

// POST to https://api.floom.app/fulfill
// with x-api-key: your-api-key
{
  "id": "order-id",
  "status": "failed",
  "description": "Failed to render video"
}

# Status Polling APIs

Status polling APIs need more time to process orders, and follow a status polling pattern. When a customer places an order, the order is initiated by sending a request that contains the customer input to your API endpoint. For example, if you sell a service which adds a title screen to videos, you may receive an HTTP request that looks like this:

# New Order Request

// sent to your-api.com/input-endpoint
{
  "id": "81d6cc31-b6d5-4425-9d3f-77a8c8563484", // Floom order id
  "input": {
    // contains user input
    "videoSrc": "storage.floom.app/customer-upload.mp4", // customer uploaded video
    "videoTitle": "Awesome Video" // more customer input
  }
}

To notify Floom that you are processing the order you must send a response that contains status set to received. Optionally, you can also include metadata. This metadata will be handed back to you when we poll for updates of your service. This can by useful, for instance, if you create your own UUID when you receive an order and need a reference to it to respond to the status poll.

{
  "status": "received",
  "metadata": { "key": "value", "another_key": "another_value" } // optional, key value pairs
}

If you would like to reject the order (for instance if the an input is not valid), you can send a response with "status": "reject".

{
  "status": "reject",
  "description": "Optional reason for rejection that will display to customer"
}

We'll then know to mark the order as processing, and to start polling for status updates. We will do this by sending you a request to your status polling endpoint with a body containing the order id

// sent to your-api.com/status-endpoint
{
  "id": "81d6cc31-b6d5-4425-9d3f-77a8c8563484",
  "metadata": { "key": "value", "another_key": "another_value" } // if included in initial order response
}

To this, you must respond with (a) status: pending, (b) status: failed, or (c) status: complete along with the order output.

# Order Status Response (pending)

If you respond with status: pending Floom will keep polling for order fulfillment.

{
  "status": "pending",
  "description": "Optional description that will be displayed to the buyer"
}

# Order Status Response (failed)

If you respond with status: failed, we will stop polling you for this order.

{
  "status": "failed",
  "description": "Optional reason for failure that will display to customer"
}

# Order Status Response (complete, preferred)

{
  "status": "complete",
  "output": [
    {
      "key": "vid",
      "type": "VIDEO",
      "value": "https://s3.amazonaws.com/your-bucket/customer-video.mp4",
      "label": "Your Video Trailer"
    }
  ]
}

You'll notice that we use an array structure here instead of a simple map. This allows you, as a vendor, to associate a type for each output value. For instance, here we specify that we are outputting a VIDEO, which allows Floom to present this to the customer as a video, instead of just a URL. The available types are TEXT, IMAGE, VIDEO, LINK, and AUDIO.

Similarly, the label is a customer facing attribute which labels each output value. The key attribute exists as a good practice for vendor bookkeeping purposes.

Alternatively, if required, the vendor can send a response in the following simplified form

# Order Status Response (complete, alternate)

{
  "status": "complete",
  "output": {
    "vid": "https://s3.amazonaws.com/your-bucket/customer-video.mp4"
  }
}