Understanding API Response

Good to know: We are expecting frequent changes to API response, and each change would be backward compatible.

Response field specifications

Top-level field

field name	data type	note
status	string	possible status [ success, failed]
user_request_id	string	user request identifier
email	string	verification request for email

Response level fields

field name	data type	note
isit_common_email_id	boolean	check if email belong to common alias such as support@, admin@, no-reply@
is_email_domain_disposable	boolean	is the domain used in email belongs to any temporary email service providers
domain_registration_information	nested json object	domain registration information is available using whois for old TLDs and RDAP for the latest TLDs

Response level field : can_domain_send_or_recieve_mail

"can_domain_send_or_recieve_mail":{
         "can_domain_send_or_receive_email":true,
         "mx_setups":[
            "0 arcesium-com.mail.protection.outlook.com."
         ]
  }

field nam	data type	note
can_domain_send_or_receive_email	boolean	True if MX record present else false
mx_setups	List[String]	List of MX records

Response level field: is_email_on_source_verified

"is_email_on_source_verified": {
      "message": "",
      "smtp_status_code": 250,
      "status": "yes",
      "catch_all": false
    }

Field interpretation

field	desc	possible values	nullable
status	the result of SMTP verification	[yes, no, unverifiable]	No
catch_all	A catch-all domain will accept all mail sent to any address at the domain and return a 250 OK	boolean	No
smtp_status_code	SMTP replies generated for the RCPT command https://www.greenend.org.uk/rjk/tech/smtpreplies.html#RCPT	integer values	Yes, the default is 0 0 implies smtp status not applicable
message	provide additional information in case of status is no or unverifiable	string (max 300 char)	Yes, the default is empty

Expected behavior

email	status	catch_all	smtp_status_code	message
[email protected]	yes	false	250
[email protected]	no	false	550
[email protected]	no	false	550	"Blocked by mail server for b'5.4.1 Recipient address rejected: Access denied. AS(201806281) [SN1NAM02FT0057.eop-nam02.prod.protection.outlook.com]'
[email protected]	unverifiable	true	250	Unverifiable due to catch-all
	yes	false	522
	yes	false	251

Common error

message	status	desc
Internal error: smtp request is taking more time	unverifiable	SMTP request exceed timeout period (i.e. 1 sec)
Internal error: not able to process the request	unverifiable	Due to technical error

Response level field: input_name_to_email_matching

"input_name_to_email_matching":{
         "match":"yes",
         "rule":"Rule F.L"
 }

field name	data type	note
match	string	possible value: ["yes", "not sure"]
rule	string	Matching found as per rule Refer additional information page for details

Response level field: mca_information

"mca_information":[
         {
            "cin":"U01403PN2015PTC153736",
            "company_name":"KHANDALA TALUKA FARMERS PRODUCER COMPANY LIMITED",
            "company_status":"Strike Off",
            "date_of_incorporation":"15 January 2015",
            "directors":[
               {
                  "din":"07014914",
                  "name":"SURYAKANT BAPU DHANAVADE",
                  "designation":"Director",
                  "appointment_start_date":"15 January 2015", 
	          "appointment_end_date":"" 
               },
               {
                  "din":"07065317",
                  "name":"NILESH VISHNU BHOSALE",
                  "designation":"Director",
                  "appointment_start_date":"15 January 2015",
		  "appointment_end_date":"15 January 2020"
               }
            ]
        }
]               

mca_information

field name	data type	note
cin	String
company_name	String
date_of_incorporation	String	Date format is DD MMM YYY
directors	List of object	Refer next table for more details
company_status	String	Refer additional information page for details

directors

field name	data type	note
din	String
name	String
designation	String	Fixed value i.e director
appointment_start_date	String	Date format is DD MMM YYY
appointment_end_date	String	Date format is DD MMM YYY

Response level field: matching_directors

Refer above director table

How MCA information and matching director search works

API Request Parameter	mca_information block	matching_directors
Only CIN provided e.g CIN=U01403PN2015PTC153736	Get company information for a given CIN	Get all the directors from MCA director master dataset matching first and last name provided in request
Only DIN provided e.g DIN=7065317	Get all the companies in which director is part of.	Get director by matching DIN provided in request
Both CIN and DIN provided e.g CIN=U01403PN2015PTC153736 DIN=7065317	Get company information for a given CIN	Get director by matching DIN provided in request