Skip to main content
A request for information is a compliance check asking for something instead of declining. Kira raises it against one of your sub-clients. Whatever it holds stays held until it closes. You never create one. You read it, answer it, and watch for the event that closes it. You can answer it through the API or through the dashboard. Both do the same thing; which you use depends on who in your organisation is doing the answering.
Your sub-client never calls this API. You collect the answer in your own interface and send it with your credentials, so every answer is recorded against you. first_answered_at and updated_at are when you sent something, not when your customer supplied it.

How it arrives

By webhook. Four events, and the item-level one matters as much as the request-level ones: Your own answers are not among them. Answering an item is your act, and nothing is sent back to tell you that you did it. One request raises one rfi.raised, however many items it has. Event catalog says which URLs receive rfi.*. List RFIs is the record of what is outstanding. The events prompt you. The list is where you catch up after an outage that outlasted a delivery’s retries.

What a request holds up

Read blocking to know what is held: A request never names an account, only a sub-client, a single movement or one capability request. Other movements for the same sub-client carry on. A request about a capability request holds no movement. It is how compliance asks you for something more before it decides that capability request. The capability request keeps its own status while the request for information is open. A held movement says so on its own resource. While the request is open, the payout or deposit reports status of NEEDS_ACTION. It is not a new stage. The stage underneath does not change, and the movement continues from there when the request closes, however it closes. What a hold means has the rest. A request on a movement asks for less. It asks only for an explanation or a document. target_key is null on every item, and no item asks a beneficial owner to verify. A request on a capability request can also ask for the capability’s own form. An item’s target_key names either a field of the sub-client, as on a request whose blocking is null, or a question of that capability’s form. You answer both kinds the same way. No item on it asks a beneficial owner to verify. Those items come only on a request whose blocking is null.

The deadline

Every request carries a due_at, fixed when it is raised. Answering does not extend it. An item sent back for a second answer keeps the same deadline. If the deadline passes with the request open, it closes as not_resolved with resolution_reason of expired, and you receive that event. Plan to have the answer collected by due_at, not to start on it then.

The item is the unit

A request carries one or more items, each asking for its own thing, each answered on its own and each returnable on its own. One item coming back does not undo the others. An item has two states: pending while something is outstanding, and answered once you have sent it and a reviewer has it. It has no ending of its own. Whether the request was satisfied is recorded on the request, not item by item. The request has four: An answered request goes back to pending if one of its items is sent back. Only resolved and not_resolved are endings. pending always means it is your turn. Branch on the request’s status; you do not need to walk its items.
resolved does not mean every item was answered. A reviewer can resolve the request while an item is still pending — for example, when it asked for something you had already sent. Treat the request as over once it reads resolved, whatever its items say.
A request can also be withdrawn. When Kira stops asking, the request leaves your lists and its own URL answers 404. No event announces it. Treat a request you can no longer fetch as closed.

Answering through the API

Each item declares its own answer_spec: the complete set of rules its answer is checked against. Validate against it before you send, and the call goes through. RFI values has the keys each kind of question carries.

A batch is all or nothing

One call answers one or more items, each named by its item_id. Every answer is checked against its item before any is written. If one does not pass, nothing is written, and the response names the items to fix. There is no partial write to reconcile. Answering only some items is normal. Each item advances on its own, and the request stays pending until nothing is outstanding.

Some kinds of item are not answered in that call

A document item takes files, not a value. Upload them as multipart/form-data, and the upload answers the item. Each upload adds to the item’s files instead of replacing them. Send a second bank statement without re-sending the first, and remove a file explicitly when you need to. The last file cannot be removed, because an answered item needs something to review. To download a file, ask for a short-lived link each time you need it. Do not store the link. A ubo_link item is not answered through the API. It names a beneficial owner Kira has no record of yet, and it closes when that person finishes their own verification. Create a link when your customer asks for it, and hand it over. The API takes no answer for it, not even an empty one. A signature_link item is not answered through the API either. It asks one of the sub-client’s legal representatives to review and sign its U.S. tax form. Create the link the same way and hand it to that representative. The item closes once their signature is recorded as valid. Nor is a fatca_questions item. It asks the sub-client to answer its U.S. tax form questions again. Create the link the same way and hand it to the sub-client. Once they answer, the link is no longer offered, and the item closes when the new form’s signature is recorded as valid.

Answering again

An item sent back is pending again. review_note says what to change and returned_at says when. Answer it the same way as the first time, and the new answer replaces the old one. An item that reads answered is with a reviewer. It cannot be answered again until they accept it or send it back.

Answering through the dashboard

The same requests appear in the dashboard, where someone in your organisation can read and answer them without going through your integration. This is usually the right route when the answer is a document your compliance or finance team holds rather than something your product can collect. Requests have their own section there. They also appear on the sub-client and on the payment they hold, so whoever opens that payment finds the request. Answering needs a login. Getting access explains how to get one. An answer given in the dashboard sends you no event, the same as one given through the API. You learn the outcome from rfi.resolved, rfi.item_returned or rfi.not_resolved.

What a hold means

When money stops, and what moves it again.