CAMARA · GSMA Open Gateway Preview

Number Recycling API

Know when a phone number has a new owner

The Number Recycling API tells you whether the subscriber behind a mobile number has changed since a date you choose, so you stop sending codes, notices or payments to someone who received a recycled number. Based on the CAMARA Number Recycling API.

Preview: this API returns sample responses while the operator connections are completed. You can build and test your integration with it now.

  • Account recovery
  • Notification hygiene
  • Fraud prevention

What you can do with this API

Ready to test? Jump to the sample call and the API reference, where you can try every endpoint. Start testing
Read the full API overview

Number Recycling API

Mobile numbers that are given up are reassigned to new subscribers. If your service still links that number to the old customer, one-time codes, account notices and password resets go to a stranger.

The Number Recycling API answers one question: has this number been assigned to a different subscriber since a given date? Pass the phone number and the date you last verified it (for example the date the customer registered), and the API returns phoneNumberRecycled: true or false.

When to use it

  • Before sending a one-time code or password reset to a stored number.
  • When a customer has been inactive for a long time.
  • As a periodic clean-up of the numbers in your customer base.

Standard

Follows the CAMARA Number Recycling API (GSMA Open Gateway). The operator is chosen from the number's country code.

Questions about the Number Recycling API

What can I do with the Number Recycling API?

The Number Recycling API tells you whether the subscriber behind a mobile number has changed since a date you choose, so you stop sending codes, notices or payments to someone who received a recycled number. Based on the CAMARA Number Recycling API.

  • Has the number changed owner since a date? (POST /check)
Which inputs does each call to the Number Recycling API need?
  • POST /check: requires phoneNumber, specifiedDate

Every call also needs Authorization: Bearer <access_token>. The API reference on this page shows each field's type and an example request.

What does the Number Recycling API return?
  • POST /check returns HTTP 200 with phoneNumberRecycled

Responses are JSON.

How do I authenticate with the Number Recycling API?
  1. Call POST https://api.ooredoo.com/oauth/v1/token with your client ID and client secret. Send grant_type in the body. Use the client ID and secret of your app.
  2. The response contains access_token, token_type, expires_in.
  3. Send Authorization: Bearer <access_token> on each call until the token expires, then request a new one.
Which errors can the Number Recycling API return?
  • 400: Invalid request: a required field is missing or malformed
  • 401: Invalid client credentials
  • 403: The token does not carry the scope this operation needs
  • 429: Quota exceeded
  • 500: Server error
  • 503: Operator backend unavailable

On 401, request a new access token and retry.

Where is the Number Recycling API available?

Number Recycling is available in Algeria, Iraq, Kuwait, Maldives, Oman, Palestine, Qatar and Tunisia.

Which standard does the Number Recycling API follow?

It follows the CAMARA specification of the GSMA Open Gateway initiative, so an integration built for another operator's CAMARA API needs little change. See our CAMARA certification page.

Related APIs

Sample call

From the published OpenAPI specification. Replace the placeholders with your app's credentials and real values.

1. Get an access token

curl -X POST https://api.ooredoo.com/oauth/v1/token \
  -H "client_id: $CLIENT_ID" \
  -H "client_secret: $CLIENT_SECRET" \
  -d "grant_type=client_credentials" \
  -d "client_id=<client_id>" \
  -d "client_secret=<client_secret>"

2. Call the API

curl -X POST https://api.ooredoo.com/number-recycling/v1/check \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+974XXXXXXXX",
    "specifiedDate": "2025-01-01T00:00:00Z"
  }'

API reference

Try any endpoint in the sandbox