Remllo
Book demo
Getting StartedCore ConceptsIntegration GuidesAPI ReferenceResources
Identity/API Reference

API Reference

Public-safe REST endpoints for integrating Remllo Identity into your application. Use the API to run direct KYC and KYB checks, create verification sessions, submit evidence and documents, read subject and business context, report identity activity, configure webhooks, and check your wallet balance.

Auth Model

Every request is authenticated with a tenant API key, sent as x-api-key or as an Authorization bearer token. The key determines the tenant and environment.

Core Entry Point

Most integrations start with POST /v1/verifications/kyc or POST /v1/verifications/kyb.

Operational Workflows

Verification sessions, evidence upload, document analysis, webhook delivery, and wallet balance routes are documented here.

Examples use placeholder credentials and sample data only. Keep live API keys server-side, never paste secrets into client code, and every mutating request should carry an idempotency key so a retried request cannot create duplicate verification work.

Developer Reference

Remllo Identity API

Customer-facing reference for the Remllo Identity API. Use this API to run direct KYC and KYB checks, create verification sessions, submit evidence and documents, read subject and business risk context, report identity and access activity from your own platform, configure webhooks, and check your wallet balance. The environment (sandbox or production) is always derived from the API key; requests that try to override it are rejected. Public examples use placeholders only; do not send secrets in URLs, tickets, or client-side code.

Resource

Verifications

Create direct KYC and KYB verification requests and retrieve verification results.

POST
/v1/verifications/kyc

Create a direct KYC verification

Runs one or more individual identity checks synchronously against the subject you provide and returns the risk decision immediately. The environment is derived from the API key; do not send an `environment` field or the request is rejected.

Authentication
apiKey

Parameters

x-api-keystringRequired
idempotency-keystringRequired

Request Body

application/json
objectRequired
subjectobjectRequired
external_refstring
country_codestringRequired
individualobjectRequired

Provide the fields required by the checks you request. See the individual check requirements in the product guide.

bvnstring
ninstring
phone_numberstring
first_namestring
last_namestring
date_of_birthstring
genderstring
doc_imagestring

Base64 image or artifact reference, depending on flow mode.

selfie_imagestring
checksarrayRequired
itemsstring
bvnningovernment_idselfielivenessage_genderdocument_verificationdocument_verification_with_faceface_matchphonebank_accountdrivers_licenseinternational_passportvoters_cardtinvninaddresssanctions_screeningpep_screening
consentobjectRequired

Evidence that the subject consented to this verification.

captured_atstringRequired
sourcestringRequired
legal_basisstringRequired
referencestring
client_referencestring
contextobject

Optional request metadata such as ip_address and device_fingerprint.

1curl -X POST "https://api.remllo.com/v1/verifications/kyc" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "idempotency-key: 8d80a7b3-2e52-4d74-9f7f-f59f14b97f86" \
4  -H "Content-Type: application/json" \
5 \
6  -d '{
7  "subject": {
8    "external_ref": "cust_38221",
9    "country_code": "NG",
10    "individual": {
11      "bvn": "22123456789",
12      "nin": "12345678901",
13      "phone_number": "+2348012345678",
14      "first_name": "Ada",
15      "last_name": "Okoye",
16      "date_of_birth": "1990-04-12",
17      "gender": "Female",
18      "doc_image": "...",
19      "selfie_image": "..."
20    }
21  },
22  "checks": [
23    "bvn",
24    "liveness"
25  ],
26  "consent": {
27    "captured_at": "2026-03-20T10:00:00.000Z",
28    "source": "checkbox_web_form",
29    "legal_basis": "contract",
30    "reference": "consent_9f1b2c"
31  },
32  "client_reference": "onboarding_9911",
33  "context": {}
34}'
Example Response
200 OK
{
  "environment": {
    "type": "string",
    "enum": [
      "sandbox",
      "production"
    ]
  },
  "billable": {
    "type": "boolean"
  },
  "data_source": {
    "type": "string",
    "enum": [
      "mock",
      "provider"
    ]
  },
  "verification_id": "ver_9c1f2a3b4d5e6f708192a3b4c5d6e7f8",
  "status": {
    "type": "string",
    "enum": [
      "pending",
      "in_progress",
      "completed",
      "failed",
      "manual_review"
    ]
  },
  "subject_id": "sub_1a2b3c4d5e6f708192a3b4c5d6e7f8a9",
  "case_type": {
    "type": "string",
    "enum": [
      "kyc",
      "kyb"
    ]
  },
  "client_reference": {
    "type": "string"
  },
  "created_at": {
    "type": "string",
    "format": "date-time"
  },
  "completed_at": {
    "type": "string",
    "format": "date-time"
  },
  "result": {
    "type": "object",
    "properties": {
      "decision": {
        "type": "string",
        "enum": [
          "approve",
          "review",
          "reject"
        ]
      },
      "risk_score": {
        "type": "number",
        "minimum": 0,
        "maximum": 100
      },
      "risk_level": {
        "type": "string",
        "enum": [
          "low",
          "medium",
          "high",
          "critical"
        ]
      },
      "checks": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "bvn",
                "nin",
                "government_id",
                "selfie",
                "liveness",
                "age_gender",
                "document_verification",
                "document_verification_with_face",
                "face_match",
                "phone",
                "bank_account",
                "drivers_license",
                "international_passport",
                "voters_card",
                "tin",
                "vnin",
                "address",
                "sanctions_screening",
                "pep_screening",
                "company_registry",
                "director_verification",
                "ubo_lookup"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "passed",
                "failed",
                "pending",
                "manual_review",
                "awaiting_evidence"
              ]
            },
            "confidence_score": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            "completed_at": {
              "type": "string",
              "format": "date-time"
            },
            "result": {
              "type": "object",
              "description": "Displayable normalized fields for this check. Shape varies by check type."
            },
            "match": {
              "type": "object",
              "properties": {
                "overall": {
                  "type": "string",
                  "enum": [
                    "match",
                    "partial_match",
                    "mismatch",
                    "unavailable"
                  ]
                },
                "fields": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "field": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "matched",
                          "mismatch",
                          "unavailable"
                        ]
                      },
                      "submitted": {
                        "type": "string"
                      },
                      "returned": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            },
            "billing": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "reserved",
                    "captured",
                    "released"
                  ]
                },
                "currency": "NGN",
                "amount_minor": 15000
              }
            },
            "coverage_gap": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "check_type": {
                  "type": "string"
                },
                "subject_type": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "audit_ref": {
    "type": "string"
  }
}
POST
/v1/verifications/kyb

Create a direct KYB verification

Runs one or more business checks synchronously against the business you provide and returns the risk decision immediately. The environment is derived from the API key; do not send an `environment` field or the request is rejected.

Authentication
apiKey

Parameters

x-api-keystringRequired
idempotency-keystringRequired

Request Body

application/json
objectRequired
subjectobjectRequired
external_refstring
country_codestringRequired
businessobjectRequired
legal_namestringRequired
registration_numberstringRequired
first_namestring

Representative first name, required for screening checks.

last_namestring

Representative last name, required for screening checks.

tinstring
checksarrayRequired
itemsstring
tinsanctions_screeningpep_screeningcompany_registrydirector_verificationubo_lookup
consentobjectRequired

Evidence that the subject consented to this verification.

captured_atstringRequired
sourcestringRequired
legal_basisstringRequired
referencestring
client_referencestring
contextobject
1curl -X POST "https://api.remllo.com/v1/verifications/kyb" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "idempotency-key: 8d80a7b3-2e52-4d74-9f7f-f59f14b97f86" \
4  -H "Content-Type: application/json" \
5 \
6  -d '{
7  "subject": {
8    "external_ref": "biz_5521",
9    "country_code": "NG",
10    "business": {
11      "legal_name": "Lagos Trade Exchange Ltd",
12      "registration_number": "RC1234567",
13      "first_name": "...",
14      "last_name": "...",
15      "tin": "..."
16    }
17  },
18  "checks": [
19    "company_registry",
20    "sanctions_screening"
21  ],
22  "consent": {
23    "captured_at": "2026-03-20T10:00:00.000Z",
24    "source": "checkbox_web_form",
25    "legal_basis": "contract",
26    "reference": "consent_9f1b2c"
27  },
28  "client_reference": "...",
29  "context": {}
30}'
Example Response
200 OK
{
  "environment": {
    "type": "string",
    "enum": [
      "sandbox",
      "production"
    ]
  },
  "billable": {
    "type": "boolean"
  },
  "data_source": {
    "type": "string",
    "enum": [
      "mock",
      "provider"
    ]
  },
  "verification_id": "ver_9c1f2a3b4d5e6f708192a3b4c5d6e7f8",
  "status": {
    "type": "string",
    "enum": [
      "pending",
      "in_progress",
      "completed",
      "failed",
      "manual_review"
    ]
  },
  "subject_id": "sub_1a2b3c4d5e6f708192a3b4c5d6e7f8a9",
  "case_type": {
    "type": "string",
    "enum": [
      "kyc",
      "kyb"
    ]
  },
  "client_reference": {
    "type": "string"
  },
  "created_at": {
    "type": "string",
    "format": "date-time"
  },
  "completed_at": {
    "type": "string",
    "format": "date-time"
  },
  "result": {
    "type": "object",
    "properties": {
      "decision": {
        "type": "string",
        "enum": [
          "approve",
          "review",
          "reject"
        ]
      },
      "risk_score": {
        "type": "number",
        "minimum": 0,
        "maximum": 100
      },
      "risk_level": {
        "type": "string",
        "enum": [
          "low",
          "medium",
          "high",
          "critical"
        ]
      },
      "checks": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "bvn",
                "nin",
                "government_id",
                "selfie",
                "liveness",
                "age_gender",
                "document_verification",
                "document_verification_with_face",
                "face_match",
                "phone",
                "bank_account",
                "drivers_license",
                "international_passport",
                "voters_card",
                "tin",
                "vnin",
                "address",
                "sanctions_screening",
                "pep_screening",
                "company_registry",
                "director_verification",
                "ubo_lookup"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "passed",
                "failed",
                "pending",
                "manual_review",
                "awaiting_evidence"
              ]
            },
            "confidence_score": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            "completed_at": {
              "type": "string",
              "format": "date-time"
            },
            "result": {
              "type": "object",
              "description": "Displayable normalized fields for this check. Shape varies by check type."
            },
            "match": {
              "type": "object",
              "properties": {
                "overall": {
                  "type": "string",
                  "enum": [
                    "match",
                    "partial_match",
                    "mismatch",
                    "unavailable"
                  ]
                },
                "fields": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "field": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "matched",
                          "mismatch",
                          "unavailable"
                        ]
                      },
                      "submitted": {
                        "type": "string"
                      },
                      "returned": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            },
            "billing": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "reserved",
                    "captured",
                    "released"
                  ]
                },
                "currency": "NGN",
                "amount_minor": 15000
              }
            },
            "coverage_gap": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "check_type": {
                  "type": "string"
                },
                "subject_type": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "audit_ref": {
    "type": "string"
  }
}
GET
/v1/verifications/{verification_id}

Retrieve a verification

Returns the current status, decision, and check results for a verification created with either the direct verification or session endpoints.

Authentication
apiKey

Parameters

x-api-keystringRequired
verification_idstringRequired
1curl -X GET "https://api.remllo.com/v1/verifications/{verification_id}" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "environment": {
    "type": "string",
    "enum": [
      "sandbox",
      "production"
    ]
  },
  "billable": {
    "type": "boolean"
  },
  "data_source": {
    "type": "string",
    "enum": [
      "mock",
      "provider"
    ]
  },
  "verification_id": "ver_9c1f2a3b4d5e6f708192a3b4c5d6e7f8",
  "status": {
    "type": "string",
    "enum": [
      "pending",
      "in_progress",
      "completed",
      "failed",
      "manual_review"
    ]
  },
  "subject_id": "sub_1a2b3c4d5e6f708192a3b4c5d6e7f8a9",
  "case_type": {
    "type": "string",
    "enum": [
      "kyc",
      "kyb"
    ]
  },
  "client_reference": {
    "type": "string"
  },
  "created_at": {
    "type": "string",
    "format": "date-time"
  },
  "completed_at": {
    "type": "string",
    "format": "date-time"
  },
  "result": {
    "type": "object",
    "properties": {
      "decision": {
        "type": "string",
        "enum": [
          "approve",
          "review",
          "reject"
        ]
      },
      "risk_score": {
        "type": "number",
        "minimum": 0,
        "maximum": 100
      },
      "risk_level": {
        "type": "string",
        "enum": [
          "low",
          "medium",
          "high",
          "critical"
        ]
      },
      "checks": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "enum": [
                "bvn",
                "nin",
                "government_id",
                "selfie",
                "liveness",
                "age_gender",
                "document_verification",
                "document_verification_with_face",
                "face_match",
                "phone",
                "bank_account",
                "drivers_license",
                "international_passport",
                "voters_card",
                "tin",
                "vnin",
                "address",
                "sanctions_screening",
                "pep_screening",
                "company_registry",
                "director_verification",
                "ubo_lookup"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "passed",
                "failed",
                "pending",
                "manual_review",
                "awaiting_evidence"
              ]
            },
            "confidence_score": {
              "type": "number",
              "minimum": 0,
              "maximum": 100
            },
            "completed_at": {
              "type": "string",
              "format": "date-time"
            },
            "result": {
              "type": "object",
              "description": "Displayable normalized fields for this check. Shape varies by check type."
            },
            "match": {
              "type": "object",
              "properties": {
                "overall": {
                  "type": "string",
                  "enum": [
                    "match",
                    "partial_match",
                    "mismatch",
                    "unavailable"
                  ]
                },
                "fields": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "field": {
                        "type": "string"
                      },
                      "status": {
                        "type": "string",
                        "enum": [
                          "matched",
                          "mismatch",
                          "unavailable"
                        ]
                      },
                      "submitted": {
                        "type": "string"
                      },
                      "returned": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            },
            "billing": {
              "type": "object",
              "properties": {
                "status": {
                  "type": "string",
                  "enum": [
                    "reserved",
                    "captured",
                    "released"
                  ]
                },
                "currency": "NGN",
                "amount_minor": 15000
              }
            },
            "coverage_gap": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string"
                },
                "country_code": {
                  "type": "string"
                },
                "check_type": {
                  "type": "string"
                },
                "subject_type": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "audit_ref": {
    "type": "string"
  }
}
Resource

Verification Sessions

Create and track verification sessions for API-driven, hosted, or embedded onboarding flows.

POST
/v1/sessions/kyc

Create a KYC verification session

Creates a session-tracked KYC verification. Use flow_mode `hosted` or `embedded` to defer document and biometric evidence until the subject completes a follow-up step, or `api` when you already have all evidence.

Authentication
apiKey

Parameters

x-api-keystringRequired
idempotency-keystringRequired

Request Body

application/json
objectRequired
subjectobjectRequired
country_codestringRequired
individualobjectRequired

Provide the fields required by the checks you request. See the individual check requirements in the product guide.

bvnstring
ninstring
phone_numberstring
first_namestring
last_namestring
date_of_birthstring
genderstring
doc_imagestring

Base64 image or artifact reference, depending on flow mode.

selfie_imagestring
checksarrayRequired
itemsstring
bvnningovernment_idselfielivenessage_genderdocument_verificationdocument_verification_with_faceface_matchphonebank_accountdrivers_licenseinternational_passportvoters_cardtinvninaddresssanctions_screeningpep_screening
consentobjectRequired

Evidence that the subject consented to this verification.

captured_atstringRequired
sourcestringRequired
legal_basisstringRequired
referencestring
flow_modestring

api expects all evidence up front. hosted and embedded defer document and biometric evidence to a follow-up step.

apihostedembedded
session_expires_atstring
idempotencyKeystring
metadataobject
1curl -X POST "https://api.remllo.com/v1/sessions/kyc" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "idempotency-key: 8d80a7b3-2e52-4d74-9f7f-f59f14b97f86" \
4  -H "Content-Type: application/json" \
5 \
6  -d '{
7  "subject": {
8    "country_code": "NG",
9    "individual": {
10      "bvn": "22123456789",
11      "nin": "12345678901",
12      "phone_number": "+2348012345678",
13      "first_name": "Ada",
14      "last_name": "Okoye",
15      "date_of_birth": "1990-04-12",
16      "gender": "Female",
17      "doc_image": "...",
18      "selfie_image": "..."
19    }
20  },
21  "checks": [
22    "bvn"
23  ],
24  "consent": {
25    "captured_at": "2026-03-20T10:00:00.000Z",
26    "source": "checkbox_web_form",
27    "legal_basis": "contract",
28    "reference": "consent_9f1b2c"
29  },
30  "flow_mode": "api",
31  "session_expires_at": "2026-03-20T10:15:00.000Z",
32  "idempotencyKey": "...",
33  "metadata": {}
34}'
Example Response
200 OK
{
  "session_id": "vsn_2b3c4d5e6f708192a3b4c5d6e7f8a9b0",
  "verification_id": {
    "type": "string"
  },
  "subject_id": {
    "type": "string"
  },
  "case_type": {
    "type": "string",
    "enum": [
      "kyc",
      "kyb"
    ]
  },
  "flow_mode": {
    "type": "string",
    "enum": [
      "api",
      "hosted",
      "embedded"
    ]
  },
  "status": {
    "type": "string",
    "enum": [
      "created",
      "awaiting_document",
      "document_processing",
      "review_required",
      "completed",
      "failed"
    ]
  },
  "current_step": {
    "type": "string",
    "enum": [
      "verification_created",
      "awaiting_document_upload",
      "artifact_scanning",
      "document_analysis",
      "manual_review",
      "completed",
      "failed"
    ]
  },
  "created_at": {
    "type": "string",
    "format": "date-time"
  },
  "updated_at": {
    "type": "string",
    "format": "date-time"
  },
  "expires_at": {
    "type": "string",
    "format": "date-time"
  },
  "verification_status": {
    "type": "string",
    "enum": [
      "pending",
      "in_progress",
      "completed",
      "failed",
      "manual_review"
    ]
  },
  "environment": {
    "type": "string",
    "enum": [
      "sandbox",
      "production"
    ]
  },
  "billable": {
    "type": "boolean"
  },
  "data_source": {
    "type": "string",
    "enum": [
      "mock",
      "provider"
    ]
  },
  "next_actions": {
    "type": "array",
    "items": {
      "type": "string"
    }
  },
  "summary": {
    "type": "object",
    "properties": {
      "requested_checks": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "open_review_count": {
        "type": "integer"
      },
      "document_count": {
        "type": "integer"
      },
      "artifact_count": {
        "type": "integer"
      },
      "pending_artifact_scans": {
        "type": "integer"
      },
      "pending_document_processing": {
        "type": "integer"
      }
    }
  },
  "metadata": {
    "type": "object"
  }
}
POST
/v1/sessions/kyb

Create a KYB verification session

Creates a session-tracked KYB verification. Use flow_mode `hosted` or `embedded` to defer evidence collection to a follow-up step.

Authentication
apiKey

Parameters

x-api-keystringRequired
idempotency-keystringRequired

Request Body

application/json
objectRequired
subjectobjectRequired
country_codestringRequired
businessobjectRequired
legal_namestringRequired
registration_numberstringRequired
first_namestring

Representative first name, required for screening checks.

last_namestring

Representative last name, required for screening checks.

tinstring
checksarrayRequired
itemsstring
tinsanctions_screeningpep_screeningcompany_registrydirector_verificationubo_lookup
consentobjectRequired

Evidence that the subject consented to this verification.

captured_atstringRequired
sourcestringRequired
legal_basisstringRequired
referencestring
flow_modestring

api expects all evidence up front. hosted and embedded defer document and biometric evidence to a follow-up step.

apihostedembedded
session_expires_atstring
idempotencyKeystring
metadataobject
1curl -X POST "https://api.remllo.com/v1/sessions/kyb" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "idempotency-key: 8d80a7b3-2e52-4d74-9f7f-f59f14b97f86" \
4  -H "Content-Type: application/json" \
5 \
6  -d '{
7  "subject": {
8    "country_code": "NG",
9    "business": {
10      "legal_name": "Lagos Trade Exchange Ltd",
11      "registration_number": "RC1234567",
12      "first_name": "...",
13      "last_name": "...",
14      "tin": "..."
15    }
16  },
17  "checks": [
18    "tin"
19  ],
20  "consent": {
21    "captured_at": "2026-03-20T10:00:00.000Z",
22    "source": "checkbox_web_form",
23    "legal_basis": "contract",
24    "reference": "consent_9f1b2c"
25  },
26  "flow_mode": "api",
27  "session_expires_at": "2026-03-20T10:15:00.000Z",
28  "idempotencyKey": "...",
29  "metadata": {}
30}'
Example Response
200 OK
{
  "session_id": "vsn_2b3c4d5e6f708192a3b4c5d6e7f8a9b0",
  "verification_id": {
    "type": "string"
  },
  "subject_id": {
    "type": "string"
  },
  "case_type": {
    "type": "string",
    "enum": [
      "kyc",
      "kyb"
    ]
  },
  "flow_mode": {
    "type": "string",
    "enum": [
      "api",
      "hosted",
      "embedded"
    ]
  },
  "status": {
    "type": "string",
    "enum": [
      "created",
      "awaiting_document",
      "document_processing",
      "review_required",
      "completed",
      "failed"
    ]
  },
  "current_step": {
    "type": "string",
    "enum": [
      "verification_created",
      "awaiting_document_upload",
      "artifact_scanning",
      "document_analysis",
      "manual_review",
      "completed",
      "failed"
    ]
  },
  "created_at": {
    "type": "string",
    "format": "date-time"
  },
  "updated_at": {
    "type": "string",
    "format": "date-time"
  },
  "expires_at": {
    "type": "string",
    "format": "date-time"
  },
  "verification_status": {
    "type": "string",
    "enum": [
      "pending",
      "in_progress",
      "completed",
      "failed",
      "manual_review"
    ]
  },
  "environment": {
    "type": "string",
    "enum": [
      "sandbox",
      "production"
    ]
  },
  "billable": {
    "type": "boolean"
  },
  "data_source": {
    "type": "string",
    "enum": [
      "mock",
      "provider"
    ]
  },
  "next_actions": {
    "type": "array",
    "items": {
      "type": "string"
    }
  },
  "summary": {
    "type": "object",
    "properties": {
      "requested_checks": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "open_review_count": {
        "type": "integer"
      },
      "document_count": {
        "type": "integer"
      },
      "artifact_count": {
        "type": "integer"
      },
      "pending_artifact_scans": {
        "type": "integer"
      },
      "pending_document_processing": {
        "type": "integer"
      }
    }
  },
  "metadata": {
    "type": "object"
  }
}
GET
/v1/sessions/{session_id}

Retrieve a verification session

Returns the current step, status, and evidence summary for a verification session.

Authentication
apiKey

Parameters

x-api-keystringRequired
session_idstringRequired
1curl -X GET "https://api.remllo.com/v1/sessions/{session_id}" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "session_id": "vsn_2b3c4d5e6f708192a3b4c5d6e7f8a9b0",
  "verification_id": {
    "type": "string"
  },
  "subject_id": {
    "type": "string"
  },
  "case_type": {
    "type": "string",
    "enum": [
      "kyc",
      "kyb"
    ]
  },
  "flow_mode": {
    "type": "string",
    "enum": [
      "api",
      "hosted",
      "embedded"
    ]
  },
  "status": {
    "type": "string",
    "enum": [
      "created",
      "awaiting_document",
      "document_processing",
      "review_required",
      "completed",
      "failed"
    ]
  },
  "current_step": {
    "type": "string",
    "enum": [
      "verification_created",
      "awaiting_document_upload",
      "artifact_scanning",
      "document_analysis",
      "manual_review",
      "completed",
      "failed"
    ]
  },
  "created_at": {
    "type": "string",
    "format": "date-time"
  },
  "updated_at": {
    "type": "string",
    "format": "date-time"
  },
  "expires_at": {
    "type": "string",
    "format": "date-time"
  },
  "verification_status": {
    "type": "string",
    "enum": [
      "pending",
      "in_progress",
      "completed",
      "failed",
      "manual_review"
    ]
  },
  "environment": {
    "type": "string",
    "enum": [
      "sandbox",
      "production"
    ]
  },
  "billable": {
    "type": "boolean"
  },
  "data_source": {
    "type": "string",
    "enum": [
      "mock",
      "provider"
    ]
  },
  "next_actions": {
    "type": "array",
    "items": {
      "type": "string"
    }
  },
  "summary": {
    "type": "object",
    "properties": {
      "requested_checks": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "open_review_count": {
        "type": "integer"
      },
      "document_count": {
        "type": "integer"
      },
      "artifact_count": {
        "type": "integer"
      },
      "pending_artifact_scans": {
        "type": "integer"
      },
      "pending_document_processing": {
        "type": "integer"
      }
    }
  },
  "metadata": {
    "type": "object"
  }
}
Resource

Evidence and Documents

Register evidence artifacts, complete their upload lifecycle, and submit identity documents for a verification.

POST
/v1/verifications/{verification_id}/artifacts

Register an evidence artifact

Registers an evidence artifact (a document image, PDF, selfie, or supporting document) against a verification and returns an upload target to send the file to.

Authentication
apiKey

Parameters

x-api-keystringRequired
verification_idstringRequired
idempotency-keystringRequired

Request Body

application/json
objectRequired
artifact_typestringRequired
document_imagedocument_pdfselfie_imagesupporting_document
sha256_digeststringRequired
file_namestring
mime_typestring
size_bytesinteger
retention_untilstring
1curl -X POST "https://api.remllo.com/v1/verifications/{verification_id}/artifacts" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "idempotency-key: 8d80a7b3-2e52-4d74-9f7f-f59f14b97f86" \
4  -H "Content-Type: application/json" \
5 \
6  -d '{
7  "artifact_type": "document_image",
8  "sha256_digest": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
9  "file_name": "passport-front.jpg",
10  "mime_type": "image/jpeg",
11  "size_bytes": 482913,
12  "retention_until": "2026-03-20T10:15:00.000Z"
13}'
Example Response
200 OK
{
  "artifact": {
    "type": "object",
    "properties": {
      "id": "art_3c4d5e6f708192a3b4c5d6e7f8a9b0c1",
      "verificationCaseId": {
        "type": "string"
      },
      "artifactType": {
        "type": "string",
        "enum": [
          "document_image",
          "document_pdf",
          "selfie_image",
          "supporting_document"
        ]
      },
      "status": {
        "type": "string",
        "enum": [
          "registered",
          "uploaded",
          "quarantined"
        ]
      },
      "uploadSessionStatus": {
        "type": "string",
        "enum": [
          "pending_upload",
          "uploaded",
          "expired"
        ]
      },
      "scanStatus": {
        "type": "string",
        "enum": [
          "pending",
          "clean",
          "suspicious"
        ]
      },
      "fileName": {
        "type": "string"
      },
      "mimeType": {
        "type": "string"
      },
      "sizeBytes": {
        "type": "integer"
      },
      "retentionUntil": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "upload": {
    "type": "object",
    "properties": {
      "provider": {
        "type": "string",
        "enum": [
          "s3_compatible_mock",
          "s3_presigned"
        ]
      },
      "method": {
        "type": "string",
        "enum": [
          "PUT"
        ]
      },
      "uploadUrl": {
        "type": "string",
        "format": "uri"
      },
      "objectKey": {
        "type": "string"
      },
      "headers": {
        "type": "object"
      },
      "expiresAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  }
}
GET
/v1/verifications/{verification_id}/artifacts

List evidence artifacts for a verification

Returns every evidence artifact registered against the verification.

Authentication
apiKey

Parameters

x-api-keystringRequired
verification_idstringRequired
1curl -X GET "https://api.remllo.com/v1/verifications/{verification_id}/artifacts" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "id": "art_3c4d5e6f708192a3b4c5d6e7f8a9b0c1",
        "verificationCaseId": {
          "type": "string"
        },
        "artifactType": {
          "type": "string",
          "enum": [
            "document_image",
            "document_pdf",
            "selfie_image",
            "supporting_document"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "registered",
            "uploaded",
            "quarantined"
          ]
        },
        "uploadSessionStatus": {
          "type": "string",
          "enum": [
            "pending_upload",
            "uploaded",
            "expired"
          ]
        },
        "scanStatus": {
          "type": "string",
          "enum": [
            "pending",
            "clean",
            "suspicious"
          ]
        },
        "fileName": {
          "type": "string"
        },
        "mimeType": {
          "type": "string"
        },
        "sizeBytes": {
          "type": "integer"
        },
        "retentionUntil": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}
GET
/v1/artifacts/{artifact_id}

Retrieve an evidence artifact

Returns the current status of a single evidence artifact, including scan and upload session status.

Authentication
apiKey

Parameters

x-api-keystringRequired
artifact_idstringRequired
1curl -X GET "https://api.remllo.com/v1/artifacts/{artifact_id}" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "id": "art_3c4d5e6f708192a3b4c5d6e7f8a9b0c1",
      "verificationCaseId": {
        "type": "string"
      },
      "artifactType": {
        "type": "string",
        "enum": [
          "document_image",
          "document_pdf",
          "selfie_image",
          "supporting_document"
        ]
      },
      "status": {
        "type": "string",
        "enum": [
          "registered",
          "uploaded",
          "quarantined"
        ]
      },
      "uploadSessionStatus": {
        "type": "string",
        "enum": [
          "pending_upload",
          "uploaded",
          "expired"
        ]
      },
      "scanStatus": {
        "type": "string",
        "enum": [
          "pending",
          "clean",
          "suspicious"
        ]
      },
      "fileName": {
        "type": "string"
      },
      "mimeType": {
        "type": "string"
      },
      "sizeBytes": {
        "type": "integer"
      },
      "retentionUntil": {
        "type": "string",
        "format": "date-time"
      }
    }
  }
}
GET
/v1/artifacts/{artifact_id}/jobs

List processing jobs for an artifact

Returns the malware scan and processing jobs that have run against this artifact.

Authentication
apiKey

Parameters

x-api-keystringRequired
artifact_idstringRequired
1curl -X GET "https://api.remllo.com/v1/artifacts/{artifact_id}/jobs" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "jobType": {
          "type": "string"
        },
        "status": {
          "type": "string",
          "enum": [
            "pending",
            "processing",
            "completed",
            "failed"
          ]
        },
        "createdAt": {
          "type": "string",
          "format": "date-time"
        },
        "completedAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}
POST
/v1/artifacts/{artifact_id}/complete-upload

Confirm an artifact upload finished

Call after you finish uploading to the target returned by artifact registration. Triggers the malware scan and downstream processing.

Authentication
apiKey

Parameters

x-api-keystringRequired
artifact_idstringRequired

Request Body

application/json
object
sha256_digeststring
size_bytesinteger
1curl -X POST "https://api.remllo.com/v1/artifacts/{artifact_id}/complete-upload" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json" \
4 \
5  -d '{
6  "sha256_digest": "...",
7  "size_bytes": 0
8}'
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "id": "art_3c4d5e6f708192a3b4c5d6e7f8a9b0c1",
      "verificationCaseId": {
        "type": "string"
      },
      "artifactType": {
        "type": "string",
        "enum": [
          "document_image",
          "document_pdf",
          "selfie_image",
          "supporting_document"
        ]
      },
      "status": {
        "type": "string",
        "enum": [
          "registered",
          "uploaded",
          "quarantined"
        ]
      },
      "uploadSessionStatus": {
        "type": "string",
        "enum": [
          "pending_upload",
          "uploaded",
          "expired"
        ]
      },
      "scanStatus": {
        "type": "string",
        "enum": [
          "pending",
          "clean",
          "suspicious"
        ]
      },
      "fileName": {
        "type": "string"
      },
      "mimeType": {
        "type": "string"
      },
      "sizeBytes": {
        "type": "integer"
      },
      "retentionUntil": {
        "type": "string",
        "format": "date-time"
      }
    }
  }
}
POST
/v1/artifacts/{artifact_id}/refresh-upload-target

Refresh an expired upload target

Issues a new upload target for an artifact whose original target expired before the upload completed.

Authentication
apiKey

Parameters

x-api-keystringRequired
artifact_idstringRequired
1curl -X POST "https://api.remllo.com/v1/artifacts/{artifact_id}/refresh-upload-target" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "artifact": {
    "type": "object",
    "properties": {
      "id": "art_3c4d5e6f708192a3b4c5d6e7f8a9b0c1",
      "verificationCaseId": {
        "type": "string"
      },
      "artifactType": {
        "type": "string",
        "enum": [
          "document_image",
          "document_pdf",
          "selfie_image",
          "supporting_document"
        ]
      },
      "status": {
        "type": "string",
        "enum": [
          "registered",
          "uploaded",
          "quarantined"
        ]
      },
      "uploadSessionStatus": {
        "type": "string",
        "enum": [
          "pending_upload",
          "uploaded",
          "expired"
        ]
      },
      "scanStatus": {
        "type": "string",
        "enum": [
          "pending",
          "clean",
          "suspicious"
        ]
      },
      "fileName": {
        "type": "string"
      },
      "mimeType": {
        "type": "string"
      },
      "sizeBytes": {
        "type": "integer"
      },
      "retentionUntil": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "upload": {
    "type": "object",
    "properties": {
      "provider": {
        "type": "string",
        "enum": [
          "s3_compatible_mock",
          "s3_presigned"
        ]
      },
      "method": {
        "type": "string",
        "enum": [
          "PUT"
        ]
      },
      "uploadUrl": {
        "type": "string",
        "format": "uri"
      },
      "objectKey": {
        "type": "string"
      },
      "headers": {
        "type": "object"
      },
      "expiresAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  }
}
POST
/v1/verifications/{verification_id}/documents

Submit an identity document

Submits a document (referencing an already-uploaded artifact, or inline file metadata) for OCR and authenticity analysis against a verification.

Authentication
apiKey

Parameters

x-api-keystringRequired
verification_idstringRequired
idempotency-keystringRequired

Request Body

application/json
objectRequired
document_typestringRequired
passportdrivers_licensenational_idvoters_cardresidence_permit
document_numberstring
country_codestringRequired
sidestring
frontback
artifact_idstring

Reference to an artifact already registered and uploaded for this verification.

file_namestring
mime_typestring
1curl -X POST "https://api.remllo.com/v1/verifications/{verification_id}/documents" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "idempotency-key: 8d80a7b3-2e52-4d74-9f7f-f59f14b97f86" \
4  -H "Content-Type: application/json" \
5 \
6  -d '{
7  "document_type": "passport",
8  "document_number": "...",
9  "country_code": "NG",
10  "side": "front",
11  "artifact_id": "...",
12  "file_name": "...",
13  "mime_type": "..."
14}'
Example Response
200 OK
{
  "document": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "verificationCaseId": {
        "type": "string"
      },
      "documentType": {
        "type": "string",
        "enum": [
          "passport",
          "drivers_license",
          "national_id",
          "voters_card",
          "residence_permit"
        ]
      },
      "countryCode": {
        "type": "string"
      },
      "side": {
        "type": "string",
        "enum": [
          "front",
          "back"
        ]
      },
      "status": {
        "type": "string",
        "enum": [
          "received",
          "analyzed",
          "review_required"
        ]
      },
      "processingStage": {
        "type": "string",
        "enum": [
          "received",
          "ocr_complete",
          "authenticity_complete",
          "provider_validation_complete"
        ]
      },
      "processingStatus": {
        "type": "string",
        "enum": [
          "pending",
          "processing",
          "completed",
          "failed"
        ]
      }
    }
  },
  "job": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string"
      },
      "status": {
        "type": "string"
      }
    }
  }
}
GET
/v1/verifications/{verification_id}/documents

List submitted documents

Returns every document submitted against a verification, with OCR and authenticity processing status.

Authentication
apiKey

Parameters

x-api-keystringRequired
verification_idstringRequired
1curl -X GET "https://api.remllo.com/v1/verifications/{verification_id}/documents" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "verificationCaseId": {
          "type": "string"
        },
        "documentType": {
          "type": "string",
          "enum": [
            "passport",
            "drivers_license",
            "national_id",
            "voters_card",
            "residence_permit"
          ]
        },
        "countryCode": {
          "type": "string"
        },
        "side": {
          "type": "string",
          "enum": [
            "front",
            "back"
          ]
        },
        "status": {
          "type": "string",
          "enum": [
            "received",
            "analyzed",
            "review_required"
          ]
        },
        "processingStage": {
          "type": "string",
          "enum": [
            "received",
            "ocr_complete",
            "authenticity_complete",
            "provider_validation_complete"
          ]
        },
        "processingStatus": {
          "type": "string",
          "enum": [
            "pending",
            "processing",
            "completed",
            "failed"
          ]
        }
      }
    }
  }
}
Resource

Subjects and Businesses

Retrieve the identity-safe context, risk assessment, and business profile associated with a verified subject.

GET
/v1/subjects/{subject_id}/context

Retrieve identity-safe context for a subject

Returns a summary of a subject's verification status, risk posture, and screening history without exposing raw evidence. This is the same context Identity shares with WatchTower when both products are linked for a tenant.

Authentication
apiKey

Parameters

x-api-keystringRequired
subject_idstringRequired
1curl -X GET "https://api.remllo.com/v1/subjects/{subject_id}/context" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "subjectId": {
        "type": "string"
      },
      "businessId": {
        "type": "string"
      },
      "subjectType": {
        "type": "string",
        "enum": [
          "individual",
          "business"
        ]
      },
      "countryCode": {
        "type": "string"
      },
      "verificationStatus": {
        "type": "string",
        "enum": [
          "pending",
          "in_progress",
          "completed",
          "failed",
          "manual_review"
        ]
      },
      "kycStatus": {
        "type": "string"
      },
      "kybStatus": {
        "type": "string"
      },
      "riskLevel": {
        "type": "string",
        "enum": [
          "low",
          "medium",
          "high",
          "critical"
        ]
      },
      "riskScore": {
        "type": "number"
      },
      "sanctionsHit": {
        "type": "boolean"
      },
      "pepHit": {
        "type": "boolean"
      },
      "latestVerificationAt": {
        "type": "string",
        "format": "date-time"
      },
      "requestedChecks": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "documentTypes": {
        "type": "array",
        "items": {
          "type": "string"
        }
      }
    }
  }
}
GET
/v1/subjects/{subject_id}/risk

Retrieve the latest risk assessment for a subject

Returns the most recent risk score, risk level, and decision recommendation computed for the subject.

Authentication
apiKey

Parameters

x-api-keystringRequired
subject_idstringRequired
1curl -X GET "https://api.remllo.com/v1/subjects/{subject_id}/risk" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "score": {
    "type": "number"
  },
  "riskLevel": {
    "type": "string",
    "enum": [
      "low",
      "medium",
      "high",
      "critical"
    ]
  },
  "decisionRecommendation": {
    "type": "string",
    "enum": [
      "approve",
      "review",
      "reject"
    ]
  },
  "explanations": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "message": {
          "type": "string"
        },
        "weight": {
          "type": "number"
        }
      }
    }
  },
  "createdAt": {
    "type": "string",
    "format": "date-time"
  }
}
GET
/v1/businesses/{subject_id}

Retrieve a business profile

Returns registry, risk, and screening details for a business subject verified through KYB.

Authentication
apiKey

Parameters

x-api-keystringRequired
subject_idstringRequired
1curl -X GET "https://api.remllo.com/v1/businesses/{subject_id}" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "subjectId": {
        "type": "string"
      },
      "legalName": {
        "type": "string"
      },
      "registrationNumber": {
        "type": "string"
      },
      "entityType": {
        "type": "string"
      },
      "incorporationDate": {
        "type": "string"
      },
      "status": {
        "type": "string"
      },
      "registryCountry": {
        "type": "string"
      },
      "riskLevel": {
        "type": "string"
      },
      "riskScore": {
        "type": "number"
      },
      "kybStatus": {
        "type": "string"
      },
      "sanctionsHit": {
        "type": "boolean"
      },
      "pepHit": {
        "type": "boolean"
      }
    }
  }
}
Resource

Identity Activity

Report identity and access activity you observe in your own platform so Remllo can factor it into risk context.

POST
/v1/subjects/{subject_id}/access-events

Report a login or access event

Reports a login success or failure you observed for this subject in your own platform. Remllo folds this into the subject's identity-safe context, and relays it to WatchTower when both products are linked.

Authentication
apiKey

Parameters

x-api-keystringRequired
subject_idstringRequired

Request Body

application/json
objectRequired
outcomestringRequired
successfailed
occurred_atstring
device_idstring
session_idstring
ip_addressstring
country_codestring
access_sourcestring
failure_reasonstring
1curl -X POST "https://api.remllo.com/v1/subjects/{subject_id}/access-events" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json" \
4 \
5  -d '{
6  "outcome": "success",
7  "occurred_at": "2026-03-20T10:15:00.000Z",
8  "device_id": "...",
9  "session_id": "...",
10  "ip_address": "...",
11  "country_code": "...",
12  "access_source": "mobile_app",
13  "failure_reason": "..."
14}'
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "subjectId": {
        "type": "string"
      },
      "emittedEvents": {
        "type": "array",
        "items": {
          "type": "object"
        }
      }
    }
  }
}
POST
/v1/subjects/{subject_id}/security-events

Report a credential change event

Reports a password reset or PIN change you observed for this subject in your own platform.

Authentication
apiKey

Parameters

x-api-keystringRequired
subject_idstringRequired

Request Body

application/json
objectRequired
event_typestringRequired
password.resetpin.changed
occurred_atstring
device_idstring
session_idstring
ip_addressstring
access_sourcestring
reasonstring
recipient_emailstring
reset_urlstring

Only supported for password.reset events.

1curl -X POST "https://api.remllo.com/v1/subjects/{subject_id}/security-events" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json" \
4 \
5  -d '{
6  "event_type": "password.reset",
7  "occurred_at": "2026-03-20T10:15:00.000Z",
8  "device_id": "...",
9  "session_id": "...",
10  "ip_address": "...",
11  "access_source": "...",
12  "reason": "...",
13  "recipient_email": "ops@example.com",
14  "reset_url": "..."
15}'
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "subjectId": {
        "type": "string"
      },
      "emittedEvents": {
        "type": "array",
        "items": {
          "type": "object"
        }
      }
    }
  }
}
POST
/v1/subjects/{subject_id}/screening-events

Report a sanctions or PEP screening hit

Reports a sanctions or politically exposed person screening result you observed for this subject outside of a Remllo-run screening check.

Authentication
apiKey

Parameters

x-api-keystringRequired
subject_idstringRequired

Request Body

application/json
objectRequired
occurred_atstring
sanctions_hitboolean
pep_hitboolean
list_namestring
match_referencestring
risk_levelstring
risk_scorenumber
screening_providerstring

Free-text label for your own screening source, if applicable.

1curl -X POST "https://api.remllo.com/v1/subjects/{subject_id}/screening-events" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json" \
4 \
5  -d '{
6  "occurred_at": "2026-03-20T10:15:00.000Z",
7  "sanctions_hit": true,
8  "pep_hit": true,
9  "list_name": "...",
10  "match_reference": "...",
11  "risk_level": "...",
12  "risk_score": 0,
13  "screening_provider": "..."
14}'
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "subjectId": {
        "type": "string"
      },
      "emittedEvents": {
        "type": "array",
        "items": {
          "type": "object"
        }
      }
    }
  }
}
POST
/v1/subjects/{subject_id}/business-director-changes

Report a business director change

Reports a director or officer being added, updated, or removed for a business subject you have already verified through KYB.

Authentication
apiKey

Parameters

x-api-keystringRequired
subject_idstringRequired

Request Body

application/json
objectRequired
actionstringRequired
addedupdatedremoved
occurred_atstring
director_idstring
director_namestring
rolestring
1curl -X POST "https://api.remllo.com/v1/subjects/{subject_id}/business-director-changes" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json" \
4 \
5  -d '{
6  "action": "added",
7  "occurred_at": "2026-03-20T10:15:00.000Z",
8  "director_id": "...",
9  "director_name": "Chidi Nwosu",
10  "role": "director"
11}'
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "subjectId": {
        "type": "string"
      },
      "emittedEvents": {
        "type": "array",
        "items": {
          "type": "object"
        }
      }
    }
  }
}
Resource

Webhooks

Configure webhook endpoints and inspect delivery history.

POST
/v1/webhooks/endpoints

Create a webhook endpoint

Registers a URL to receive Identity webhook events for your tenant and environment. The signing secret is returned once; store it securely to verify future deliveries.

Authentication
apiKey

Parameters

x-api-keystringRequired

Request Body

application/json
objectRequired
urlstringRequired
subscribed_eventsarrayRequired
itemsstring
descriptionstring
1curl -X POST "https://api.remllo.com/v1/webhooks/endpoints" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json" \
4 \
5  -d '{
6  "url": "...",
7  "subscribed_events": [
8    "identity.verification.completed",
9    "identity.evidence.created"
10  ],
11  "description": "..."
12}'
Example Response
200 OK
{
  "endpoint": {
    "type": "object",
    "properties": {
      "id": "wh_4d5e6f708192a3b4c5d6e7f8a9b0c1d2",
      "tenantId": {
        "type": "string"
      },
      "environment": {
        "type": "string",
        "enum": [
          "sandbox",
          "production"
        ]
      },
      "url": "https://example.com/webhooks/remllo-identity",
      "subscribedEvents": [
        "identity.verification.completed",
        "identity.risk.updated"
      ],
      "description": {
        "type": "string"
      },
      "status": "active",
      "createdAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  },
  "signingSecret": "whsec_5e6f708192a3b4c5d6e7f8a9b0c1d2e3"
}
GET
/v1/webhooks/endpoints

List webhook endpoints

Returns the webhook endpoints configured for your tenant and environment.

Authentication
apiKey

Parameters

x-api-keystringRequired
statusstring
querystring
pageinteger
page_sizeinteger
1curl -X GET "https://api.remllo.com/v1/webhooks/endpoints" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "id": "wh_4d5e6f708192a3b4c5d6e7f8a9b0c1d2",
        "tenantId": {
          "type": "string"
        },
        "environment": {
          "type": "string",
          "enum": [
            "sandbox",
            "production"
          ]
        },
        "url": "https://example.com/webhooks/remllo-identity",
        "subscribedEvents": [
          "identity.verification.completed",
          "identity.risk.updated"
        ],
        "description": {
          "type": "string"
        },
        "status": "active",
        "createdAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}
GET
/v1/webhooks/endpoints/{endpoint_id}

Retrieve a webhook endpoint

Returns a single webhook endpoint by id.

Authentication
apiKey

Parameters

x-api-keystringRequired
endpoint_idstringRequired
1curl -X GET "https://api.remllo.com/v1/webhooks/endpoints/{endpoint_id}" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "id": "wh_4d5e6f708192a3b4c5d6e7f8a9b0c1d2",
      "tenantId": {
        "type": "string"
      },
      "environment": {
        "type": "string",
        "enum": [
          "sandbox",
          "production"
        ]
      },
      "url": "https://example.com/webhooks/remllo-identity",
      "subscribedEvents": [
        "identity.verification.completed",
        "identity.risk.updated"
      ],
      "description": {
        "type": "string"
      },
      "status": "active",
      "createdAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  }
}
POST
/v1/webhooks/endpoints/{endpoint_id}/rotate-secret

Rotate a webhook signing secret

Issues a new signing secret for the endpoint. The new secret is returned once; update your verification code before the old deliveries stop.

Authentication
apiKey

Parameters

x-api-keystringRequired
endpoint_idstringRequired
1curl -X POST "https://api.remllo.com/v1/webhooks/endpoints/{endpoint_id}/rotate-secret" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "endpoint": {
        "type": "object",
        "properties": {
          "id": "wh_4d5e6f708192a3b4c5d6e7f8a9b0c1d2",
          "tenantId": {
            "type": "string"
          },
          "environment": {
            "type": "string",
            "enum": [
              "sandbox",
              "production"
            ]
          },
          "url": "https://example.com/webhooks/remllo-identity",
          "subscribedEvents": [
            "identity.verification.completed",
            "identity.risk.updated"
          ],
          "description": {
            "type": "string"
          },
          "status": "active",
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "signingSecret": {
        "type": "string"
      }
    }
  }
}
POST
/v1/webhooks/endpoints/{endpoint_id}/activate

Activate a webhook endpoint

Resumes delivery to a previously deactivated endpoint.

Authentication
apiKey

Parameters

x-api-keystringRequired
endpoint_idstringRequired
1curl -X POST "https://api.remllo.com/v1/webhooks/endpoints/{endpoint_id}/activate" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "id": "wh_4d5e6f708192a3b4c5d6e7f8a9b0c1d2",
      "tenantId": {
        "type": "string"
      },
      "environment": {
        "type": "string",
        "enum": [
          "sandbox",
          "production"
        ]
      },
      "url": "https://example.com/webhooks/remllo-identity",
      "subscribedEvents": [
        "identity.verification.completed",
        "identity.risk.updated"
      ],
      "description": {
        "type": "string"
      },
      "status": "active",
      "createdAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  }
}
POST
/v1/webhooks/endpoints/{endpoint_id}/deactivate

Deactivate a webhook endpoint

Pauses delivery to this endpoint without deleting its configuration.

Authentication
apiKey

Parameters

x-api-keystringRequired
endpoint_idstringRequired
1curl -X POST "https://api.remllo.com/v1/webhooks/endpoints/{endpoint_id}/deactivate" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "id": "wh_4d5e6f708192a3b4c5d6e7f8a9b0c1d2",
      "tenantId": {
        "type": "string"
      },
      "environment": {
        "type": "string",
        "enum": [
          "sandbox",
          "production"
        ]
      },
      "url": "https://example.com/webhooks/remllo-identity",
      "subscribedEvents": [
        "identity.verification.completed",
        "identity.risk.updated"
      ],
      "description": {
        "type": "string"
      },
      "status": "active",
      "createdAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  }
}
GET
/v1/webhooks/endpoints/{endpoint_id}/deliveries

List deliveries for a webhook endpoint

Returns delivery attempts sent to this specific endpoint, most recent first.

Authentication
apiKey

Parameters

x-api-keystringRequired
endpoint_idstringRequired
statusstring
limitinteger
1curl -X GET "https://api.remllo.com/v1/webhooks/endpoints/{endpoint_id}/deliveries" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "id": "whd_6f708192a3b4c5d6e7f8a9b0c1d2e3f4",
        "eventId": {
          "type": "string"
        },
        "endpointId": {
          "type": "string"
        },
        "destination": {
          "type": "string",
          "format": "uri"
        },
        "status": "delivered",
        "attemptCount": {
          "type": "integer"
        },
        "lastHttpStatus": {
          "type": "integer"
        },
        "lastError": {
          "type": "string"
        },
        "nextAttemptAt": {
          "type": "string",
          "format": "date-time"
        },
        "lastAttemptAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}
GET
/v1/webhooks/deliveries

List webhook deliveries

Returns delivery attempts across all endpoints for your tenant and environment, most recent first.

Authentication
apiKey

Parameters

x-api-keystringRequired
statusstring
endpoint_idstring
limitinteger
pageinteger
page_sizeinteger
1curl -X GET "https://api.remllo.com/v1/webhooks/deliveries" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "id": "whd_6f708192a3b4c5d6e7f8a9b0c1d2e3f4",
        "eventId": {
          "type": "string"
        },
        "endpointId": {
          "type": "string"
        },
        "destination": {
          "type": "string",
          "format": "uri"
        },
        "status": "delivered",
        "attemptCount": {
          "type": "integer"
        },
        "lastHttpStatus": {
          "type": "integer"
        },
        "lastError": {
          "type": "string"
        },
        "nextAttemptAt": {
          "type": "string",
          "format": "date-time"
        },
        "lastAttemptAt": {
          "type": "string",
          "format": "date-time"
        }
      }
    }
  }
}
GET
/v1/webhooks/deliveries/{delivery_id}

Retrieve a webhook delivery

Returns a single delivery attempt by id, including its latest HTTP status and error if it failed.

Authentication
apiKey

Parameters

x-api-keystringRequired
delivery_idstringRequired
1curl -X GET "https://api.remllo.com/v1/webhooks/deliveries/{delivery_id}" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "id": "whd_6f708192a3b4c5d6e7f8a9b0c1d2e3f4",
      "eventId": {
        "type": "string"
      },
      "endpointId": {
        "type": "string"
      },
      "destination": {
        "type": "string",
        "format": "uri"
      },
      "status": "delivered",
      "attemptCount": {
        "type": "integer"
      },
      "lastHttpStatus": {
        "type": "integer"
      },
      "lastError": {
        "type": "string"
      },
      "nextAttemptAt": {
        "type": "string",
        "format": "date-time"
      },
      "lastAttemptAt": {
        "type": "string",
        "format": "date-time"
      }
    }
  }
}
Resource

Wallet

Check prepaid balance, funding history, and active pricing for your tenant.

GET
/v1/wallet

Retrieve wallet balance and pricing

Returns your tenant's prepaid balance, recent ledger entries, funding intent history, and the active per-check prices available to your tenant and country.

Authentication
apiKey

Parameters

x-api-keystringRequired
1curl -X GET "https://api.remllo.com/v1/wallet" \
2  -H "x-api-key: remllo_sk_test_EXAMPLESELECTOR12_examplesecretvaluegoeshere" \
3  -H "Content-Type: application/json"
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "currency": "NGN",
      "tenant": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "region": {
            "type": "string"
          }
        }
      },
      "accounts": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "currency": {
              "type": "string"
            },
            "availableBalanceMinor": {
              "type": "integer"
            },
            "reservedBalanceMinor": {
              "type": "integer"
            },
            "status": {
              "type": "string",
              "enum": [
                "active",
                "disabled"
              ]
            }
          }
        }
      },
      "primaryAccount": {
        "type": "object",
        "nullable": true
      },
      "ledgerEntries": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "entryType": {
              "type": "string"
            },
            "direction": {
              "type": "string",
              "enum": [
                "credit",
                "debit"
              ]
            },
            "amountMinor": {
              "type": "integer"
            },
            "createdAt": {
              "type": "string",
              "format": "date-time"
            }
          }
        }
      },
      "fundingIntents": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "amountMinor": {
              "type": "integer"
            },
            "status": {
              "type": "string",
              "enum": [
                "pending",
                "processing",
                "succeeded",
                "failed",
                "expired"
              ]
            },
            "createdAt": {
              "type": "string",
              "format": "date-time"
            }
          }
        }
      },
      "prices": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "countryCode": {
              "type": "string"
            },
            "checkType": {
              "type": "string"
            },
            "subjectType": {
              "type": "string",
              "enum": [
                "individual",
                "business"
              ]
            },
            "currency": {
              "type": "string"
            },
            "priceMinor": {
              "type": "integer"
            },
            "channel": {
              "type": "string",
              "enum": [
                "api",
                "console",
                "embedded"
              ]
            },
            "status": {
              "type": "string",
              "enum": [
                "draft",
                "active",
                "inactive"
              ]
            }
          }
        }
      }
    }
  }
}
Resource

Account Recovery

Complete a password reset for an Identity console account.

POST
/v1/accounts/password-reset/complete

Complete a console account password reset

Completes a password reset for an Identity console account using the token from the reset email. This is unauthenticated by design; the token itself is the credential.

Request Body

application/json
objectRequired
tokenstringRequired
newPasswordstringRequired
1curl -X POST "https://api.remllo.com/v1/accounts/password-reset/complete" \
2  -H "Content-Type: application/json" \
3 \
4  -d '{
5  "token": "prt_7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d",
6  "newPassword": "a-strong-example-passphrase"
7}'
Example Response
200 OK
{
  "data": {
    "type": "object",
    "properties": {
      "account": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        }
      }
    }
  }
}