RFIs

Upload files to a document item

Answer a document item by uploading its files as multipart/form-data. Every file goes under the files field, and one call can carry several: an item asking for “your last 3 months of statements” is one thing asked whose answer happens to be N files.

Uploading adds to the set — it never replaces it. Sending the second statement does not delete the first. The first upload leaves the item answered; a later one moves updated_at and leaves first_answered_at where it was.

The limits are the item’s own answer_spec (mime_types, max_files), and a file outside them is a 422 naming that limit with nothing stored. An item with no spec still has ceilings: application/pdf, image/jpeg, image/png, image/heic, image/webp, at most 20 files, each at most 30 MB. A spec can only narrow those, never widen them — so answer_spec is the complete rule.

A file’s bytes are checked against its declared type, so a payload renamed to .pdf is refused rather than stored; checksum is the SHA-256 of what we received. Base64 inside the batch PATCH is deliberately not an option — it inflates a file by a third and doubles the memory needed to handle it.

POST

rfis

{rfi_id}

items

{item_id}

documents

Upload files to a document item

curl --request POST \
  --url https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form 'files=<string>' \
  --form files.items='@example-file'

import requests

url = "https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents"

files = { "files.items": ("example-file", open("example-file", "rb")) }
payload = { "files": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "x-api-key": "<api-key>"
}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('files', '<string>');
form.append('files.items', '{
  "fileName": "example-file"
}');

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'x-api-key': '<api-key>'}
};

options.body = form;

fetch('https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents")
  .header("Authorization", "Bearer <token>")
  .header("x-api-key", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-api-key"] = '<api-key>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "item": {
    "item_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "ordinal": 123,
    "prompt": "<string>",
    "answer_type": "text_long",
    "answer_spec": {
      "mime_types": [
        "application/pdf"
      ],
      "max_files": 5
    },
    "target_key": "<string>",
    "status": "pending",
    "answer_value": "<string>",
    "documents": [
      {
        "document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "file_name": "january.pdf",
        "mime_type": "application/pdf",
        "size_bytes": 123,
        "uploaded_at": "2023-11-07T05:31:56Z",
        "checksum": "<string>"
      }
    ],
    "review_note": "<string>",
    "updated_at": "2023-11-07T05:31:56Z",
    "returned_at": "2023-11-07T05:31:56Z"
  }
}

{
  "code": "<string>",
  "message": "<string>",
  "error": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ],
  "details": "<array>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

Stable since 2025-01-01 — unchanged in 2026-06-01.

Authorizations

Authorization

string

header

required

Access token from POST /auth (the data.access_token value).

x-api-key

string

header

required

API key issued by Kira. Required on every request, including /auth.

Headers

X-Api-Version

string

Optional. The date-versioned API version to apply for this request (e.g. 2026-04-14). When sent it always wins, even over your pinned account default. When omitted, the API uses your account's pinned version if set, otherwise a baseline default.

Example:

"2026-06-01"

Path Parameters

rfi_id

string<uuid>

required

RFI UUID.

item_id

string<uuid>

required

Item UUID. The item must be a document item of this RFI.

Body

multipart/form-data

files

file[]

required

One or more files. Repeat the field per file.

Response

The files were stored and the item is answered.

The item after the change, in the same shape every read of it returns — so the whole resulting set of files and the item's status come back together.

item

object

required

One thing being asked for. The addressable unit of an RFI — a PATCH or a document upload always names an item_id, never the parent RFI.

Show child attributes

Upload files to a document item

curl --request POST \
  --url https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --header 'x-api-key: <api-key>' \
  --form 'files=<string>' \
  --form files.items='@example-file'

import requests

url = "https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents"

files = { "files.items": ("example-file", open("example-file", "rb")) }
payload = { "files": "<string>" }
headers = {
    "Authorization": "Bearer <token>",
    "x-api-key": "<api-key>"
}

response = requests.post(url, data=payload, files=files, headers=headers)

print(response.text)

const form = new FormData();
form.append('files', '<string>');
form.append('files.items', '{
  "fileName": "example-file"
}');

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'x-api-key': '<api-key>'}
};

options.body = form;

fetch('https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: multipart/form-data",
    "x-api-key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("x-api-key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents")
  .header("Authorization", "Bearer <token>")
  .header("x-api-key", "<api-key>")
  .body("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.balampay.com/v1/rfis/{rfi_id}/items/{item_id}/documents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["x-api-key"] = '<api-key>'
request.body = "-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files\"\r\n\r\n<string>\r\n-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"files.items\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n{\r\n  \"fileName\": \"example-file\"\r\n}\r\n-----011000010111000001101001--"

response = http.request(request)
puts response.read_body

{
  "item": {
    "item_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "ordinal": 123,
    "prompt": "<string>",
    "answer_type": "text_long",
    "answer_spec": {
      "mime_types": [
        "application/pdf"
      ],
      "max_files": 5
    },
    "target_key": "<string>",
    "status": "pending",
    "answer_value": "<string>",
    "documents": [
      {
        "document_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "file_name": "january.pdf",
        "mime_type": "application/pdf",
        "size_bytes": 123,
        "uploaded_at": "2023-11-07T05:31:56Z",
        "checksum": "<string>"
      }
    ],
    "review_note": "<string>",
    "updated_at": "2023-11-07T05:31:56Z",
    "returned_at": "2023-11-07T05:31:56Z"
  }
}

{
  "code": "<string>",
  "message": "<string>",
  "error": "<string>",
  "errors": [
    {
      "field": "<string>",
      "message": "<string>"
    }
  ],
  "details": "<array>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

{
  "message": "<string>",
  "code": "<string>",
  "statusCode": 123,
  "error": "<string>",
  "timestamp": "<string>",
  "path": "<string>",
  "details": "<unknown>"
}

Authentication

Versioning

Users

Virtual Accounts

Quotations

Payouts

Recipients

Reference

RFIs

Upload files to a document item

Authorizations

Headers

Path Parameters

Body

Response