Apply for a Legal Identity

Create the identity application, attach the required photos or documents, then call ReadyForApproval to start review. ApplyId alone does not complete this sequence. For account and key creation in the sandbox, start with the Agent API quickstart. The requests below work with your provider’s HTTPS host and requirements.

Before you start

You need an enabled account, its JWT and account password, and the signing key used for the application. Retain the key’s keyId, localName, namespace, and key password. Keep credentials and identity evidence in your backend. Send Referer on every Agent API request, including backend calls. Replace the host and other placeholders in the examples below.

1. Get the application requirements

POST /Agent/Legal/GetApplicationAttributes HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{}

The response includes Required property names, nrPhotos, peerReview, and nrReviewers. Use these with the selected review provider’s requirements to decide which properties and attachments to collect. Ask the provider which document types and image formats it accepts; a photo count does not identify the required documents.

2. Create the application

Submit the required properties using Apply ID. The quickstart’s application step shows the complete request and signature calculation; replace its test properties with the ones required for your application. Retain the returned Identity.id as legalId. Attachments must be added to your own identity while Identity.status.state is Created, before submitting it for review.

3. Prepare each attachment

Read the file as bytes and Base64-encode those bytes. Use plain Base64 without a data:image/...;base64, prefix. Send one file per request.

Request field	What to supply
`attachmentBase64`	The Base64-encoded file bytes.
`attachmentFileName`	A filename identifying the evidence, such as `ProfilePhoto.jpg`.
`attachmentContentType`	The actual media type, such as `image/jpeg` or `image/png`. It must match the file bytes.
`legalId`	The `Identity.id` returned by `ApplyId`.
`keyId`	The signing key used for this application.

Automated review services can use the filename to recognize a document. Confirm which of these names your reviewer requires:

Filename without extension	Evidence
`ProfilePhoto`	Profile photograph.
`IdCardFront`, `IdCardBack`	Front and back of a national identity card.
`Passport`	Personal-information and signature pages in one image.
`DriverLicenseFront`, `DriverLicenseBack`	Front and back of a driver’s license.

Use the extension matching your file format, for example IdCardFront.png. Upload only the evidence needed for the selected review method. See the original attachment reference for recognized names.

4. Sign and upload the attachment

Define HMAC(secret, message) as Base64-encoded HMAC-SHA-256 using the UTF-8 secret and UTF-8 message. Generate a fresh nonce from 32 random bytes encoded as Base64 for each upload. Build these strings by joining the actual values with : in exactly this order:

keyMessage = userName:host:localName:namespace:keyId
keySignature = HMAC(keyPassword, keyMessage)
message = keyMessage:keySignature:nonce:attachmentBase64:attachmentFileName:attachmentContentType:legalId
requestSignature = HMAC(accountPassword, message)

The host must match the request’s HTTP host, without the scheme or path. Sign the exact filename, content type, Base64 value, and identity identifier you send. Do not change the file or re-encode it after signing.

POST /Agent/Legal/AddIdAttachment HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "keyId": "<APPLICATION_KEY_ID>",
  "legalId": "<IDENTITY_ID>",
  "nonce": "<FRESH_NONCE>",
  "keySignature": "<KEY_SIGNATURE>",
  "requestSignature": "<ATTACHMENT_REQUEST_SIGNATURE>",
  "attachmentBase64": "<BASE64_FILE_BYTES>",
  "attachmentFileName": "ProfilePhoto.jpg",
  "attachmentContentType": "image/jpeg"
}

Add ID Attachment signs the file with the selected key, attaches it to the application, and returns the updated Identity. You do not need a separate SignData call or a multipart upload. Check the updated identity for the attachment reference and retain it with legalId. Repeat for each required file, using a fresh nonce and request signature. Wait for every upload to succeed before continuing.

5. Mark the application ready for approval

Call ReadyForApproval after all required properties and attachments are present to start the configured review, even when no attachments are required. In the sandbox, an identity may already be automatically approved. If its current state is Approved, skip ReadyForApproval; it requires an identity still in Created state. Using the same keyMessage and a new nonce, calculate:

keySignature = HMAC(keyPassword, keyMessage)
message = keyMessage:keySignature:nonce:legalId
requestSignature = HMAC(accountPassword, message)

POST /Agent/Legal/ReadyForApproval HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{
  "keyId": "<APPLICATION_KEY_ID>",
  "legalId": "<IDENTITY_ID>",
  "nonce": "<NEW_NONCE>",
  "keySignature": "<KEY_SIGNATURE>",
  "requestSignature": "<READY_REQUEST_SIGNATURE>"
}

Ready For Approval returns Identity. The request starts review; its HTTP success does not guarantee approval.

6. Observe the result

POST /Agent/Legal/GetIdentity HTTP/1.1
Host: <NEURON_HOST>
Referer: https://your-app.example/
Authorization: Bearer <JWT>
Accept: application/json
Content-Type: application/json

{"legalId":"<IDENTITY_ID>"}

Read Identity.status.state. Continue to signing or other identity-dependent actions only after the identity is Approved. While review is pending, poll at a bounded interval or use your Neuron’s event mechanism. See Observe Legal Identity review. The signature formulas and request order are checked locally. Upload and review outcomes still need testing with your provider.

Recover from an incomplete application

Problem	Next step
Attachment signature rejected	Check the exact Base64 value, filename, media type, host, identity ID, field order, and passwords. Use a new nonce for a corrected request.
Invalid attachment	Check that the Base64 decodes to a file matching its content type and the provider’s accepted format.
Identity is no longer `Created`	Retrieve its state. Do not try to append evidence to an approved identity; ask the operator how to correct or replace the application.
Upload times out	Retrieve the identity and inspect its attachments before uploading again.
Identity remains `Created`	Confirm all required uploads succeeded and `ReadyForApproval` was accepted, then check the review status with the operator.
Readiness request times out	Retrieve the identity before retrying; review may already have started.

Keep attachment bytes, identity documents, passwords, and JWTs out of logs, URLs, analytics, and error reports. Persist identity and attachment references for recovery.

Build an application

Verified identity

Sign-in and signatures

Contracts and agreements

Tokens and digital assets

Wallets and payments

Other application tasks

Reports

Before you start

1. Get the application requirements

2. Create the application

3. Prepare each attachment

4. Sign and upload the attachment

5. Mark the application ready for approval

6. Observe the result

Recover from an incomplete application

​Before you start

​1. Get the application requirements

​2. Create the application

​3. Prepare each attachment

​4. Sign and upload the attachment

​5. Mark the application ready for approval

​6. Observe the result

​Recover from an incomplete application

Before you start

1. Get the application requirements

2. Create the application

3. Prepare each attachment

4. Sign and upload the attachment

5. Mark the application ready for approval

6. Observe the result

Recover from an incomplete application