curl PHP
Español

Introduction

doctorSIM´s unlocking API provides full control over the process of requesting, verifying, ordering and receiving unlocking codes and services from over 1,300 devices and 350 global network operators.

API Reference

API Endpoint

$ curl https://api.doctorsim.com

Php librarie for the doctorSIM API is coming soon.

doctorSIM´s unlocking API is a fully-fledged RESTful API.

Requests must be placed via HTTPS. Valid accepted methods are GET, POST and DELETE. All responses are delivered in JSON format.

A Sandbox mode is available whereby no real orders are placed and testing can be peformed. Please refer to the Testing section for specific IMEI test codes.

The API is throttle-limited at 500 requests per minute (regardless of the method used - GET, POST, DELETE). Once this limit is reached, the API will be respond with a 409 HTTP Status Error.

Authentication

Remember to replace your httpdsimkey and httpdsimsecret with your access details.

$ curl https://api.doctorsim.com \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

Php librarie for the doctorSIM API is coming soon.

Authentication is performed with each API call, and done by including DSIM_KEY and DSIM_SECRET as header parameters.

You will find your Sandbox and Production key/secret in your control panel account or from your account manager.

All requests must be under HTTPS. HTTP requests will fail.

Error Handling

doctorSIM uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a request failed, etc.), and codes in the 5xx range indicate an error with doctorSIM´s servers (these are rare).

Not all errors map cleanly onto HTTP response codes, however.

You can check meaning and correlation of error codes here.

Methods

$ curl https://api.doctorsim.com/{action}/{add_param} \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{ ... }
}

Php librarie for the doctorSIM API is coming soon.

All requests must be under HTTPS. HTTP requests will fail.

Some methods require additional parameters in order to apply specific filtering and segmentation of data.

Sample Request:

https://api.doctorsim.com/{action or type of request}/{additional param}/{additional param}/...

Response:

Response will be returned in JSON format with the following structure:

Parameter Description
code integer HTTP status code
status string OK or WRONG_ACCESS or TOO_MANY_REQUESTS or API_ERROR
info string In case of an error, otherwise empty.
res object Object containing result of request.

You can check meaning and correlation of error codes here.

Countries (GET)

$ curl https://api.doctorsim.com/countries \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "id":"country"
  }
}

Possible request status:
{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "1146":"Argentina",
    "1932":"Canada",
    "1937":"China"
  }
}

Php librarie for the doctorSIM API is coming soon.

Request list of available countries.

https://api.doctorsim.com/countries

Response:

Parameter Description
id integer Country id.
country string Country name.

Networks (GET)

$ curl https://api.doctorsim.com/networks \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

$ curl https://api.doctorsim.com/networks/{country_id} \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "country":{
      "id":"network"
    }
  }
}

Possible request status:
{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "34":{
      "1":"Movistar",
      "2":"Vodafone",
      "3":"Orange",
      "4":"Yoigo"
    }
  }
}

Php librarie for the doctorSIM API is coming soon.

Request list of available network providers.

https://api.doctorsim.com/networks

https://api.doctorsim.com/networks/{id_country}

Response:

Parameter Description
id integer Network id.
network string Network name.

Brands (GET)

$ curl https://api.doctorsim.com/brands \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "id":{
      "brand":"brand name",
      "desc":"brand description"
    }
  }
}

Possible request status:
{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "1":{
      "brand":"Alcatel"
      "desc":""
    },
    "6":{
      "brand":"LG",
      "desc":""
    },
    "15":{
      "brand":"Samsung",
      "desc":""
    },
    "29":{
      "brand":"iPhone",
      "desc":""
    }
  }
}

Php librarie for the doctorSIM API is coming soon.

Request list of available device brands.

https://api.doctorsim.com/brands

Response:

Parameter Description
id integer Brand id.
brand string Brand name.
desc string Additional data related to brand.

Devices (GET)

$ curl https://api.doctorsim.com/devices/{brand_id} \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

$ curl https://api.doctorsim.com/devices/{brand_id}/{device_id} \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "brand_id":{
      "id":{
        "name":"device name",
        "img":"device image URL",
        "desc":"device description"
      }
    }
  }
}

Possible request status:
{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "29":{
      "15910":{
        "name":"iPhone 6",
        "img":"https://img1.doctorsim.com/img/term/iphone_6.png",
        "desc":"<p>The<strong> iPhone 6</strong> is Apple’s sixth generation Smartphone succeeding the iPhone 5S. Launched in September 2014, along with the larger-sized iPhone 6 Plus, the iPhone 6 quickly became a huge hit among Apple enthusiasts. With its new Retina HD 4.7-inch screen, the iPhone 6 is larger than previous generations. Other features include a faster A8 64-bit processor, an upgraded camera and support for the new Apple Pay mobile payments service.</p>
    <p>But the best thing about the iPhone 6 is that you can unlock it fast and safe, with the quality you would expect with a phone of this magnitude. At <strong>doctorSIM</strong>, the price will be unbeatable, you will receive expert customer support throughout the service and the speed at which we unlock your iPhone will be as fast as its processor!</p>
    <p>The phone manufacturer’s warranty will remain intact and the iPhone never has to leave your side. Your iPhone 6 will be unlocked via e-mail and iTunes.</p>
    <p>Unlocking your iPhone 6 with doctorSIM is <strong>100% legal</strong>, <strong>permanent</strong> and will not damage the iPhone in any way. We offer a full guarantee and will issue a full refund if for any reason under our responsibility are unable to unlock your iPhone.</p>"
      }
    }
  }
}

Php librarie for the doctorSIM API is coming soon.

Request list of available devices by brand.

https://api.doctorsim.com/devices/{brand_id}

https://api.doctorsim.com/devices/{brand_id}/{device_id}

Response:

Parameter Description
id integer Device id.
name string Device name.
img string Device image URL.
desc string Device description.

Tools (GET)

$ curl https://api.doctorsim.com/tools/{device_id}/{network_id} \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "tools":[
      {
        "name":"tool name",
        "desc":"tool description",
        "service_name":"service name",
        "service_desc":"service description",
        "guaranteed_time":{
          "min":"min time value",
          "max":"max time value",
          "type":"time type"
        },
        "average_time":"average time",
        "sn":"sn",
        "prd":"prd",
        "pin":"pin",
        "mep":"mep",
        "sro":"sro",
        "id_tool":"associated tool id",
        "success_ratio":"tool success ratio",
        "tool_type":"tool type",
        "custom":"custom",
        "price":"tool cost"
      },
      { ... }
    ]
  }
}

Possible request status:
{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "tools":[
      {
        "name":"Samsung - USA Standard Service",
        "desc":"Our Standard Service scans LOCAL databases and is our low-cost solution with a very high success rate.If your unlocking code is unavailable after scanning LOCAL databases, we will issue you a full refund so you can use our Premium Service which scans databases located WORLDWIDE and guarantees the availability of your unlocking code. IMPORTANT! If your Samsung phone has received technical support or you have tried to unlock it without success in the past, make your request directly through our Premium Service. Valid for all Samsung models.",
        "service_name":"Standard Service",
        "service_desc":"Your low-cost solution. Success rate: 41%. Full refund if the unlocking code is unavailable.",
        "guaranteed_time":{
          "min":"1",
          "max":"6",
          "type":"days"
        },
        "average_time":"2 days, 8 hours",
        "sn":"false",
        "prd":"false",
        "pin":"false",
        "mep":"false",
        "sro":"false",
        "id_tool":"452787",
        "success_ratio":"0.72",
        "tool_type":"imei",
        "custom":"",
        "price":24.95
      }
    ]
  }
}

Php librarie for the doctorSIM API is coming soon.

Request list of available unlocking services by device/operator combination.

https://api.doctorsim.com/tools/{device_id}/{network_id}

Response:

Parameter Description
tools array The different services that can be used to unlock the device.
name string Tool name.
desc string Tool description.
service_name string Service name.
service_desc string Service description.
guaranteed_time object Guaranteed delivery time object.
min integer Minimum guaranteed time value.
max integer Maximum guaranteed time value.
type string Unit of guaranteed time for min/max delivery times (minutes, days, weeks, ...).
average_time string Average delivery time.
sn string Flag to indicate where this service requires Serial Number parameter, also known as KBH or Provider ID (Usually for Alcatel). Posible values: true or false.
prd string Flag to indicate where this service requires PRD parameter(Usually for Blackberry). Posible values: true or false.
pin string Flag to indicate where this service requires PIN parameter(Phone PIN). Posible values: true or false.
mep string Flag to indicate where this service requires MEP parameter(Usually for Blackberry). Posible values: true or false.
sro string Flag to indicate where this service requires SRO parameter(Usually for Alcatel). Posible values: true or false.
id_tool integer Tool id used on new invoices.
success_ratio decimal Success rate of the unlocking service. *
tool_type string Type of Service. Usually imei, file, usb, … (Additional info in custom field).
custom object Additional data for special parameters. Object format with one or more values in key/pair style.
price number (float, decimal, ...) Cost in credits for use of this tool.

Create Order (POST)

$ curl https://api.doctorsim.com/create_order/{device_id}/{network_id}/{imei}/{tool_id} \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "id_ticket":"new invoice id"
  }
}

Possible request status:
{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "id_ticket":"1509403"
  }
}

Php librarie for the doctorSIM API is coming soon.

Request unlocking service via IMEI for a specific device.

https://api.doctorsim.com/create_order/{device_id}/{network_id}/{imei}/{tool_id}

imei: 011950004980028SN5678G-33574

(SN followed by a string of 4 or 5 characters, followed by a hyphen, followed by a string of 5 to 7 characters. Without spaces.)

imei: 011950004980028PRD12345678

(PRD followed by 8 integers without spaces)

imei: 011950004980028PIN21FB6301

(PIN followed by 8 characters without spaces)

imei: 011950004980028MEP-12345-678

(MEP followed by a hyphen, followed by 5 integers, followed by a hyphen, followed by 3 integers. Without spaces)

imei: 011950004980028SROXM66NA40

(SRO followed by a capital X, followed by 7 to 11 integers without spaces)

Response:

Parameter Description
id_ticket integer New invoice id.

Check Order Status (GET)

$ curl https://api.doctorsim.com/check_order_status/{ticket_id} \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "id_ticket":{
      "id_device":"device id",
      "id_network":"network id",
      "imei":"imei",
      "creation_datetime":"creation date/time",
      "status":"status",
      "ok_sent":"ok_sent"
    }
  }
}

Possible request status:
{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "1509403":{
      "id_device":"1697",
      "id_network":"3",
      "imei":"011950004980028",
      "creation_datetime":"2011-10-04 15:29:18",
      "status":"available",
      "ok_sent":"true"
    }
  }
}

Php librarie for the doctorSIM API is coming soon.

Get status of all orders associated with your account.

https://api.doctorsim.com/check_order_status/{ticket_id}

Response:

Parameter Description
id_device integer Device id.
id_network integer Network id.
imei string IMEI of requested device.
creation_datetime string Date when request is received.
status string Order Status: check following table.
ok_sent string Flag that indicates whether unlock instructions are ready. Posible values: true or false.

Possible order status:

Parameter Description
open Request has been received.
pending Request is being processed and awaiting delivery of code and instructions.
available Unlocking instructions are available and ready.
canceled Request has been successfully cancelled (and refunded).
notavailable Request for unlock code failed since no code was available (and request has been refunded).
error An error occurred during the request process.

Update Order (POST)

$ curl https://api.doctorsim.com/update_order/{ticket_id} \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"
  -d force={value}

{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "id_ticket":{
      "id_device":"device id",
      "id_network":"network id",
      "imei":"imei",
      "creation_datetime":"creation date/time",
      "status":"status",
      "ok_sent":"ok_sent"
    }
  }
}

Possible request status:
{
  "code":"200",
  "status":"OK",
  "info":"",
  "res":{
    "1509403":{
      "id_device":"1697",
      "id_network":"3",
      "imei":"011950004980028",
      "creation_datetime":"2011-10-04 15:29:18",
      "status":"available",
      "ok_sent":"1"
    }
  }
}

Php librarie for the doctorSIM API is coming soon.

Updates a request based on provided parameters.

https://api.doctorsim.com/update_order/{ticket_id}

Arguments:

Argument Description
force string Values permitted:
- nowait: Passing this parameter will override the specified guaranteed_time tool parameters and force the order to be ready. When checked, the order will return instructions or non-availability

Response:

Parameter Description
id_device integer Device id.
id_network integer Network id.
imei string IMEI of requested device.
creation_datetime string Date when request is received.
status string The status of the request. Check under Possible order status the Status method.
ok_sent string Flag that indicates whether unlock instructions are ready. Posible values: true or false.

Cancel Order (DELETE)

$ curl https://api.doctorsim.com/cancel_order/{ticket_id} \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

{
  "status":"OK",
  "info":"",
  "res":{
    "id_ticket":{
      "status":"order status"
    }
  }
}

Possible request status:
{
  "status":"OK",
  "info":"",
  "res":{
    "1509403":{
      "status":"canceled"
    }
  }
}


Php librarie for the doctorSIM API is coming soon.

Placed orders can be cancelled during the 10 minute window immediately after the order has been placed. This is a safety mechanism that enables rapid cancellation of an order due to incorrect data before it is billed and processed.

Some services such as IMEI Checks (blacklisted check, locked, operator, icloud) are not bound by this window and are processed immediately.

If a cancelation request is tried after the 10 minute window it will be met with the specific error.

https://api.doctorsim.com/cancel_order/{ticket_id}

Response:

Parameter Description
status string Ticket status.

Retrieve Order Instructions (GET)

$ curl https://api.doctorsim.com/retrieve_order_instructions/{ticket_id} \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

{
  "status":"OK",
  "info":"",
  "res":{
    "id_ticket":{
      "howto":"The message explaining how to unlock the phone."
    }
  }
  }
}

Possible request status:
{
  "status":"OK",
  "info":"",
  "res":{
    "id_ticket":{
      "howto":"IMEI number: 123456789876543
        Model: Nokia 5230
        Network Provider: Movistar

        To unlock your phone please follow these simple steps:

        1. Insert an accepted SIM card (from network provider Movistar) and turn on the phone. If the phone prompts you to enter the SIM card PIN, do so and press OK.
        (For more modern phones you will not need the SIM card).

        2. Enter your unlock code: #pw+123456+1#

        To enter p, press the * (star) key 3 times.
        To enter w, press the * (star) key 4 times.
        To enter +, press the * (star) key 2 twice.

        NOTE: If your phone has a full QWERTY keyboard (with letters) type the letters and the + sign directly.

        When you enter the last pound sign (#) the phone will display one of the following messages:

        "Phone Restriction Off" or "SIM Restriction Off" ---> The phone is now unlocked and will restart.

        "Impossible to Undo SIM Restriction" or "Not Allowed" --> This means the unlock code is valid, but the phone was previously out of unlocking attempts. You can, however, reset the counter following this tutorial: http://bit.ly/Contador_Nokia.

        Please note that you only have 3 attempts to unlock your phone."
       }
     }
  }
}


Php librarie for the doctorSIM API is coming soon.

Obtain specific instructions for a ready available order.

Instructions are specific to brand, device and sometimes operator.

https://api.doctorsim.com/retrieve_order_instructions/{ticket_id}

Response:

Parameter Description
howto string The unlock instructions for the request.

Error Handling

There are 2 types of errors to handle:

Returned directly in the HTTP response header depending on the issuing error.

Indicated in the info field.

{"status":"API_ERROR","info":"The error message","res":{ ... }}

HTTP status code summary

Error Code Meaning
200 OK: – Everything worked as expected.
400 Bad Request: – The request was unacceptable, often due to missing a required parameter.
401 Unauthorized: – No valid API key provided.
404 Not Found: – The requested resource doesn´t exist.
405 Method not allowed: – A request method is not supported for the requested resource.
429 Too Many Requests: – Too many requests hit the API too quickly.
500 Server Error: – Something went wrong on doctorSIM's end. (These are rare.)

doctorSIM API Errors

Error Code Meaning
WRONG_ACCESS Wrong Access Credentials.
TOO_MANY_REQUESTS Too many connections where made to the server. Check the API Reference for API limit.
API_ERROR An error ocurred with the specific operation. Review info field for more information.

Testing

All methods defined in the Methods section are active in SandBox mode.

Below are two IMEI numbers which create the different statuses of a request.

IMEI Status Created
123456789876543 The request is available and delivers the unlock instructions.
355710060480006 The request is notavailable and issues a refund for the request.

API Best Practices

For a streamlined and optimal flow of requests and orders, doctorSIM suggests the following best practices.

General

Implementing API Calls and Caching

At the time of development, when implementing calls to the various methods, we recommend you store locally (cache) the following methods, with the indicated refresh time. I.e, you should call these methods every X hours to ensure fresh information before populating your dropdowns.

The following request can be performed once a day and stored locally:

Building your Order Page

When building your order page, we recommend your information request flow go as follows:

  1. Country --> Network
  2. Brand --> Device
  3. With Network ID and Device ID, you must call Tools to display Price, Delivery Times, and Service Options.

Tools

Some combinations of Tools requests for various Device ID and Network ID can return more than one service. For example, AT&T (5815) and Apple iPhone 5 (15429) https://api.doctorsim.com/tools/15429/5815 (POST). We recommend you display all options on your order page, but you can exclude any based on the success ratio parameter returned (value from 0 to 1).

Some tool services require you request additional information from the user such as SN o Provider Number (LG, Alcatel, BB, etc). This is indicated in the response returned.

When displaying service options to the customer, besides price, we recommend you at least always display:

Delivery Times are broken down into to metrics: Average Delivery Time and Guaranteed Delivery Time.

When displaying delivery times to customer, we recommend you market Average Delivery Times, but ensure that the guaranteed Delivery Time is the enforcing parameter.

Placing and Order and Checking Status

When placing an order via the Order POST call, you will receive a doctorSIM order id which can be used to further check the status, cancel or retrieve instructions.

Due to the number of checks and verifications that must be made internally, the response from the order request can take up to 30 seconds.

Once you place the order and have your doctorSIM order id, we recommend you check back for availability of instructions based on the guaranteed delivery time type for the service requested.

Guaranteed Delivery Time (tools -> time -> type):

Once an order is available via the status request, an additional call to instructions must be made to retrieve and send instructions and/or code to the client.

Cancelling an Order

Unless otherwise agreed, orders can be cancelled during the 10-minute window following the placement of the order using the cancel_order. After this 10 minute window, orders are no longer cancellable. If you wish to eliminate this 10 minute window for certain instant delivery services, please get in touch with us.

curl PHP