Additional Information | Vodafone Developer Marketplace

A Three-legged OAuth Flow

Number Recycling (CAMARA) uses a three-legged OAuth flow. A three-legged OAuth process involves three parties: the end-user (or resource owner), the client (the third-party application), and the server (or authorization server):

Get an authorization code
Exchange the authorization code for an access token
Check Mobile number Recycle status

For more information on OAuth, see OAuth 2.0 RFC 6749, section 4.1 (external website).

Get an Authorization Code

Make a request to Vodafone’s “/bc-authorize” endpoint.
Vodafone's API validates the client_id provided.
Vodafone provides an auth_req_id in the response that can be used for token call.

Authorization request example

curl -X 'POST' \
  'https://api-sandbox.vf-dmp.engineering.vodafone.com/openIDConnectCIBA/v1/bc-authorize' \
  -H 'accept: application/json' \
  -H 'x-correlator: b4333c46-49c0-4f62-80d7-f0ef930f1c46' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'login_hint=tel%3A%2B447772000001&scope=openid%20number-recycling%3Acheck'

Authorization response example

HTTP/1.1 200 OK
{
  "interval": 0,
  "auth_req_id": "55a03e56-ba3a-42a0-a4f8-1a0f418061e4",
  "expires_in": 60
}

Get an Access Token

In order to use this API, you must exchange the auth_req_id for an access token.

The token is valid for 59 minutes and 59 seconds. It can be used for multiple requests.

The bearer tokens can only be used for a specific country. For example: If you generate a token for a UK mobile number (MSISDN), you cannot use it to query a German number.

If the request is valid, the API returns an access_token, along with expiry and scope information.
This access token can then be used in one or more requests, for as long as the token remains valid.
If the request is not valid, the API will return an error message.

To exchange the auth_req_id for an access token:

Make a “/token” request.

Token request example

curl -X 'POST' \
  'https://api-sandbox.vf-dmp.engineering.vodafone.com/openIDConnectCIBA/v1/token' \
  -H 'accept: application/json' \
  -H 'x-correlator: b4333c46-49c0-4f62-80d7-f0ef930f1c46' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'auth_req_id=39da5b19-457a-4d30-a5c4-047c62dcca3b&grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba'

Token response example

HTTP/1.1 200 OK
        {
  "access_token": "WabJNPE2bxGkjLR6yndbANzKfPUF",
  "token_type": "Bearer",
  "expires_in": 3597,
  "id_token": "eyJraWQiOiJkbXAtcHJvZC1raWQiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJodHRwczovL2FwaS52Zi1kbXAuZW5naW5lZXJpbmcudm9kYWZvbmUuY29tL21vYmlsZWNvbm5lY3QvZGV2aWNlaW5pdGlhdGVkL3YxL2F1dGhvcml6ZT8iLCJhdWQiOiJodHRwczovL2FwaS52Zi1kbXAuZW5naW5lZXJpbmcudm9kYWZvbmUuY29tL21vYmlsZWNvbm5lY3QvZGV2aWNlaW5pdGlhdGVkL3YxL3Rva2VuIiwic2hvdyI6IkFuZCBub3cgZm9yIHNvbWV0aGluZyBjb21wbGV0ZWx5IGRpZmZlcmVudC4iLCJpc3MiOiJETVAiLCJleHAiOjE3NzAyMjIyMjUsImlhdCI6MTc3MDIxODYyNSwianRpIjoiMjQ2ZWIxZGMtYjA5OC00NjYzLWFiMjYtOTMxZmYzMzlkOTkwIn0.2SwSiZ6lkmcCsgw61VMHpkhzBDqt5KFYOt5VCVGdNcCy4Wf13YyEikG0qOJQ4fCEVuzWp_5Jq09gnvWXmCLlXGxQndKgrty4edV2PHSF_X8BDAtYe3J2g-l4LXQzE3Wpg6DWhDdiusKp_narBfqkc81K4-FVRW92WaJgFjbIGyRUj1We2CXVJHEFIHaDD4RTK9qVMltpEA3I-_1vlWdGgiXEb2o58s4Yla2W53FePDnsIdTVwzc6PMNoWCixGeu53Es4e3DPgw4pCVBT4VeaAtkupPUe1ZDnJsNQypknQtrqx4Vb3VGM1-iNceuNh0X32OIfDlpbmD8_IJUTtU9W_JXlU6hpIU23E226WgKg2CVEPzJfhjZ1u0iNV-BDULCFkwbtcHGjaraLcj1xTkad1OB3e8oY1BJsaAHngze2Pznx804KZlhp0elmUHhtY4_MrzUYnIiujJ0k8ngMC3fr0IBVG-S3PeSKcZsCxXynMYriKaDDeUwrgpB9qZv-h1vePNZnix34Rhur7kjgE6IHd_qJAF8Z7aGMMVnj8cNqMLU1UjcGyofUKjQ842rmHEFM1PaiU4TzrbhXcS-ZQpbbwm_KhIRlsGQDccoM15Ae9Mk05K8FBWjBNuCxBJn--Q9zuvZX-XGNIxJ4mdQ00CbaZWPr84zDUkfxzMxzL-lqMvc"
}

Number Recycle Check

Retrieves phone number recycle status based on the provided specifiedDate. Requires a valid Bearer Token for authorization.

Number Recycling API request:

This example is of Number Recycling API:

curl -X 'POST' \
  'https://api-sandbox.vf-dmp.engineering.vodafone.com/number-recycling/v0.2.0/check' \
  -H 'accept: application/json' \
  -H 'x-correlator: b4333c46-49c0-4f62-80d7-f0ef930f1c46' \
  -H 'Content-Type: application/json' \
  -d '{
  "specifiedDate": "2025-12-01"
}'

Number Recycle API Response:

Below are the example responses for Number Recycling API.

When there has been a change in the subscriber associated with the specific phone number after “specifiedDate", 'true' is returned.
```
HTTP/1.1 200 OK.
 {
  "phoneNumberRecycled": true
}
                    
```
When there has not been a change in the subscriber associated with the specific phone number after “specifiedDate", 'false' is returned.
```
HTTP/1.1 200 OK.
 {
  "phoneNumberRecycled": false
}
                    
```

Exceptions: If there is Problem with the client request

HTTP/1.1 400.
{
  "status": 400,
  "code": "INVALID_ARGUMENT",
  "message": "Client specified an invalid argument, request body or query param."
}

If there is Authentication problem with the client request and Request cannot be authenticated and a new authentication is required

HTTP/1.1 401.
{
  "status": 401,
  "code": "UNAUTHENTICATED",
  "message": "Request not authenticated due to missing, invalid, or expired credentials. A new authentication is required."
}

When client does not have sufficient permission

HTTP/1.1 403.
{
  "status": 403,
  "code": "PERMISSION_DENIED",
  "message": "Client does not have sufficient permissions to perform this action"
}

When provided phone number is used by a different network operator.

HTTP/1.1 404.
{
  "status": 404,
  "code": "IDENTIFIER_NOT_FOUND",
  "message": "Phone number not found."
}

When service not applicable for the provided phone number.

HTTP/1.1 422.
{
  "status": 422,
  "code": "SERVICE_NOT_APPLICABLE",
  "message": "The service is not available for the provided phone number"
}

Number Recycling (CAMARA)