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.

IMEI Check (POST)

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

$ curl https://api.doctorsim.com/imeicheck/{imei}/{hash} \
  -H "DSIM_KEY: httpdsimkey" \
  -H "DSIM_SECRET: httpdsimsecret"

{
  "status":"OK",
  "info":"",
  "res":{
    "data":{
      "imei":"requested imei",
      "tac":"imei decomposition",
      "brandname":"detected brand name",
      "marketingname":"device marketing name",
      "modelname":"device name",
      "devicetype":"device type",
      "img":"device image url",
      "lang":"result language"
    },
    "error":[
      {
        "code":"error code ID",
        "txt":"error code description  "
      }
    ],
    "result":{
      "blackliststatus":"indicates if the device is blacklisted",
      "imeihistory":[
        {
          "imei":"requested imei",
          "action":"the performed action by company network",
          "date":"date of the performed action",
          "by":"company network",
          "country":"company country"
        }
      ],
      "lists":{
        "black":[
          {
            "name":"country name",
            "opers":[
              {
                "txt":"network and country",
                "status":"blacklist status"
              }
            ]
          }
        ],
        "white":[
          {
            "name":"country name",
            "opers":[
              {
                "txt":"network and country",
                "status":"whitelist status"
              }
            ]
          }
        ]
      },
      "url_report":"pdf download url"
    },
    "type_pay":{
      "type":"payment type ID",
      "desc":"payment type description"
    },
    "extra_info":[
      {
        "type":"object type",
        "txt":"object txt",
        "url":"object url"
      }
    ]
  }
}

Possible request status: (Blacklist)
{
  "status":"OK",
  "info":"",
  "res":{
    "data":{
      "imei":"353047098598802",
      "tac":"TAC:3530470 SN:98598802",
      "brandname":"IPHONE",
      "marketingname":"Apple iPhone X (A1901)",
      "modelname":"iPhone X (A1901)",
      "devicetype":"Smartphone",
      "img":"https://img2.doctorsim.com/img/term/iphone_x.png",
      "lang":"es"
    },
    "error":[],
    "result":{
      "blackliststatus":true,
      "imeihistory":[
        {
          "imei":"353047098598802",
          "action":"Black Insert",
          "date":"2018-10-17 17:59:19",
          "by":"TELCEL MEXICO",
          "country":"Mexico"
        }
      ],
      "lists":{
        "black":[
          {
            "name":"Mexico",
            "opers":[
              {
                "txt":"Mexico-Iusacell",
                "status":"0"
              },
              {
                "txt":"Mexico-Movistar",
                "status":"0"
              },
            ]
          }
        ],
        "white":[
          {
            "name":"Alemania",
            "opers":[
              {
                "txt":"Alemania-E-Plus",
                "status":"2"
              },
              {
                "txt":"Alemania-O2",
                "status":"1"
              }
            ]
          }
        ]
      },
      "url_report":"https://www.doctorsim.com/imei_report/zl6fpnyqkewa-1milgoxbj7cu"
    },
    "type_pay":{
      "type":"F",
      "desc":"free"
    },
    "extra_info":[]
  }
}

Possible request status: (Whitelist)

{
  "status":"OK",
  "info":"",
  "res":{
    "data":{
      "imei":"359405085972766",
      "tac":"TAC:3594050 SN:85972766",
      "brandname":"IPHONE",
      "marketingname":"Apple iPhone X (A1901)",
      "modelname":"iPhone X (A1901)",
      "devicetype":"Smartphone",
      "img":"https://img2.doctorsim.com/img/term/iphone_x.png",
      "lang":"es"
    },
    "error":[],
    "result":{
      "blackliststatus":false,
      "imeihistory":[],
      "lists":{
        "black":[],
        "white":[
          {
            "name":"Alemania",
            "opers":[
              {
                "txt":"Alemania-E-Plus",
                "status":"2"
              },
              {
                "txt":"Alemania-O2",
                "status":"1"
              }
            ]
          }
        ]
      },
      "url_report":"https://www.doctorsim.com/imei_report/zdt2eu4jkzeg-1mzlvvrqowrc"
    },
    "type_pay":{
      "type":"F",
      "desc":"free"
    },
    "extra_info":[
      {
        "type":"button",
        "txt":"Libera tu iPhone",
        "url":"https://www.doctorsim.com/liberar-movil/iphone/iphone-x/liberar/"
      },
      {
        "type":"button",
        "txt":"Descubre si tu iPhone está Libre",
        "url":"https://www.doctorsim.com/comprobar-movil-imei/chequeo-estado-libre-bloqueado/solicitar/"
      }
    ]
  }
}

Possible request status: (No Free)

{
  "status":"OK",
  "info":"",
  "res":{
    "data":{
      "imei":"359405085972766",
      "tac":"TAC:3594050 SN:85972766",
      "brandname":"IPHONE",
      "marketingname":"Apple iPhone X (A1901)",
      "modelname":"iPhone X (A1901)",
      "devicetype":"Smartphone",
      "img":"https://img2.doctorsim.com/img/term/iphone_x.png",
      "lang":"es"
    },
    "error":[],
    "result":{},
    "type_pay":{
      "type":"P",
      "desc":"pay"
    },
    "extra_info":[]
  }
}

Possible request status: (Error)

{
  "status":"OK",
  "info":"",
  "res":{
    "data":{
      "imei":"123456789876543",
      "tac":"TAC:1234567 SN:89876543",
      "brandname":"NA",
      "marketingname":"NA",
      "modelname":"NA",
      "devicetype":"NA",
      "img":"https://img3.doctorsim.com/img/term/default.png",
      "lang":"es"
    },
    "error":[
      {
        "code":404,
        "txt":"Lo sentimos, el IMEI facilitado no se corresponde con ningún modelo existente."
      }
    ],
    "result":{},
    "type_pay":{
      "type":"P",
      "desc":"pay"
    },
    "extra_info":[]
  }
}


Php librarie for the doctorSIM API is coming soon.

Solicitar un chequeo de imei.

https://api.doctorsim.com/imeicheck/{imei}

https://api.doctorsim.com/imeicheck/{imei}/{hash}

Arguments:

Argument Description
imei string El IMEI para el que realizar el chequeo.
hash string

Este parámetro solo podemos omitirlo en modo sandbox, sino recibiremos un error.

Se trata de un valor encriptado dónde agruparemos los distintos argumentos que el método espera recibir.

La forma de agrupar los argumentos y la encriptación es la que sigue:

encrypt_function(arg1####arg2####arg3)

Response:

Parameter Description
data object Los datos del dispositivo identificado.
imei string El IMEI solicitado.
tac string Descomposición técnica del IMEI.
brandname string El nombre de la marca del dispositivo.
marketingname string El nombre del modelo del dispositivo.
modelname string El nombre técnico del modelo del dispositivo.
devicetype string El tipo de dispositivo.
img string La imagen del dispositivo.
lang string Idioma de la respuesta.
error array Array con los posibles errores derivados del chequeo del IMEI.
code string Identificador del error.
txt string Descripción del error a mostrar al usuario.
result object Objeto que contiene los resultados obtenidos de comprobar si el IMEI está reportado o no.
blackliststatus boolean Indica si el IMEI está reportado (TRUE) o no (FALSE)
imeihistory array En caso de estar el IMEI reportado, este Array contiene un histórico, con un máximo de 10 registros, de las acciones llevadas a cabo por los distintos operadores
imei string El IMEI para el que se lleva a cabo la acción descrita.
action string La acción llevada a cabo sobre el IMEI.
date string La fecha en la que se lleva a cabo la acción.
by string Operador que lleva a cabo la acción.
country string País del operador que lleva a cabo la acción.
lists object Objeto que contiene los listados de los operadores dónde se podrá usar (white) o no (black) el dispositivo.
black array

Array con los países de los operadores dónde el dispositivo no podrá ser utilizado.

Ordenado por país de forma descendente.
name string El nombre del país.
opers array Array con los operadores dónde el dispositivo no puede ser usado.
txt string Nombre del operador
status string

El estado de blacklist.

0: siempre mostraremos este valor que indica que el dispositivo no puede ser usado con el operador indicado.

white array

Array con los países de los operadores dónde poder usar el dispositivo.

Ordenado por país de forma descendente.
name string El nombre del país.
opers array Array con los operadores dónde poder usar el dispositivo.
txt string Nombre del operador
status string

El estado de whitelist:

  • 1: se puede usar (en los informes de doctorSIM, color verde).
  • 2: status no confirmado por la GSMA, pero el dispositivo debería poder ser usado (en los informes de doctorSIM, color gris).
url_report string La URL para descargar el informe en formato PDF.
type_pay object Objeto que indica qué tipo de pago debemos ofrecerle al cliente.
type string

Identificador del tipo de pago:

  • F: el pedido es gratis, no le cobramos nada al usuario y mostramos todos los datos disponibles.
  • P: el pedido es de pago, mostramos solamente la información del dispositivo (data) y le ofrecemos pagar por el informe completo.
desc string Descripción adicional asociada al tipo de pago.
extra_info array Array de objetos a pintar en secciones especificas.
type string

El tipo de objeto

button: define el pintado de un botón con acción de apertura de la URL asociada.
txt string El texto asociado al objeto para comunicar al usuario la acción del objeto.
url string La URL asociada a la accion del objeto

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.

Pruebas Liberaciones

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.

Pruebas ImeiCheck

IMEI Status Created
353047098598802 La solicitud nos devuelve un informe Blacklist gratuito.
359405085972766 La solicitud nos devuelve un informe Whitelist (no reportado) gratuito.
123456789876543 La solicitud nos devuelve solo datos de teléfono (no reconocido) y fuerza pedir pago.
123456789987654 La solicitud nos devuelve un error.

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