Register Consent API

AI Tools

The Register Consent API is the first mandatory step before performing any KYC verification or personal data processing through the Attestr Platform

Before initiating a verification request, the client (acting as the Data Fiduciary) must first obtain lawful and explicit consent from the end user (the Data Principal) for the intended data processing activity. Once the consent has been collected, the client is required to register the consent with Attestr (acting as the Data Processor) using this API.

Upon successful registration, Attestr generates a unique consent id that serves as a reference for the consent transaction. This consent id must subsequently be passed in all related verification and KYC API requests to establish a valid consent trail and enable compliant data processing on the Attestr platform.

The Register Consent API helps ensure:

Consent traceability and auditability
Regulatory compliance for personal data processing
Proper linkage between consent records and verification requests
Secure and accountable KYC workflows

Every consent registration is associated with specific:

Data categories
Data types
Purpose of processing
Verification services requested
Consent validity and metadata

Clients must ensure that the consent obtained from the Data Principal is lawful, informed, specific, and compliant with applicable data protection regulations before invoking this API.

API Definition

Request

Type	URL	Version
POST	https://api.attestr.com/api/`{version`/public/consent/register	Use "v3" for DPDA compliant version

Request Body Parameters

Type	Name	Description	Optional (default)	Min Version
String	consentPurpose	Purpose for which consent has been obtained from the Data Principal. Allowed values are - kyc_verification background_verification Refer to Consent Purpose to read more.	Required	v3
String	consentPurposeDesc	Optional text describing the consent purpose in detail	Optional	v3
Array<Service Object>	services	List of services/products for which this consent is intended to be used for the specified purpose. Depending on the services provided, appropriate data categories are required to be passed in the data categories input below. Refer Service object definition below.	Required	v3
Array <DataCategory Object>	consentDataCategories	List of data categories and associated data types are needed for the specified input services. See Data Category Object definition below. Refer to Consent Data Categories to know more.	Required	v3
String	consentType	Allowed values are - single_use multi_use Refer to Consent Type to read more.	Required	v3
String	consentMode	Allowed values are - checkbox email_otp mobile_otp digilocker ivr physical_form offline Refer to Consent Mode to read more.	Required	v3
String	consentModeDesc	Optional text describing how the consent was collected	Optional	v3
String	consentTimestamp	ISO Date and timestamp of the time when consent was obtained from the Data Principal. Eg. "2026-05-22T00:00:00+0000" Refer to Consent Validity to know more.	Required	v3
String	consentValidFrom	ISO Timestamp from which the consent becomes valid for processing operations. Eg. "2026-05-22T00:00:00+0000" Refer to Consent Validity to know more.	Required	v3
String	consentValidTill	ISO Timestamp until which the consent remains valid for processing operations. Refer to Consent Validity to know more.	Required	v3
String	consentReferenceId	Unique client internal reference ID assigned to the consent. Refer to Consent Reference ID to know more.	Required	v3
String	consentPrincipalUserId	Data Principal user ID as assigned by client in its internal systems. Refer to Consent Principal User ID to know more.	Optional	v3
String	clientPrivacyPolicyUrl	Link to client's privacy policy. Refer to Client Privacy Policy URL and Version	Optional	v3
String	clientPrivacyPolicyVersion	Version of the client's privacy policy. Refer to Client Privacy Policy URL and Version	Optional	v3
Boolean	clientDeclaration	Must be declared as True always. Refer to Client Declaration to know more.	Required	v3
String	clientObtainedBy	ID of the client's internal user, app, system through which the consent was obtained. Refer to Client Obtained By to read more.	Optional	v3
Array <String>	consentOperations	List of allowed data processing operations for the consent. Allowed values are -VERIFY FETCH EXPORT STORE SHARE REPORT Multiple values can be provided Refer to Consent Operations to read more.	Required	v3
Boolean	webhook	Boolean flag indicating if webhooks must be triggered for consent lifecycle events. Refer to Webhooks to know more.	Optional	v3

Service Object Definition

Type	Name	Description	Optional (default)	Min Version	Max Version
String	service	Provide the Service code. Attestr assigns a unique service code to each product and service it offers. For example, the service code for Bank Account Verification is `BANK_ACC`. Please refer to the relevant product documentation to identify the correct service code for the service you intend to use.	Required	v3
Object	options	Reserved for future use. Used for specifying service specific options which helps to decide the associated data categories.	Optional	v3

Data Category Object Definition

Type	Key	Description	Min Version	Max Version
String	category	Data category for the provided service	v3
Array<String>	values	Associated data types as mapped to the provided service	v3

Request Header Parameters

Type	Name	Value / Description	Optional	Min Version	Max Version
String	Content-Type	application/json	Required	v3
String	Authorization	Basic `{authToken}`	Required	v3

Info

If you do not have the authentication token, please refer to Register App to generate one.

Sample Request Payload

{ "consentPurpose": "kyc_verification", "services": [{ "service": "BANK_ACC" }], "consentTimestamp": "2026-05-22T00:00:00+0000", "consentMode": "email_otp", "consentType": "multi_use", "consentValidFrom": "2026-05-23T12:05:00+0000", "consentValidTill": "2026-05-23T12:07:00+0000", "consentReferenceId": "12341", "consentPrincipalUserId": "USER#1234", "clientDeclaration": true, "consentOperations": ["VERIFY","FETCH", "STORE","REPORT"], "consentDataCategories": [{ "category": "personal_information", "values": ["name", "father_name"] }, { "category": "financial", "values": ["bank_account", "ifsc"] }], "clientObtainedBy": "app-1234" }

Response

Http Status 200

Type	Key	Description	Min Version	Max Version
String	_id	Unique consent Id as assigned by Attestr Platform	v3
String	number	Unique human readable consent number for reference as assigned by Attestr platform	v3

Sample Response

Sample response for valid input

{ "_id": "CX3S-m5YMohWXqt7b-", "number": "3991-752664-7914" }

Error Response

Parameter	Type	Description
code	Number	Unique error codes for different errors. Always available.
httpStatusCode	String	Standard HTTP status code for the error
message	String	Error message describing the error. Always Available.
details	String	Detail error message. Available only for certain types of errors.

Error Codes

HTTP Status	Error Code	Error Message
400	4001	Malformed data or missing required parameter values
400	4005	Operation could not be performed due to low credits balance
401	4016	Invalid client authorization
403	4031	Unauthorized access
403	4035	Requested service is not provisioned for your account
403	4039	Client's IP address is not whitelisted
403	4035	Requested service is not provisioned for your account
429	4291	Maximum account rate limit exceeded
429	4292	Maximum API rate limit exceeded
429	4293	Maximum account daily limit exceeded
429	4294	Maximum API daily limit exceeded
500	5001	Request could not be processed

Sample Error Response

{ "httpStatusCode": 400, "code": 4001, "message": "Malformed data or missing required parameter values", "appError": true }

Last updated on May 25, 2026