INTEGRO API

Introduction

The INTEGRO API is organized around REST. It has predictable, resource-oriented URLs, accepts JSON request bodies, returns JSON responses, and uses standard HTTP response codes, authentication, and verbs. All requests must be made over HTTPS.

Base URL & Versioning

All endpoints are relative to the base URL below.

https://integroai.io/api/

Responses are JSON. Send Content-Type: application/json on requests with a body.

Authentication

Authenticate by exchanging credentials for a token, then send that token as a Bearer token on every request.

Register

POST /api/auth/register/
{ "username": "jane", "email": "jane@acme.com", "password": "••••••" }

Log in & get a token

POST /api/auth/login/
{ "username": "jane", "password": "••••••" }

→ 200 OK
{ "access": "ACCESS_TOKEN", "refresh": "REFRESH_TOKEN" }

Authorize requests

Authorization: Bearer ACCESS_TOKEN

Refresh an expired token

POST /api/auth/token/refresh/
{ "refresh": "REFRESH_TOKEN" }

Rate Limits

Requests are rate limited per account. If you exceed the limit you'll receive 429 Too Many Requests; back off and retry after a short delay. Scan endpoints are additionally limited by your plan's scan quota.

Identities

An identity is the set of data you want to protect (name, emails, phones, usernames, social profiles).

GET  /api/identities/            # list your identities
POST /api/identities/            # create one
{
  "full_name": "Jane Doe",
  "emails": ["jane@acme.com"],
  "phones": ["+1555000111"],
  "usernames": ["janedoe"]
}

Scans

Start a scan for an identity. Choose what to scan with scan_modes and how deep with scan_type.

POST /api/scans/start/
{
  "identity_id": "UUID",
  "scan_type": "full",            // quick | full | deep
  "scan_modes": ["email","username","phone"],
  "consent": true
}

→ 201 Created
{ "id": "SCAN_UUID", "status": "pending" }

Check status & results

GET /api/scans/{scan_id}/        # status + progress
GET /api/scans/{scan_id}/results/

Findings & Alerts

GET  /api/findings/                     # exposures discovered
POST /api/findings/{id}/resolve/        # mark resolved
GET  /api/alerts/                       # monitoring alerts

Find Users

Search discoverable users. Identities are concealed (nickname + photo only) until you connect.

GET /api/users/search/?q=term
→ { "users": [ { "id": 12, "concealed": true, "display_name": "Swift Falcon 07", "is_verified": true } ] }

Conversations

Starting a conversation sends a one-message request. The recipient must accept before full chat unlocks.

POST /api/messages/start/               { "user_id": 12, "message": "Hi!" }
GET  /api/messages/requests/            # incoming requests
POST /api/messages/{id}/accept/
POST /api/messages/{id}/decline/
POST /api/messages/{id}/send/           { "content": "Hello" }

Verify & Integrity

POST /api/messages/{id}/request-verify/    # ask the other user to verify
POST /api/messages/{id}/integrity-link/    # verified users only

KYC / Verification

Start identity verification and receive a hosted URL to complete it.

POST /api/kyc/start/
→ { "verification_url": "https://verification.didit.me/..." }

Webhooks

INTEGRO posts verification results to your configured webhook. Verify the signature using the shared secret before trusting the payload.

POST  https://your-domain/kyc/webhook/
X-Signature: HMAC_SHA256(body, secret)
X-Timestamp: 1699999999

Errors

INTEGRO uses conventional HTTP status codes. Errors return a JSON body with a message and, where useful, a machine-readable code.

200 OK            · success
201 Created       · resource created
400 Bad Request   · invalid parameters
401 Unauthorized  · missing / invalid token
403 Forbidden     · not allowed (e.g. not connected, not verified)
404 Not Found     · resource doesn't exist
429 Too Many      · rate limited, back off and retry

{ "error": "Accept this request to start chatting.", "code": "not_connected" }

Support

Questions or need higher limits? Reach the team at info@integroai.io or visit the About page.