Incognia Onboarding API

openapi: 3.2.0
info:
  title: Incognia Onboarding API
  version: v2
  description: Incognia is a location identity and device fingerprinting platform for fraud prevention.
  contact:
    name: Incognia Developer Support
    url: https://developer.incognia.com/
  x-source: Faithfully reconstructed from the official Incognia Go client library (github.com/inloco/incognia-go) endpoints, request and response types. Not a provider-published OpenAPI.
servers:
- url: https://api.incognia.com/api
  description: Production
security:
- bearerAuth: []
tags:
- name: Onboarding
  description: Signup risk assessment
paths:
  /v2/onboarding/signups:
    post:
      operationId: registerSignup
      tags:
      - Onboarding
      summary: Register a signup for risk assessment
      description: Evaluate a new-user onboarding signup and return a risk assessment. Send either an installation_id (mobile SDK) or a request_token (web), plus an optional address to assess address quality and location behavior.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SignupRequest'
      responses:
        '200':
          description: Signup risk assessment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SignupAssessment'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid access token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Access token lacks permission for this resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    StructuredAddress:
      type: object
      properties:
        locale:
          type: string
        country_name:
          type: string
        country_code:
          type: string
        state:
          type: string
        city:
          type: string
        county:
          type: string
        borough:
          type: string
        neighborhood:
          type: string
        street:
          type: string
        number:
          type: string
        complements:
          type: string
        postal_code:
          type: string
    SignupRequest:
      type: object
      properties:
        installation_id:
          type: string
        request_token:
          type: string
        related_web_request_token:
          type: string
        session_token:
          type: string
        app_version:
          type: string
        device_os:
          type: string
        address_line:
          type: string
        structured_address:
          $ref: '#/components/schemas/StructuredAddress'
        address_coordinates:
          $ref: '#/components/schemas/Coordinates'
        account_id:
          type: string
        policy_id:
          type: string
        external_id:
          type: string
        tenant_id:
          type: string
        custom_properties:
          type: object
          additionalProperties: true
        person_id:
          $ref: '#/components/schemas/PersonID'
    Coordinates:
      type: object
      properties:
        lat:
          type: number
          format: double
        lng:
          type: number
          format: double
    Error:
      type: object
      description: Incognia error envelope.
      properties:
        message:
          type: string
          example: missing credentials
    PersonID:
      type: object
      properties:
        type:
          type: string
        value:
          type: string
    Reason:
      type: object
      properties:
        code:
          type: string
        source:
          type: string
    SignupAssessment:
      type: object
      properties:
        id:
          type: string
        device_id:
          type: string
        request_id:
          type: string
        risk_assessment:
          $ref: '#/components/schemas/RiskAssessment'
        evidence:
          type: object
          additionalProperties: true
        reasons:
          type: array
          items:
            $ref: '#/components/schemas/Reason'
        actions:
          type: array
          items:
            type: string
        signals:
          type: object
          additionalProperties: true
    RiskAssessment:
      type: string
      enum:
      - low_risk
      - high_risk
      - unknown_risk
      description: Overall risk verdict returned by Incognia.
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: client_id and client_secret sent as HTTP Basic credentials to the token endpoint.
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: OAuth 2.0 bearer access token obtained from POST /v2/token.
    oauth2:
      type: oauth2
      description: OAuth 2.0 client-credentials grant. No scopes are defined; access is scoped by the credential's tenant.
      flows:
        clientCredentials:
          tokenUrl: https://api.incognia.com/api/v2/token
          scopes: {}