API Integrations

1. Before you start

1. Create a client organisation in WordPress Admin → CRIS Check → Clients, or have the client register through POST register.php.
2. Activate the client account and allocate test credits.
3. On the client server, issue a test key. The raw key is returned once only, so save it immediately in server environment variables.
4. Use the test key to integrate and test. Issue a separate live key only when the client is ready.

On this Windows development computer, the API base URL is http://localhost/fica-app/api/. A Docker service on the same computer uses http://host.docker.internal/fica-app/api/. A remote site must use the future public HTTPS CRIS Check API address; its own localhost cannot reach this computer.

2. Client account, API keys and environments

A client has two separate environments. A test key can never read live cases or spend live credits.

Register a pending client

POST /api/register.php
Content-Type: application/x-www-form-urlencoded

organization_name=Client+X&full_name=Jane+Doe&email=jane@example.com&password=choose-a-strong-password

Registration creates a pending account. A CRIS Check administrator activates it and allocates credits before the client can issue keys.

Issue a test key

POST /api/credentials.php
Content-Type: application/x-www-form-urlencoded

email=jane@example.com&password=CLIENT_PASSWORD&environment=test&action=issue

The response contains api_key exactly once. Use action=rotate to replace an existing key or action=revoke to remove it. Administrators can revoke a key in CRIS Check → Clients, but cannot view its value.

Save settings on the client server

CRIS_API_BASE_URL=https://your-cris-domain.example/api/
CRIS_API_KEY=cris_test_received_once_only

Every authenticated API call includes X-API-Key: YOUR_CLIENT_KEY.

3. Load the exact fields and document requirements

Do not hard-code the form forever. Before displaying an integration form, call this endpoint with the client key:

GET /api/application_types.php
X-API-Key: YOUR_CLIENT_KEY

The response lists every supported application type and the exact field_modes and document_modes for each one. Build the selected form from that response: required fields must be collected, optional fields may be collected, and ignore fields must not be sent.

Common request metadata: external_client_id (required and unique on your side), source_app, application_type, application_reference, personal_profile_client_id, and optional callback_url.

Document upload field names must exactly match the selected application type’s document_modes, for example identity_document, proof_of_address, selfie, or supporting_document where they are returned by application_types.php.

To send several files for one requirement, keep that exact canonical name and use normal multipart array notation: proof_of_address[]. CRIS Check accepts up to three files for every evidence field and up to five supporting_document[] files. Each file is stored, assessed and returned separately.

4. Submit a verification

Send multipart/form-data from the client server. This curl example sends a personal verification with three files, including two proofs of address under the same stable field:

curl -X POST "${CRIS_API_BASE_URL}submit.php" 
  -H "X-API-Key: ${CRIS_API_KEY}" 
  -H "Accept: application/json" 
  -F "external_client_id=client-x-000123" 
  -F "source_app=client-x-website" 
  -F "application_type=personal" 
  -F "full_name=Jane Doe" 
  -F "id_number=0000000000000" 
  -F "email=jane@example.com" 
  -F "terms_accepted=1" 
  -F "callback_url=https://client-x.example/cris/callback" 
  -F "identity_document[]=@/secure/path/id.jpg" 
  -F "proof_of_address[]=@/secure/path/address.pdf" 
  -F "proof_of_address[]=@/secure/path/municipal-account.jpg"

A successful background submission returns HTTP 202:

{
  "success": true,
  "case_id": 123,
  "status": "queued",
  "environment": "test",
  "credits_reserved": 1
}

Store case_id and your own external_client_id. Either can retrieve the case later. An insufficient credit balance returns HTTP 422 and no case is retained.

5. Receive progress and the final result

Poll processing status

GET /api/status.php?case_id=123
X-API-Key: YOUR_CLIENT_KEY

Poll every few seconds while queue_status is queued or running. The response reports FICA status, queue status, screening status, and AI processing totals when available.

Get the stable JSON contract

GET /api/v1/result.php?case_id=123
X-API-Key: YOUR_CLIENT_KEY

# Or use your own identifier:
GET /api/v1/result.php?external_client_id=client-x-000123

This is the result endpoint client systems should integrate against. It always returns the v1 shape, identified by schema.name = cris_fica_result and schema.version = 1.0. Every response includes the same ordered master list of all CRIS Check profile fields and document slots, regardless of whether the case is personal, company, trust, NGO/NPO, or merchant. A field outside the selected application is returned with requirement=not_applicable and status=not_applicable; an applicable field with no usable value is returned as outstanding with a null value. CRIS Check will not rename or remove v1 fields; an incompatible change will use a new versioned endpoint.

Use callbacks instead of polling

Include a HTTPS callback_url during submission. After assessment CRIS Check POSTs the same stable v1 JSON result to that URL. Your endpoint must return a 2xx response. When callback signing is enabled by the CRIS Check platform administrator, verify X-FICA-Signature: sha256=… against the configured shared callback secret.

6. Credits and billing information

GET /api/account.php
X-API-Key: YOUR_CLIENT_KEY

The response contains credits.balance, credits.reserved, and credits.available, plus active packages. A credit is reserved when CRIS Check accepts a case. It is deducted only after a successful assessment. If processing fails technically, the reservation is released.

Live payment gateway purchasing will be added later. For now, a CRIS Check administrator allocates test or live credits from CRIS Check → Clients.

7. Integration checklist

• Use HTTPS in production.
• Keep API keys and client passwords on the server only.
• Use a test key and test credits first.
• Fetch application_types.php so your form always matches CRIS Check.
• Store both your external_client_id and CRIS Check case_id.
• Use the versioned v1 result endpoint or a protected callback endpoint.
• Handle HTTP 401, 403, 404, 409, 422, and 500 responses safely.