Bynn Intelligence Aml API

openapi: 3.2.0
info:
  title: BYNN Aml API
  description: 'The BYNN API is organized around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors, although our API libraries convert responses to appropriate language-specific objects. To make the API as explorable as possible, accounts have test mode and live mode API keys. There is no “switch” for changing between modes, just use the appropriate key to perform a live or test transaction. Requests made with test-mode credentials never hit live networks and incur no cost. **AUTHENTICATION:** Use your **Private API Key**, which looks like `private_xxxxxxxxxxxxxxxxxxxxxxxx` (or `private_sandbox_xxxxxxxxxxxxxxxxxxxxxxxx` for a sandbox key), as the username in HTTP Basic auth with an empty password, or send it as `Authorization: Bearer `. Your keys are at https://dashboard.bynn.com/integration.'
  termsOfService: https://bynn.com/terms
  contact:
    name: BYNN Development Team
    email: hello@bynn.com
    url: https://docs.bynn.com
  license:
    name: BYNN Documentation
    url: https://docs.bynn.com
  version: '1.0'
servers:
- url: https://api.bynn.com/v1
tags:
- name: AML
  description: Operations about amls
paths:
  /aml/entity/{id}:
    get:
      summary: Retrieve an AML entity
      description: Returns the AML-entity payload delivered by `aml_entity.*` webhooks (screening status).
      parameters:
      - in: path
        name: id
        description: AML entity identifier (`aml_xxx`).
        required: true
        schema:
          type: string
      security:
      - PrivateKey: []
      responses:
        '200':
          description: Retrieve an AML entity
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '404':
          description: Not found in this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
      tags:
      - AML
      operationId: getAmlEntityId
  /aml/activity/{id}:
    get:
      summary: Retrieve an AML activity / match
      description: Returns the AML-activity payload delivered by `aml_activity.*` webhooks (the individual screening match).
      parameters:
      - in: path
        name: id
        description: AML activity identifier (`amla_xxx`).
        required: true
        schema:
          type: string
      security:
      - PrivateKey: []
      responses:
        '200':
          description: Retrieve an AML activity / match
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '404':
          description: Not found in this organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
      tags:
      - AML
      operationId: getAmlActivityId
  /aml/search:
    post:
      summary: Search AML data (sanctions, PEP & watchlists)
      description: 'Screens a name against Bynn''s AML data — global sanctions, PEP (politically

        exposed persons), and watchlists.


        Search for a **person** or an **entity** (company / organization) with the

        `type` parameter. Returns the ranked matches; use the returned `id` with the

        AML detail endpoints to pull a full profile.


        ### Response

        ```

        {

        "query": "John Doe",

        "type": "person",

        "total": 2,

        "results": [

        { "id": "NK-…", "name": "John Doe", "schema": "Person", "match": true,

        "score": 0.92, "topics": ["sanction"], "birth_date": ["1965-04-12"],

        "country": ["ru"] }

        ]

        }

        ```


        ### Errors

        - `401 authentication_error` — missing, malformed, or revoked private key.

        - `402 payment_required` — the request could not be completed for this account.

        - `503 service_unavailable` — screening is temporarily unavailable; retry.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/postAmlSearch'
        required: true
      security:
      - PrivateKey: []
      responses:
        '201':
          description: Search AML data (sanctions, PEP & watchlists)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_AmlSearchResultEntity'
        '401':
          description: Invalid or missing credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '402':
          description: Payment required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
        '503':
          description: Screening temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Bynn_V1_Entities_Error'
      tags:
      - AML
      operationId: postAmlSearch
components:
  schemas:
    postAmlSearch:
      type: object
      properties:
        name:
          type: string
          description: Name to screen against the AML data.
        type:
          type: string
          description: 'What to search for: a `person` or an entity (`company` / `organization` / `legal_entity`).'
          enum:
          - person
          - company
          - organization
          - legal_entity
          default: person
        limit:
          type: integer
          format: int32
          description: Maximum number of matches to return (default 10, max 50).
          minimum: 1
          maximum: 50
          default: 10
      required:
      - name
      description: Search AML data (sanctions, PEP & watchlists)
    Bynn_V1_Entities_AmlSearchResultEntity:
      type: object
      properties:
        id:
          type: string
          example: NK-abc123
          description: Stable identifier of the matched profile (use it to fetch full detail).
        name:
          type: string
          example: John Doe
          description: Primary name / caption of the match.
        schema:
          type: string
          enum:
          - Person
          - Company
          - Organization
          - LegalEntity
          example: Person
          description: Kind of profile matched.
        match:
          type: boolean
          example: true
          description: Whether the provider considers this a strong match (above the match threshold).
        score:
          type: number
          example: 0.92
          description: Match score (0.0–1.0).
        topics:
          type: array
          items:
            type: array
            items: {}
          example:
          - sanction
          description: Risk topics on the profile (e.g. sanction, role.pep, crime, debarment).
        birth_date:
          type: array
          items:
            type: array
            items: {}
          example:
          - '1965-04-12'
          description: Known dates of birth (YYYY-MM-DD).
        birth_place:
          type: array
          items:
            type: array
            items: {}
          description: Known places of birth.
        death_date:
          type: array
          items:
            type: array
            items: {}
          description: Known dates of death, when applicable.
        country:
          type: array
          items:
            type: array
            items: {}
          example:
          - ru
          description: Citizenship / nationality / country of the profile.
      required:
      - id
      - name
      - schema
      - match
      - score
      - topics
      - birth_date
      - birth_place
      - death_date
      - country
      description: Bynn_V1_Entities_AmlSearchResultEntity model
    Bynn_V1_Entities_Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              example: validation_error
              description: Type of error
            message:
              type: string
              example: Invalid parameters
              description: Error message
            reason:
              type: string
              example: issuer_key_unavailable
              description: Machine-readable cause, where one is set
            retry_after:
              type: integer
              format: int32
              example: 60
              description: Seconds to wait before retrying
            limit:
              type: integer
              format: int32
              example: 30
              description: The limit that was exceeded
            detail:
              type: string
              description: Operator-facing detail, outside production
          required:
          - type
          - message
      required:
      - error
      description: Bynn_V1_Entities_Error model
  securitySchemes:
    PrivateKey:
      type: apiKey
      name: Authorization
      in: header
      description: Enter your PRIVATE KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`
    PublicKey:
      type: apiKey
      name: Authorization
      in: header
      description: Enter your PUBLIC KEY token prefixed with `Bearer `, e.g. `Bearer your_token_here`