Get started with API

This guide walks you through making your first API call to AdvanGuard — from generating an access token to creating a verification application.

Before You Start

1. Sign up for an AdvanGuard account on the AdvanGuard platform.
2. Get your credentials — navigate to Account → Account Management to obtain your accessKey and secretKey.
3. Configure webhooks (optional) — set up a webhook endpoint in the AdvanGuard platform to receive status change notifications. See the Webhooks Guide for details.

Base URL

All API requests are made to:

https://openapi.advance.ai/v1/

Available environments:

Testing account — Use a testing account during development to avoid affecting production data. Contact your account manager to request one.

Step 1: Generate an Access Token

Before calling any API, you need to generate a JWT access token.

Compute the Signature

Concatenate accessKey + secretKey + timestamp and compute the SHA-256 hash:

import java.security.MessageDigest;

public class SignatureUtil {

    public static String computeSignature(String accessKey, String secretKey, String timestamp) {
        try {
            String combined = accessKey + secretKey + timestamp;
            MessageDigest digest = MessageDigest.getInstance("SHA-256");
            byte[] hash = digest.digest(combined.getBytes("UTF-8"));
            StringBuilder hex = new StringBuilder();
            for (byte b : hash) {
                String h = Integer.toHexString(0xff & b);
                if (h.length() == 1) hex.append('0');
                hex.append(h);
            }
            return hex.toString();
        } catch (Exception e) {
            throw new RuntimeException(e);
        }
    }
}

Request the Token

curl -X POST https://openapi.advance.ai/v1/auth/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "accessKey": "your_access_key",
    "timestamp": 1718524800000,
    "signature": "computed_sha256_signature"
  }'

Response:

{
  "accessToken": "eyJhbGciOiJIUzUxMiJ9.eyJpc3MiOiJhZHZhbmd1YXJkIn0.abc123",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "expiresAt": "2026-06-16T10:00:00Z"
}

Use the accessToken value in the Authorization header for all subsequent requests.

See the Authentication Guide for the full signature computation reference and multi-language code examples.

Step 2: Create a Verification Application

Create a verification application for a user. The API automatically creates or associates a profile for the given externalUserId.

Note: The levelId defines the verification flow (which checks to perform). You can find your available Level IDs in the AdvanGuard platform under Level Management.

curl -X POST https://openapi.advance.ai/v1/individual/applications \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "levelId": "level-kyc-standard",
    "externalUserId": "user-001",
    "inputInfo": {
      "preferences": { "language": "en-US", "prefersColorScheme": "light" }
    }
  }'

Response (200 OK; example for a workflow with client collection):

{
  "applicationId": "app-7392581047263518721",
  "profileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "levelId": "level-kyc-standard",
  "levelVersion": 3,
  "created": "2026-09-24T08:00:00Z",
  "link": {
    "linkId": "AAECAwQFBgcICQoLDA0ODw",
    "url": "https://verify.example.com/entry/example-link",
    "status": "ACTIVE",
    "expiresAt": "2026-10-01T08:00:00Z"
  },
  "requestId": "req-example"
}

Save applicationId and profileId. If link is returned, open its url in the applicant's browser to collect verification data. Use the actual returned URL, not the illustrative domain above. Workflows without a Collect node omit link.

The creation response is an acknowledgment; retrieve status and results in the next step. An existing active application returns 409 active_application_exists; it is not automatically resumed. 409 application_create_in_progress means another creation is running for the same user: retry with backoff. Do not rely on conflictStrategy or Idempotency-Key to resume or deduplicate creation.

Optional link.ttlSeconds is an integer from 1 to 2592000 (default 604800). Optional link.redirect contains at least one HTTPS submittedUrl, successUrl, or rejectUrl. These options apply to workflows with client collection.

Step 3: Check Application Status

Poll the application status to track verification progress:

curl https://openapi.advance.ai/v1/individual/applications/app-7392581047263518721 \
  -H "Authorization: Bearer eyJhbGciOiJIUzUxMiJ9..."

Response:

{
  "applicationId": "app-7392581047263518721",
  "externalUserId": "user-001",
  "profileId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "levelId": "level-kyc-standard",
  "levelVersion": 3,
  "status": "completed",
  "review": { "reviewAnswer": "GREEN", "rejectLabels": [] },
  "stepResults": {},
  "createdAt": "2026-09-24T08:00:00Z",
  "updatedAt": "2026-09-24T08:10:00Z",
  "completedAt": "2026-09-24T08:10:00Z",
  "requestId": "req-example"
}

stepResults depends on the configured workflow and available results. Document results appear under stepResults.document: documentType identifies each side, ocr contains merged recognition data, and ocrSides.front / ocrSides.back contain side-specific data. An unavailable side is null; before recognition, these result fields may be absent. Within an OCR result, unrecognized values are null and extra is an object.

Face results appear under stepResults.face as faceLiveness, faceCompare, and faceFastfail; face may be null before a trusted result exists. Document and Face do not use resultData or expose internal workflow nodes. review.reviewAnswer can be null before a conclusion.

The query returns profileId, not an embedded Profile. Retrieve identity details with GET /v1/individual/profiles/{profileId} when that API is enabled for your integration.

Tip: Instead of polling, configure a webhook to receive real-time notifications when the application status changes.

API Groups

AdvanGuard APIs are organized into groups:

Next Steps

• Authentication — Signature computation, token lifecycle, and security best practices
• Errors — Error handling patterns
• Webhooks — Real-time event notifications