ID Best Practices

Tips for building a robust integration

While we strive to provide 100% uptime, not all factors are in our control. We rely on numerous systems in a variety of countries to bring you ID information, and their reliability is out of our hands. We work with these entities as much as possible to improve uptime, but it is important to ensure that your system can handle the inherent uncertainty surrounding obtaining ID information for your users.

When an ID provider is down we will always provide a response with the result code 1015.

A 1015 result code on an id lookup may mean the provider is down, or it could also be intermittent during high traffic. Not all ID providers are able to handle the same traffic that Smile Identity or your systems can. In most cases, an hour or two later, that ID lookup will probably succeed. It is important to account for this in your UI and you may want to provide feedback to the user that the action they are taking may be delayed.

There is never a charge for an ID lookup where the provider is down.

The next step to handling this situation robustly is to resend the request for an ID lookup later. We recommend implementing a cron job to resend the ID lookup request if this is critical information to have for your use case. You can utilize our ID Status API as a part of that cron job to check is the ID authority is back up. Is there an API I can check to check the status of an ID authority?

Please also utilize the ID API Status page in your Smile Identity dashboard for a visual representation of the uptime status for out ID providers.

Not all ID providers can handle large volumes of concurrent requests

During times of peak traffic, some providers will be unable to respond to all ID lookup requests. Therefore, if you are implementing a cron job to retry ID lookups, or if you are trying to run a large batch, or backlog, of IDs through our system it is important to limit the number of concurrent requests. We recommend using no more than 5 concurrent requests at a time. Cron jobs or backlog-clearing scripts will also have the highest probability of success if they are run at night. We have observed that our peak traffic is generally between 10AM and 6PM WAT.

Ensure the correct values for Country and ID Type are being sent

The most common problem in otherwise successful integrations is non-conforming strings for country and id_type. The accepted values are all listed in Supported ID Types. Also note that different types of IDs require different parameters to be sent. Before enabling a user to check an ID type, check to see that you are collecting all the required parameters for that type of ID. If your UI includes the ability to select unsupported ID types, ensure that you are not requesting ID lookups in our system with them (i.e. the id_info should have "entered"="false"). An enroll with ID Number sent with a non-conforming country or ID type will be rejected by our system because we are unable to lookup that ID.

Validate the ID number formatting before sending a job

The most common reason that an ID authority will report the ID does not exist is because the user did not enter their perfectly valid ID number correctly. By validating the format of the ID number on the client, you can greatly improve your user's experience. See ID Number Regex Examples for examples of how to validate ID number formats.

Always send a unique user_id and job_id

We are only able to hold requests open for a maximum of 30 seconds. At times our ID providers may have latency longer than that period of time. While we manage this for you in most scenarios, when sending a request directly to our ID API (job type 5), you may receive a 504 "gateway timeout" response from our server. If you receive this error, it doesn't mean we won't be able to obtain a response, just that it is taking longer than we are able to sustain a connection. When this occurs you will still be able to get the result of that id check by polling our Job Status endpoint, provided the job was sent with a unique user_id and job_id in the initial request.

Filter duplicate ID numbers

We recognize that there are legitimate reasons why a user may need multiple accounts using the same credentials for KYC. As a result, we allow your users to register a selfie with an ID Number multiple times. However, each time we make a call to an ID provider you are charged. Especially during periods of heavy marketing and promotion of your product you will see some unscrupulous actors attempt to take advantage by opening multiple accounts, but continuing to use the same ID credentials each time. If this is not behavior you want in your app, you should validate whether or not you already have a user that has submitted a particular ID number for a given id type/country. By validating whether or not this is actually a new user opening an account, you are able to save money by not sending Smile Identity requests to perform KYC.