Responding to RFIs

A Request for Information (RFI) is raised when compliance needs something more from a customer before verification can complete. It names exactly which documents or fields are missing, expired, or invalid, so you never have to guess what to resend. An RFI puts the customer into ACTION_REQUIRED and holds verification there until you respond. Nothing progresses in the meantime.

An RFI can also be raised after a customer is already APPROVED. In that case the customer status does not change. The only signal is the customer.rfi webhook and the populated request_for_information array.

How an RFI Reaches You

There are two ways to find an open RFI, and both carry the same structure.

Channel	Reference	When to use it
`customer.rfi` webhook	customer.rfi	Primary path. Fires the moment compliance raises the request.
`request_for_information` field	GET /v2/customers/:customer-id	Reconciliation. Read the open RFI on demand, or recover one whose webhook you missed.

The customer.status webhook fires alongside customer.rfi when the status actually changes. Treat customer.rfi as the payload that tells you what to do, and customer.status as the state transition.

Reading the RFI Payload

The payload is a list of sections. Each section holds one or more document categories, and each category holds the individual fields with a problem.

request_for_information[]
└── section            The document section with the issue
    └── categories[]
        └── document_type   The document that was requested or rejected
            └── fields[]
                ├── field_name   The specific field to resubmit
                ├── data_type    URI, DATE, TEXT, or ENUM
                ├── status       MISSING, EXPIRED, or INVALID
                ├── side         FRONT or BACK, file fields only
                └── reason       Why it was rejected, null when MISSING

Field Status Values

Status	Meaning	What to send
`MISSING`	The document or field was never provided. `reason` is `null`.	The missing document or value.
`EXPIRED`	The document has passed its expiry date.	A current document of the same type.
`INVALID`	The value does not meet requirements. `reason` explains why.	A corrected document or value.

Section Values by Customer Type

Customer Type	Sections
Individual	`proof_of_identity`, `proof_of_address`, `tos_policies_value`
Business V1	`company_details`, `ownership_structure`, `legal_presence`
Business V2	`formation_documents`, `ownership_documents`, `supporting_documents`
Associated Party (V1)	`proof_of_identity`, `proof_of_address`
Associated Party (V2)	`identifying_documents`, `tax_info`, `address_documents`

An RFI can be scoped to the customer’s own records or to a specific associated party. Sections from the associated party rows above tell you the request concerns a party rather than the business itself.

Example: The `customer.rfi` Webhook

An individual customer whose passport has expired on the front, is damaged on the back, is missing both dates, and carries a name mismatch:

{
  "event": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "event_reference_id": "cust-uuid-1234",
    "type": "customer.rfi",
    "created_at": "2026-04-04T10:00:00.000000Z",
    "sandbox_mode": false
  },
  "data": {
    "customer_id": "cust-uuid-1234",
    "request_for_information": [
      {
        "section": "proof_of_identity",
        "categories": [
          {
            "document_type": "GOVERNMENT_ID",
            "fields": [
              {
                "field_name": "files",
                "data_type": "URI",
                "status": "EXPIRED",
                "reason": "Document has expired",
                "side": "FRONT"
              },
              {
                "field_name": "issue_date",
                "data_type": "DATE",
                "status": "MISSING",
                "reason": null
              }
            ]
          }
        ]
      },
      {
        "section": "proof_of_address",
        "categories": [
          {
            "document_type": "PROOF_OF_ADDRESS",
            "fields": [
              {
                "field_name": "files",
                "data_type": "URI",
                "status": "MISSING",
                "reason": null
              }
            ]
          }
        ]
      }
    ]
  }
}

Every webhook request is signed. Verify the x-fin-signature header before acting on the payload. See Verifying webhooks.

Example: Get Customer Details

The same request is readable at any time on the customer record. request_for_information is an empty array when nothing is outstanding.

{
  "data": {
    "customer_id": "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06",
    "type": "BUSINESS",
    "business_name": "Fin.com",
    "customer_status": "ACTION_REQUIRED",
    "request_for_information": [
      {
        "section": "ownership_documents",
        "categories": [
          {
            "document_type": "SHAREHOLDER_REGISTRY",
            "fields": [
              {
                "field_name": "files",
                "data_type": "URI",
                "status": "INVALID",
                "reason": "Unacceptable document."
              }
            ]
          }
        ]
      }
    ]
  }
}

For individual customers the same array is returned by GET /v1/customers/:customer-id, with two additional fields per entry: scope, which is CUSTOMER or ASSOCIATED_PARTY, and options, which lists permitted values when data_type is ENUM.

Responding to an RFI

Responding takes two calls: upload the files, then patch the customer with the returned URIs.

Upload the replacement files

Post the files to POST /v1/customers/upload as multipart/form-data. Field names are arbitrary and are echoed back as the keys in the response.

curl -X POST https://sandbox.api.fin.com/v1/customers/upload \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -F "customer_id=ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06" \
  -F "passport=@passport-front.jpg" \
  -F "poa=@utility-bill.pdf"

{
  "data": {
    "files": [
      { "passport": "/CwW9PHhP_passport-front.jpg" },
      { "poa": "/KVdLfqjR_utility-bill.pdf" }
    ]
  }
}

Allowed file types are PDF, JPG, JPEG, and PNG. Keep the returned URIs; the next call needs them.

Submit the response

Send the requested fields to PATCH /v1/customers/:customer-id. The same endpoint serves individual and business customers, and its body accepts the same fields as the Attach Documents endpoints.

Submit only the fields the RFI listed. Sending data that was not requested returns an error.

Watch for the outcome

The customer returns to REVIEWING while compliance reassesses. Listen on customer.status for the result, and on customer.rfi in case a further request is raised.

Individual Customer Response

Answering the proof_of_identity and proof_of_address sections from the webhook example above:

{
  "proof_of_identity": {
    "type": "PASSPORT",
    "number": "A12345678",
    "country": "USA",
    "issue_date": "2020-01-15",
    "expiry_date": "2030-01-15",
    "files": [
      { "uri": "/CwW9PHhP_passport-front.jpg", "side": "FRONT" }
    ]
  },
  "proof_of_address": {
    "type": "UTILITY_BILL",
    "country": "USA",
    "files": [
      { "uri": "/KVdLfqjR_utility-bill.pdf" }
    ]
  }
}

Business Customer Response

Business sections map to top level arrays. An RFI scoped to an associated party is answered inside associated_party_attachments, keyed by associated_party_id:

{
  "ownership_documents": [
    {
      "type": "PROOF_OF_SIGNATORY_AUTHORITY",
      "description": "Shareholder Registry",
      "files": [
        { "uri": "/AbAcQ4hn_0652746727639.pdf" }
      ]
    }
  ],
  "associated_party_attachments": [
    {
      "associated_party_id": "f6b13e01-044a-4f74-a70b-d5f66b6449af",
      "identifying_documents": [
        {
          "type": "PASSPORT",
          "number": "A12345678",
          "country": "USA",
          "issue_date": "2020-01-15",
          "expiry_date": "2030-01-15",
          "files": [
            { "uri": "/AbAcQ4hn_0652746727637.pdf" }
          ]
        }
      ],
      "address_documents": [
        {
          "type": "BANK_STATEMENT",
          "files": [
            { "uri": "/AbAcQ4hn_0652746727638.pdf" }
          ]
        }
      ]
    }
  ]
}

A successful patch returns the customer ID:

{
  "data": {
    "customer_id": "ed54db74-7dbe-47d2-8ea0-c2bf2a9dda06"
  }
}

A 400 response means validation failed. The data object names the offending fields. A 404 means the customer ID does not exist.

Common Mistakes

Mistake	Result
Sending fields the RFI did not ask for	Request rejected with a validation error.
Resubmitting the document or field value that was rejected, unchanged	A second RFI naming the same field. Read `reason` and send a corrected or replacement version, not the original.
Omitting `side` on a two sided document	The missing side stays outstanding.
Patching before the upload call	The URIs do not resolve and the documents are not attached.
Treating `ACTION_REQUIRED` as terminal	Verification resumes as soon as the RFI is answered.

Get started

Coverage

Customers and compliance

Beneficiaries

Virtual accounts

Webhooks

Move money

Operations

Orchestration Dashboard

Crypto Orchestration

Responding to RFIs

How an RFI Reaches You

Reading the RFI Payload

Field Status Values

Section Values by Customer Type

Example: The `customer.rfi` Webhook

Example: Get Customer Details

Responding to an RFI

Individual Customer Response

Business Customer Response

Common Mistakes

​How an RFI Reaches You

​Reading the RFI Payload

​Field Status Values

​Section Values by Customer Type

​Example: The customer.rfi Webhook

​Example: Get Customer Details

​Responding to an RFI

​Individual Customer Response

​Business Customer Response

​Common Mistakes

How an RFI Reaches You

Reading the RFI Payload

Field Status Values

Section Values by Customer Type

Example: The `customer.rfi` Webhook

Example: Get Customer Details

Responding to an RFI

Individual Customer Response

Business Customer Response

Common Mistakes