API description checklist compliance review

[anthorange]

Problem description
This issue is based on the Camara Marketing “Checklist for API description review”:
https://github.com/camaraproject/Marketing/blob/main/documentation/SupportingDocuments/Checklist_for_API_description_review.md

The Number Verification API page reviewed:
https://camaraproject.org/number-verification/

The page has checklist compliance gaps for:

• API Description (the image is only illustrative)
• Use Cases (missing GSMA Use Case Library links)
• Sub Project Wiki (incorrect prefix)
• API Version(s) and Release Date(s) (extra tokens)

Expected action
Please update the Number Verification API documentation page so it matches the checklist by applying the following corrections:

1. API Description

• The image is currently illustrative and does not clearly represent a “typical use case” workflow/value for developers (as expected by the checklist).

2. Use Cases

• Add GSMA links that match appropriate use cases: https://www.gsma.com/solutions-and-impact/gsma-open-gateway/gsma_resources/frictionless-identity-verification-for-fraud-prevention/.

3. Sub Project Wiki

• The correct prefix is "Sub Project Wiki:" (current prefix: "SubProject Wiki:")

4. API Version(s) and Release Date(s)

• Remove extra non-matching tokens (e.g. “initial release”) or modify the checklist.

Additional context
Checklist reference:
https://github.com/camaraproject/Marketing/blob/main/documentation/SupportingDocuments/Checklist_for_API_description_review.md

Reviewed page export:
https://camaraproject.org/number-verification/

[MarkusKuemmerle]

Hello,

the CAMARA outreach team is currently reviewing all the API descriptions to improve it and make it attractive for customers and developers. There is some confusion how to handle and solve the findings. I would like to give the following recommendations:

• Findings in the text of API description, Use Cases, Benefits: These should be solved by the Sub Project, changes should be documented in the API description Wiki page, and then the Sub Project should open an issue in the Marketing repo to change the website. This follows the defined process description to change the website.

• Findings in the visuals: The Sub Project should give instructions to improve the visuals following the criterias defined in the checklist. The instructions also can be included in the wiki page and addressed to the outreach team by issue in the Marketing repo. We plan to ask the LF creative team to generate new visuals for us based on these instructions.

• Findings on the right column (with all the links): Reviewers should put these findings in the review xls and not in the issue. Sub Projects cannot solve it. The CAMARA outreach team is taking the findings from the xls and is changing the website.

So please work on 1. and 2. and ignore 3. and 4. in the first comment above.

Hope that helps, Markus

[albertoramosmonagas]

Hi @MarkusKuemmerle, @anthorange, thanks for the clarification. I have prepared a proposal for review by the Sub Project owners (@camaraproject/number-verification_codeowners) based on the guidelines created by the Marketing team: https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/808058914/Number+Verification+API+description+v2

I updated the API description to make it more developer-centric and technically precise, focusing on the actual Number Verification value. I also clarified the two API capabilities: phone number verification, returning devicePhoneNumberVerified: true/false, and device phone number retrieval, returning devicePhoneNumber where supported and legally allowed. I

I replaced the current illustrative image with instructions for a workflow-style visual showing a typical developer use case.

The end user starts onboarding, login, account recovery, device binding or transaction validation; the business application calls the CAMARA Number Verification API through Open Gateway; the mobile network or SIM-based mechanism validates the phone number associated with the authenticated device; the API returns devicePhoneNumberVerified: true/false or devicePhoneNumber; and the application continues the journey or applies a risk-based action.

I updated the Use Cases section to make it more actionable and aligned with the checklist, and also added the GSMA Use Case Library reference for “Frictionless Identity Verification for Fraud Prevention”.