The SimSwap API provides the customer the ability to obtain information on any recent SIM pairing change related to the User's mobile account.

HTTPS requests to the REST API are protected with 3-Legged OAuth Client-Initiated Backchannel Authentication (CIBA) mode. In short, this API uses Authorization by server initiated login hint mechanism and the final user of the service is requested to give their consent in order to authorize this client application to access their resources.

Step 1: request the back channel authorization from the application

To authenticate the end-user and obtain her/his consent a GET request must be sent to the bc-authorize endpoint from the user device. This request must provide required parameters.

curl -X POST "https://api.partner.com/es/openapi/oauth/v2/bc-authorize
-H 'Authorization: Basic encode64(clien_id:client_secret)'
-H 'Content-type:application/x-www-form-urlencoded'
-d 'scope=dpv%3AFraudPreventionAndDetection%23sim-swap&login_hint=tel%3A%2B346xxxxxxxx'

Once the end-user provided her/his consent, the Orange authorization server will send back to the client application an authorization req_id.

200 {"auth_req_id":"69957d77-fea4-4a4c-8cd2-b29f22e61307","interval":2,"expires_in":120}

Step 2: Request the OAuth access token

Once the client application got the authorization code, it has to get the access token protecting the resoures. In order to retrieve it, the client application triggers a POST request to the token endpoint.

curl -X POST "https://api.partner.com/es/openapi/oauth/v2/token"
-H "Authorization: Basic {your application Basic header}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=urn%3Aopenid%3Aparams%3Agrant-type%3Aciba&auth_req_id=69957d77-fea4-4a4c-8cd2-b29f22e61307"

If the transaction succeeds, in the POST response, the acccess_token is provided.

200 {"access_token":"*****","token_type":"Bearer","expires_in":"119"}

Step 3: Access protected resources using OAuth access token

In order to call our API, the access_token is mandatory.

Specific documentation about number Verification resources is provided below.

Go up

Base URL

The Base URL is the first part of the full invocation URL, just before the resource paths defined in the API reference.

The Base URL is comprised of the scheme ('https'), the authority (i.e. the Fully Qualified Domain Name) and the API base path.

Whenever you request this API and encounter a 404 (Not Found) HTTP status code, please check first that the Base URL is correct.

The Base URL for this API is:

PROD environment: https://api.partner.com/camara/oes/sim-swap/v0

The documentation below assumes that, whenever you make requests on this API, you are prepending the Base URL to the resource paths defined for this API.

Resources

This API has two resources which have their own parameters.

/retrieve-date (POST)

This service returns the timestamp of the most recent SIM card change, capturing the latest alteration between a specific mobile phone number and its corresponding SIM card unique identifier (IMSI).

Request

As an example:

curl 
  --request POST \
  --header 'Authorization: Bearer *****' \
  --data '{"phoneNumber": "+34654654654"}'
  'https://api.partner.com/camara/oes/sim-swap/v0/retrieve-date' 

Response

a/ If the transaction succeeds

On success, the SimSwap API returns a 200 OK HTTP status code with JSON data including the 'latestSimChange' property with information about SIM swap change.

As an example:

HTTP/1.1 200 OK
X-Orange-Trace-Id: 428fe874f806e88e243f73c730103279531ed1e1

{
  "latestSimChange": "2023-09-05T13:57:55.707Z"
}

b/ If the transaction fails

Please visit the common error responses section in this page.

/check (POST)

Checks if SIM swap has been performed during a past period.

Request

As an example:

curl 
  --request POST \
  --header 'Authorization: Bearer *****' \
  --data '{"phoneNumber": "+34654654654","maxAge": 240}'
  'https://api.partner.com/camara/oes/sim-swap/v0/check' 

Response

a/ If the transaction succeeds

On success, the SimSwap API returns a 200 OK HTTP status code with JSON data including the 'swapped' property indicating if SIM swap has been performed during the period.

As an example:

HTTP/1.1 200 OK
X-Orange-Trace-Id: 428fe874f806e88e243f73c730103279531ed1e1

{
  "swapped": true
}

b/ If the transaction fails

Please visit the common error responses section in this page.

Common error responses

In case of error, the SimSwap API returns an error response (JSON format) with the following information:

This is compliant with CAMARA Project specifications, which can be read here. Below is a list of possible error responses.

Problem with the client request:

HTTP/1.1 400 Bad Request
X-Orange-Trace-Id: 428fe874f806e88e243f73c730103279531ed1e1

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

Authentication problem with the client request:

HTTP/1.1 401 Unauthorized
X-Orange-Trace-Id: 428fe874f806e88e243f73c730103279531ed1e1

{
  "status": 401,
  "code": "UNAUTHENTICATED",
  "message": "Request not authenticated due to missing, invalid, or expired credentials"
}

Client is authenticated correctly but does not have sufficient permissions:

HTTP/1.1 403 Forbidden
X-Orange-Trace-Id: 428fe874f806e88e243f73c730103279531ed1e1

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

Resource not found (it can be an error in the pathsuffix of the URL, or an unknown phone number):

HTTP/1.1 404 Not Found
X-Orange-Trace-Id: 428fe874f806e88e243f73c730103279531ed1e1

{
  "status": 404,
  "code": "NOT_FOUND",
  "message": "The specified resource is not found."
}

The URL of the request is right but it has been made with a method (HTTP verb) not allowed:

HTTP/1.1 405 Method Not Allowed
X-Orange-Trace-Id: 428fe874f806e88e243f73c730103279531ed1e1

{
  "status": 405,
  "code": "METHOD_NOT_ALLOWED",
  "message": "The requested method is not allowed/supported on the target resource."
}

There is another request created for the same MSISDN:

HTTP/1.1 409 Conflict
X-Orange-Trace-Id: 428fe874f806e88e243f73c730103279531ed1e1

{
  "status": 409,
  "code": "CONFLICT",
  "message": "Another request is created for the same MSISDN"
}

Exceeded requests per hour/minute limit:

HTTP/1.1 429 Too Many Requests
X-Orange-Trace-Id: 428fe874f806e88e243f73c730103279531ed1e1

{
  "status": 429,
  "code": "TOO_MANY_REQUESTS",
  "message": "Either out of resource quota or reaching rate limiting."
}

Generic internal server error (also used by default if the error doesn't fit any of the ones detailed in this section):

HTTP/1.1 500 Internal Server Error
X-Orange-Trace-Id: 428fe874f806e88e243f73c730103279531ed1e1

{
  "status": 500,
  "code": "INTERNAL",
  "message": "Server error"
}

Service temporarily unavailable or host not reached:

HTTP/1.1 503 Service Unavailable
X-Orange-Trace-Id: 428fe874f806e88e243f73c730103279531ed1e1

{
  "status": 503,
  "code": "UNAVAILABLE",
  "message": "Service unavailable"
}

Request time limit exceeded:

HTTP/1.1 504 Gateway Timeout
X-Orange-Trace-Id: 428fe874f806e88e243f73c730103279531ed1e1

{
  "status": 504,
  "code": "TIMEOUT",
  "message": "Request timeout exceeded. Try later"
}

This section refers only to SimSwap API error responses. Please keep in mind that you can receive other error responses with a different format when calling our OAuth 2.0 token provider API, because it's a different API.