API response format documentation

[rmccullagh]

Hi,

Is there any documentation on the response format of https://lookup.binlist.net ?

[greendevilapps]

If I understand what you're asking, it should look something like this:

{
  "scheme": "VISA",
  "number": {
    "length": null,
    "prefix": "431940"
  },
  "type": "DEBIT",
  "brand": "",
  "prepaid": false,
  "bank": {
    "name": "BANK OF IRELAND",
    "logo": "",
    "url": "www.bankofireland.com",
    "city": "Dublin",
    "phone": "+353 567757007"
  },
  "country": {
    "alpha2": "IE",
    "name": "Ireland",
    "numeric": "372",
    "latitude": 53,
    "longitude": -8
  }
}

[rmccullagh]

I was able to extract that information from a response. We've noticed it changed over the past week or so. How often do you plan on changing it?

[greendevilapps]

@rmccullagh I'm not the owner, so I'm not sure how often it will change. You will have to ask @tjconcept about that one.

[tjconcept]

@rmccullagh @greendevilapps

Hi both, and sorry for the relatively long period of inactivity.

We are currently doing a major overhaul of the service. As you might know, the user data in here is less than 5 % of the total data, and BIN searching is far from a simple lookup by a prefix, so it will be a couple more days until we're done. Once the new service is live, more options will be available, and you'd wan't to review and maybe upgrade your implementations. From then on, we would keep a backwards compatible API.

Until then, here's an example of a lookup: https://lookup.binlist.net/431940 - that's what you want to use in your application.

I will keep you posted here about or progress.

[pculligan]

@tjconcept Will you be releasing these API changes to production after a schedule warning and preview period, so consuming integrations and services aren't interrupted? Is there a preview/beta system we should be looking at now?

[elvarb]

What do you mean by more options will be available?

And will process of modifying the user data still be the same on github?

[tjconcept]

And will process of modifying the user data still be the same on github?

We do have plans to support an interactive way of filing suggestions, but for the foreseeable future, yes. As mentioned earlier, less than 5 % of the data is sourced from users, most come from authoritative institutions.

What do you mean by more options will be available?

To do a "perfect" (one match) lookup you need to know 8-11 numbers of the card, the length and the scheme. Very few requests to the service is of that nature, so in reality, almost all lookups return 10-50.000 ranges and currently we just pick the first one, which is statistically mostly wrong 😛 The new features include control over how we "merge" (or not) these ranges into the output range. You can still keep the old behaviour though.

[elvarb]

We do have plans to support an interactive way of filing suggestions, but for the foreseeable future, yes. As mentioned earlier, less than 5 % of the data is sourced from users, most come from authoritative institutions.

Good to know, I have a few additions that I would like to add soonish.

To do a "perfect" (one match) lookup you need to know 8-11 numbers of the card, the length and the scheme. Very few requests to the service is of that nature, so in reality, almost all lookups return 10-50.000 ranges and currently we just pick the first one, which is statistically mostly wrong 😛 The new features include control over how we "merge" (or not) these ranges into the output range. You can still keep the old behaviour though.

That is interesting. Do you then mean that to get the absolute card type? The first 6 is enough to identify the issuer bank and country right?

Would it be possible in the future to get all the ranges behind the Bin number? or perhaps a subset of them.

[tjconcept]

That is interesting.

It is. I hope to be able to do some more writing on this.

Do you then mean that to get the absolute card type? The first 6 is enough to identify the issuer bank and country right?

No, that's a common misunderstanding. E.g. Mastercard has plenty of ranges inside the 4 range and Visa has several cards within the 5 range. If you know the scheme (Visa or Mastercard) and the complete length (e.g. 16), you can get pretty close with 6 digits. In relation to that, the ISO standard was recently updated to reflect that the BIN (or really IIN) is now 8 digits.

Would it be possible in the future to get all the ranges behind the Bin number? or perhaps a subset of them.

Yes, that's one of the upcoming features.

[elvarb]

In relation to that, the ISO standard was recently updated to reflect that the BIN (or really IIN) is now 8 digits.

I know that the PCI Council will be allowing 7+4 in the future as a non valid card number, will be interesting to see if they will go with 8+4. Will the first 8 be enough to pin point the exact issuer in most cases?

Yes, that's one of the upcoming features.

Very nice. Are you planning to add a subscription model maybe? ....

[tjconcept]

I know that the PCI Council will be allowing 7+4 in the future as a non valid card number, will be interesting to see if they will go with 8+4. Will the first 8 be enough to pin point the exact issuer in most cases?

I would say so, yes, but it highly depends on the scheme and region.

In terms of getting this information in relation to a sale, the best way to do this is inside the PCI environment with access to the full PAN. That's what we'll be doing at https://paylike.io and then exposing the information on each transaction.

Very nice. Are you planning to add a subscription model maybe? ....

I haven't thought of that yet. So far it's all funded by Paylike.

[BNoohi]

@tjconcept To @pculligan's point, is there a scheduled release day for the upcoming changes? Will there be final specs released before the switch?

[tjconcept]

is there a scheduled release day for the upcoming changes?

No, but expect two weeks. I'm doing this in my weekends so it depends somewhat on my private affairs.

Will there be final specs released before the switch?

Yes. I promise to give at least two weeks notice if changing what works now. Nonetheless there will only be more data and the format might change a bit but simple renames would keep things afloat.

[tjconcept]

Hi again, everyone in this thread,

So, the new version of the API is up, and you can find the documentation and response format at https://binlist.net. What is still lacking there is a note that fields may have a null value if the value could not be determined and that an empty result set will return a 404 HTTP response. I will add that soonish.

In the future more advanced features will be added such as the ability to search with the card number length, which is in some cases required (already in "beta" by appending e.g. ?number[length]=16), getting a list of possible ranges and more.

To get important API updates, I've slashed together this mailing list: http://eepurl.com/cNddUP

[sigmamupi]

Hi @tjconcept

Very nice api and website, when can we expect the ranges api(to get all ranges behind a bin) to be live? Also will it be included as a part of the limited access api.

Thanks