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.
| Action | Endpoint |
|---|---|
| Get the RFI questions | GET /api/v1/customers/{customer_uuid}/rfi |
| Send the RFI answers | POST /api/v1/customers/{customer_uuid}/rfi/answer |
How It Works
- Harbor raises an RFI. The Customer's
statechanges toupdate_required. Theirstatusdoesn't change. Harbor sends thecustomer.rfi.raisedwebhook, and the Customer has anrfi_link. - The Customer answers the RFI, on Harbor's page or through your app.
- Harbor reviews the answers.
- Harbor sends the
customer.rfi.resolvedwebhook.
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:
| Type | Answer | limit |
|---|---|---|
short_answer | Text | length: the shortest and longest answer |
select | One of the options | None |
multi_select | One or more of the options | None |
file | One or more files | count: 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:
| Field | Use 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
| Status | Meaning |
|---|---|
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. |
400 | The service returned an error, or the RFI isn't pending anymore. Get the RFI again to see its current state. |
409 | The 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 thelimit. - Each file can be up to 20 MB. It must be a
.pdf,.jpg,.jpeg,.png,.docor.docxfile, and the type must also be in the question'sacceptType. A file that is not a PDF must be at least 100 KB (size.min), or Harbor rejects it with422(code9924). - A
200doesn'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-Keyheader 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 returns202with code2004(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-Typeheader, 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
413instead of Harbor's422.
Action Required
- An RFI isn't the same as
action_required. Withaction_required, you correct the onboarding withPATCH. See Fix Onboarding Errors.
Transfer RFI
- An onboarding RFI is about the Customer. The Customer's
stateisupdate_required, and Harbor sends thecustomer.rfi.raisedwebhook. - If Harbor needs more information about a transfer instead, it's a transfer RFI. The transfer's
statusisrequest_for_information, and Harbor sends thetransfer.status.request_for_informationwebhook. See Transfer RFI.
Updated about 14 hours ago