Integration FAQs
Documentation and Changes
How will I get to know if you are making any updates to your APIs? Do you publish change logs?
We generally make only backward compatible changes to our APIs. We shall publish new task types if we need to make a change that breaks backward compatibility.
Support
Who do I contact in case of integration questions?
You can write to eve.support@idfy.com. for any queries.
Authentication
Do I need to authenticate while using the APIs?
Yes, every request must contain headers identifying the API account as specified in the Authentication section in the API reference.
What is an API account?
An API account is an entity used for authentication, authorization and tracking usage of our APIs. It consists of an account-id and api-key.
Can we have multiple API accounts?
Certainly. Please write to eve.support@idfy.com.
When should we use multiple API accounts?
It is recommended to use different API accounts for different parts of your business so you can track usage, revoke access or rotate API keys for one part independently of the others. It is also recommended to use different API accounts for pre-prod and prod environments.
Webhooks
What is a webhook?
A webhook is an HTTP callback: an HTTP POST that occurs when something happens; a simple event-notification via HTTP POST. The spec for our webhooks is defined in the API reference document
When are webhooks called?
Webhooks are called when a task gets completed, either successfully or with an error.
What is the granularity of events sent on a webhook?
Each webhook refers to only one task and is fired on task completion.
Does the server exposing the webhook endpoint need to be located in India?
Not necessary as long as you take explicit consent from the user.
Is the webhook pre-configured or can we specify a webhook url per task?
Our APIs allow only pre-configured webhooks which can be set by emailing us at eve.support@idfy.com.
Can we configure different webhook urls for different services on our side?
We support multiple webhooks. Please write to eve.support@idfy.com.
How do you handle webhook failures?
We retry a webhook failed due to 5xx error with an exponential backoff strategy. We do not retry failures with 4xx errors. We are working on a mechanism where we can notify webhook failures.
Static IPs
My organisation uses a firewall and would like to whitelist your IPs. Can you send me a list of IPs we should whitelist?
Sure, our IPs are available here -
- API endpoint
- 35.200.245.87
- Webhooks and Image Downloads
- 35.200.153.246
- 35.200.227.194
- 35.200.159.98
- 35.200.176.142
- 35.200.250.120
- 35.244.38.241
- 35.244.50.242
Statuses
What does the status “source_down” mean?
This means that one of our partners is down or not responding. For e.g.: If you’re doing a pan_verification task and you see source_down status; it means that we weren’t able to perform the task as NSDL failed to respond or is down for maintenance. Please setup an exponential retry when you see this status.
Response times
What’s the time for a task to be completed?
Tasks take anywhere between less than a second upto 10 seconds depending on the task type.
How many times can we call for the result or for how long?
Ideally, you shouldn’t be polling the APIs after the request. You can create a POST webhook for us, which we can configure on our end and send the results on it post completion. If pooling is the only option you’ve, then you should implement an exponential pooling on our GET endpoint for a period of 2 min; after which the request should expire with a timeout exception.
What will the response times change in case of spikes?
We strive hard to avoid any degradation in response times due to increased load.
Handling Load
How much load can you handle?
Each API account has a limit of 30 requests/sec. You can request for a higher limits by writing to eve.support@idfy.com.
How do you handle unexpected spikes?
Requests above the assigned limit are rejected with 429 TOO MANY REQUESTS HTTP error.
Failures
If something fails, will we also be notified?
Yes, all errors will be posted back to the webhook and also be available on the GET endpoint. However, any scheduled/unscheduled downtime will be communicated via email.