Onboarding RFI

Answer Harbor's requests for more information about a Customer.

Sometimes Harbor needs more information about a Customer, for example a recent proof of address or a document that shows who can act for a company. This is a Request for Information (RFI). It doesn't change the onboarding information the Customer already sent.

ActionEndpoint
Get the RFI questionsGET /api/v1/customers/{customer_uuid}/rfi
Send the RFI answersPOST /api/v1/customers/{customer_uuid}/rfi/answer

How It Works

  1. Harbor raises an RFI. The Customer's state changes to update_required. Their status doesn't change. Harbor sends the customer.rfi.raised webhook, and the Customer has an rfi_link.
  2. The Customer answers the RFI, on Harbor's page or through your app.
  3. Harbor reviews the answers.
  4. Harbor sends the customer.rfi.resolved webhook.

Answer on the Hosted Page

Send the Customer to the rfi_link. They answer the questions and upload any files there.

This is the simplest option, and it works for every RFI.

Answer With the API

Use this to show the questions in your own app.

Get the Questions

GET /api/v1/customers/{customer_uuid}/rfi

{
    "data": {
        "type": "general",
        "status": "pending",
        "description": "Please provide additional documents.",
        "questions": [
            {
                "key": "1",
                "label": "Bank statements",
                "type": "file",
                "required": true,
                "limit": {
                    "count": { "min": 1, "max": 6 },
                    "size": { "min": 100, "max": 8192 },
                    "acceptType": ["jpg", "png", "pdf"]
                }
            }
        ],
        "answers": null
    }
}

Each question has a type and its own limit:

TypeAnswerlimit
short_answerTextlength: the shortest and longest answer
selectOne of the optionsNone
multi_selectOne or more of the optionsNone
fileOne or more filescount: how many files. size: the smallest and largest file, in KB. acceptType: the allowed file types

Send the Answers

POST /api/v1/customers/{customer_uuid}/rfi/answer

Send the answers in one multipart/form-data request. Use each question's key in the field names:

FieldUse for
answers[key]short_answer and select answers
answers[key][]Each value of a multi_select answer
files[key][]Each file for a file question
files[key]A single file, without []

You can leave out answers if every question is a file question.

curl --location --request POST 'https://harbor-sandbox.owlpay.com/api/v1/customers/{{CUSTOMER_UUID}}/rfi/answer' \
--header 'Accept: application/json' \
--header 'X-API-KEY: {{API_KEY}}' \
--header 'X-Idempotency-Key: {{IDEMPOTENCY_KEY}}' \
--form 'files[1][]=@"statement-jan.pdf"' \
--form 'files[1][]=@"statement-feb.pdf"'

The RFI's status changes to answered. An RFI can only be answered once.

What Happens Next

After you send the answers, Harbor reviews them. When the review is done, Harbor sends customer.rfi.resolved.

Errors

StatusMeaning
422 (code 2005)An answer didn't pass Harbor's checks, for example too many files, a file that's too large, the wrong file type, a missing required answer, a file for a non-file question, or an unknown key. details is keyed by question key. Basic request checks, such as a .exe file or nothing sent, return errors keyed like files.2.0 instead.
422 (code 9924)The review service rejected the submission. details explains why, for example a non-PDF file under 100 KB.
400The service returned an error, or the RFI isn't pending anymore. Get the RFI again to see its current state.
409The RFI was already answered, or has conditional questions (requires_manual_review, with no questions). For conditional questions, the Customer must answer on the rfi_link page.

Notes

Files

  • Follow each file question's limit: how many files, the size range in KB, and the allowed file types. Harbor rejects files that don't meet the limit.
  • Each file can be up to 20 MB. It must be a .pdf, .jpg, .jpeg, .png, .doc or .docx file, and the type must also be in the question's acceptType. A file that is not a PDF must be at least 100 KB (size.min), or Harbor rejects it with 422 (code 9924).
  • A 200 doesn't mean the files passed the malware scan. The scan runs after you upload, and Harbor doesn't tell you if a file fails.

Retries

  • Send an X-Idempotency-Key header when you retry. For 24 hours, Harbor returns the same response to a repeat request with the same key. If the first request is still running, Harbor returns 202 with code 2004 (general.idempotency_conflict).

Server Setup

  • Call this endpoint from your server, and keep your API key out of the browser. Harbor doesn't send CORS headers, so a browser can't call it directly. Have your frontend send the form to your backend, then forward it to Harbor and return Harbor's status and body unchanged.
  • Let your HTTP client set the Content-Type header, so it adds the multipart boundary.
  • Raise your server's upload limit to at least 20 MB per file. Otherwise your Customer sees your server's 413 instead of Harbor's 422.

Action Required

  • An RFI isn't the same as action_required. With action_required, you correct the onboarding with PATCH. See Fix Onboarding Errors.

Transfer RFI

  • An onboarding RFI is about the Customer. The Customer's state is update_required, and Harbor sends the customer.rfi.raised webhook.
  • If Harbor needs more information about a transfer instead, it's a transfer RFI. The transfer's status is request_for_information, and Harbor sends the transfer.status.request_for_information webhook. See Transfer RFI.

Did this page help you?