Business verification is rolling out gradually. If these endpoints return
404 for a portfolio in your project, contact support./platform/v1/whatsapp/portfolios/{portfolio_id}, authenticated with your X-API-Key. portfolio_id is the Meta business portfolio ID of a production number in your project. Get phone number returns it as business_portfolio_id, with a business_verification summary.
Each submission takes 1 to 3 documents, and each business portfolio gets 3 attempts, the same as business verification in Kapso. Kapso can only submit for businesses with a number connected through Kapso’s Meta app. For numbers on your own Meta app, verify in Meta’s Security Center.
Check the status
allowed_actions.create_submission is true. status is one of:
New values may be added, so handle unknown ones.
If the status is older than 30 seconds, Kapso reads it from Meta before it responds.
checked_at is the last successful read. If Kapso couldn’t read it for 6 hours, unavailable is true and status is the last known value.
Submit documents
Send 1 to 3 PDF, JPEG, or PNG files of 5 MB or less. Together they must show the legal name and the address in the customer’s Meta business portfolio.roles is optional and says what each file shows.
source_url must be HTTPS. To upload the files instead, send multipart/form-data:
202 with the submission and a Location header. 202 means Kapso accepted the request, not that Meta verified the business. Kapso sends the documents before it responds, so state is usually pending, which means Meta is reviewing them.
If state is failed with a last_error, nothing reached Meta and no attempt was used:
For other codes, read
last_error.message.
The API has no confirmation step. Get the customer’s consent before you send their documents to Meta.
Retries
Idempotency-Key is required, 1 to 255 bytes. If the request times out, retry with the same key and the same documents. You get the same submission back, and Kapso doesn’t download or send anything again.
The same key with different documents returns 409 with code: idempotency_conflict. A renewed signed URL counts as a different document, so keep the original URL for retries. Use a new key only for a new attempt.
If state is outcome_unknown, Kapso is checking with Meta whether it received the documents. Keep polling, and don’t create a new submission: it could use another attempt.
Errors
Poll for the decision
state is approved, failed, discarded, or revoked.
When Meta rejects the documents, state is failed and rejection_reasons says why:
requirement tells you which document to replace. Submit again with a new key. Each resubmission Meta receives uses an attempt.
Documents and privacy
Submissions and their files belong to your project. Other projects with numbers in the same portfolio see the shared status and attempts, but not your submissions or Meta’s reasons. Responses include file metadata, never the files. Kapso keeps the files only to send them to Meta. It deletes them 30 days after Meta decides or the submission fails.documents_purge_after is the deletion date, and documents_purged is true once they’re gone.
The list includes submissions made in the Kapso app. Drafts, editing a submission, and the Kapso Agent document check are only in the app.
MCP
Project MCP has the same operations:
Every tool takes
business_portfolio_id. create_whatsapp_business_verification_submission also takes idempotency_key and documents with HTTPS source_urls. MCP can’t upload files. Agents should ask the user before they call it.
Browser sign-in connections need mcp:business_verification:read to read, and mcp:business_verification:submit to submit. With browser sign-in, only project owners and admins can submit.