How can I attach supporting documents to a Twilio regulatory bundle via Laravel?

Below is some guidance to help ensure your Supporting Documents (identity and address proofs) attach correctly when building your regulatory bundles.

---

Key Points to Verify

1. Base URL
   Make sure you’re uploading documents to the correct endpoint. For file uploads, the base URI must be:

   https://numbers-upload.twilio.com/v2/RegulatoryCompliance/SupportingDocuments
   

   Using the standard Twilio API URL instead will not attach your documents.

2. Form Field Names & Multipart Data
   The API requires a multipart POST using the ‑F flag (or equivalent in your SDK). In particular:

   • The file must be sent in a field named exactly File (case-sensitive).
   • Attributes must be sent as a string containing valid JSON.

3. Correct JSON in Attributes
   Validate the JSON you pass in Attributes includes all required keys (like address_sids, document_number, etc.) exactly as per the sample documentation.

---

Sample Solution Using Curl

The documentation provides a working curl sample similar to the following:

BASHCopied
ATTRIBUTES=$(cat << EOF
{
  "address_sids": ["ADXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"],
  "document_number": "312454",
  "business_name": "Twilio",
  "issue_date": "2019-11-15"
}
EOF
)

curl -X POST https://numbers-upload.twilio.com/v2/RegulatoryCompliance/SupportingDocuments \
  -u {TWILIO_ACCOUNT_SID}:{TWILIO_AUTH_TOKEN} \
  -F "Attributes=$ATTRIBUTES" \
  -F "FriendlyName=Address Proof of {your_user_first_name}" \
  -F "Type={your_document_type}" \
  -F "File=@{path/to/your_file.png}"

Notice that using ‑F correctly formats it as multipart/form-data. Any mismatch or omission (for example, sending JSON or using a different URL) could result in the document not being attached, which in turn causes the bundle to remain in a draft status.

---

Using the Twilio SDK (PHP Example)

When using the PHP SDK (or making your own HTTP requests), ensure the following:

• Use the numbers-upload endpoint. Never send the file data to the standard API.
• Send multipart data. If your HTTP client supports it (like Laravel’s HTTP client), configure it as multipart.
• Set Content-Type correctly for the file, and ensure the file stream is valid before it’s closed.

A corrected version (aligned with the curl sample) might look like this:

PHPCopied
$fileStream = fopen($addressDocumentPath, 'r');

$response = Http::withBasicAuth($twilioClient->username, $twilioClient->password)
    ->asMultipart()
    ->attach('File', $fileStream, basename($addressDocumentPath), ['Content-Type' => $mimeType])
    ->post('https://numbers-upload.twilio.com/v2/RegulatoryCompliance/SupportingDocuments', [
        'Attributes'   => $attributes, // Ensure this is a valid JSON string
        'FriendlyName' => 'Address Proof of ' . $kyc->first_name,
        'Type'         => $kyc->address_document_type,
    ]);

fclose($fileStream);

Make sure that:

• $attributes is a proper JSON string.
• The endpoint exactly matches the numbers-upload URL.
• The file is successfully uploaded via the File form field.

---

Final Notes

If the documents still aren’t attaching:

• Double-check that the file exists at the path and your web server has permission to read it.
• Verify that your JSON attributes are correctly formatted.
• Review any error messages from Twilio’s API for additional guidance.

By ensuring the correct endpoint, proper multipart usage, and exactly matching field names as demonstrated by the documentation’s sample code, your Supporting Documents should attach correctly and your regulatory bundle will advance beyond draft status.

If you have further issues, please share any error messages returned by the API or additional context about your implementation for more targeted assistance.