Authologic Customer API

openapi: 3.1.0
info:
  title: Authologic Customer API
  description: "\nThe integration API for using with Authlogic Engine.\n\nAuthologic allows for simple and effective checking\
    \ of the user's identity, and the use of API enables initiation by an external system\nthe verification process and the\
    \ receipt of its results.\n                "
  contact:
    name: API support
    email: tech-support@authologic.com
  version: '1.1'
externalDocs:
  description: API Documentation
  url: https://developer.authologic.com
servers:
- url: https://sandbox.authologic.com
  description: Testing environment
security:
- apiKey: []
- oauth2: []
tags:
- name: Conversation
  description: 1. Base Methods needed for the verification process.
  externalDocs:
    description: Usage
    url: https://developer.authologic.com/docs/developer-documentation/home
- name: Bank
  description: '2. Product: Bank Transactions'
  externalDocs:
    description: Usage
    url: https://developer.authologic.com/docs/developer-documentation/product-bank-transactions-index
- name: AML
  description: '3. Product: AML'
  externalDocs:
    description: Usage
    url: https://developer.authologic.com/docs/developer-documentation/product-aml-index
- name: Advanced
  description: 4. Advanced methods.
  externalDocs:
    description: Usage
    url: https://developer.authologic.com/docs/developer-documentation/home
- name: Metadata
  description: '5. Advanced: Metadata'
  externalDocs:
    description: Usage
    url: https://developer.authologic.com/docs/developer-documentation/additional-information-metadata
- name: Enterprise Integration
  description: 6. Enterprise Integration
  externalDocs:
    description: Usage
    url: https://developer.authologic.com/docs/developer-documentation/additional-headless-integration
- name: Affordability assessment
  description: '7. Product: Affordability assessment'
  externalDocs:
    description: Usage
    url: https://developer.authologic.com/docs/developer-documentation/product-affordability-index
- name: Database Verification
  description: '8. Product: Database Verification'
  externalDocs:
    description: Usage
    url: https://developer.authologic.com/docs/developer-documentation/product-dbv-index
paths:
  /api/conversations:
    post:
      tags:
      - Conversation
      summary: Start a new user verification process
      description: "\nEach process of getting data and confirming the identity of the user should start by calling this method.\n\
        The call initiates this process and returns information about the address to which the user should be redirected to\n\
        gathering the information requested from him.\n\n::note\nIn order to use the API you need to obtain the login and\
        \ password for a for a specific environment. \nYou can generate a new API key in the API Keys section of the OmniPanel.\n\
        The API is accessible via either HTTP Basic authentication or OAuth2 client credentials flow.\nBoth methods accept\
        \ the same API key.  \nWhen using OAuth2, the API key can be sent either via Authentication Bearer header or via HTTP\
        \ POST body.  \n::\n\n\n::note\nThis is because all of these fields may have their default values set on the Authologic\
        \ side when creating your account. If any value does not have a default setting you will get an error and you should\
        \ either provide that value or report to Authologic to set the default one.\n::\n\nThe query contains three groups\
        \ of information:\n * general information such as:\n   * **userKey**: User ID on your system\n   * **strategy**: information\
        \ about the identity checking strategy (usually the default value is sufficient)\n   * **returnUrl**: URL to which\
        \ the user should be redirected after the process is completed\n   * **callbackUrl**: information about the return\
        \ address to which the system will send the acquired information. If this information is not provided, Authologic\
        \ assumes that the information will be downloaded by the client\n * **query**: query definition containing individual\
        \ products provided by Authologic\n\n::warning\nThe test environment allows the use of an HTTP address for **callbackUrl**.\
        \ A production environment always requires HTTPS.\n::\n\n::note\nFor testing purposes, to check the callback request,\
        \ you can use online tools that accept and present the outgoing requests. One such tool is, for example, [Webhook](https://webhook.site/).\
        \ When creating a conversation, it is enough to provide the url generated by Webhook in the callbackUrl parameter.\n\
        ::\n\n\nThe information contained in the query section is divided into specific products:\n * **identity** - fetch\
        \ user information. This section is always required\n    * **requireOneOf**: User information to be specified by Authologic.\
        \ This is represented as set of sets and Authologic will try to fetch one of these\n    * **optional**: User information\
        \ that may be specified by Authologic when the information is available\n * **aml** - check user on AML lists\n  \
        \ * **checks**: lists where the user should be checked\n * **auth** - user authentication product\n * **bankTransactions**\
        \ - the process of retrieving information about transactions.\n   * **type**: type of transaction - credit, debit\
        \ or all\n   * **flags**: Additional information on what to return\n * **verify** - confirmation of the compliance\
        \ of user data\n    * **user**: information about user that should be verified\n        "
      operationId: createConversation
      requestBody:
        content:
          application/vnd.authologic.v1.1+json:
            schema:
              $ref: '#/components/schemas/CreateConversation'
            examples:
              Simple verification process example:
                summary: The simplest verification process
                description: This example shows the main scenario of verification.
                value:
                  userKey: 7dfb9ded-c38f-49ae-95e2-307283a0b1f6
                  returnUrl: https://authologic.com/tests/return/?conversation={conversationId}
                  strategy: public:default
                  query:
                    identity:
                      requireOneOf:
                      - - PERSON_NAME_FIRSTNAME
                        - PERSON_NAME_LASTNAME
                      optional:
                      - list:
                        - PERSON_CONTACT_EMAIL_OTP
              Multiple success options example:
                summary: The process with multiple success options
                description: This example shows how to use multiple field sets to describe alternative success options.
                value:
                  userKey: 7dfb9ded-c38f-49ae-95e2-307283a0b1f6
                  returnUrl: https://authologic.com/tests/return/?conversation={conversationId}
                  strategy: public:default
                  query:
                    identity:
                      requireOneOf:
                      - - PERSON_NAME_FIRSTNAME
                        - PERSON_NAME_LASTNAME
                        - PERSON_IDS_NATIONAL_ID
                      - - PERSON_NAME_FIRSTNAME
                        - PERSON_NAME_LASTNAME
                        - PERSON_IDS_PASSPORT_ID
                      optional:
                      - list:
                        - PERSON_CONTACT_EMAIL_OTP
              AML verification process example:
                summary: Verification process with AML continuous monitoring
                description: This example shows how to perform verification and set up the AML monitoring.
                value:
                  userKey: 7dfb9ded-c38f-49ae-95e2-307283a0b1f6
                  returnUrl: https://authologic.com/tests/return/?conversation={conversationId}
                  strategy: public:default
                  query:
                    identity:
                      requireOneOf:
                      - - PERSON_NAME_FIRSTNAME
                        - PERSON_NAME_LASTNAME
                    aml:
                      checks:
                      - PEP
                      - SANCTIONS
                      subscription: {}
              Example usage of the authorization product:
                summary: The user authorization product
                description: This example shows the main scenario for user authorization.
                value:
                  userKey: 7dfb9ded-c38f-49ae-95e2-307283a0b1f6
                  returnUrl: https://authologic.com/tests/return/?conversation={conversationId}
                  strategy: public:default
                  query:
                    auth: {}
              Example usage of the affordability product:
                summary: The affordability product
                description: This example shows the main scenario of verification.
                value:
                  userKey: 7dfb9ded-c38f-49ae-95e2-307283a0b1f6
                  returnUrl: https://authologic.com/tests/return/?conversation={conversationId}
                  strategy: public:default
                  query:
                    affordability:
                      user:
                        country: NL
                        email: test.user@email.com
              Example usage of the Database verification product:
                summary: The Database verification product
                description: This example shows the main scenario of identity and database verification.
                value:
                  userKey: 7dfb9ded-c38f-49ae-95e2-307283a0b1f6
                  returnUrl: https://authologic.com/tests/return/?conversation={conversationId}
                  strategy: public:default
                  query:
                    identity:
                      requireOneOf:
                      - - PERSON_NAME_FIRSTNAME
                        - PERSON_NAME_LASTNAME
                    databaseVerification: {}
      responses:
        '200':
          description: Conversation started
          content:
            application/vnd.authologic.v1.1+json:
              schema:
                $ref: '#/components/schemas/ConversationInfo'
              examples:
                Conversation created response example:
                  summary: Conversation Created and waiting for the user
                  description: The conversation was created and now the user should be redirected to the given url.
                  value:
                    id: 022e8eaf-b06d-44b9-a68f-45eef1353dbe
                    userKey: 7dfb9ded-c38f-49ae-95e2-307283a0b1f6
                    url: https://sandbox.authologic.com/c/022e8eaf-b06d-44b9-a68f-45eef1353dbe
                    status: CREATED
                    result:
                      identity:
                        status: IN_PROGRESS
                        user: {}
        '400':
          description: Bad Request
          content:
            application/vnd.authologic.v1.1+json:
              schema:
                type: string
                oneOf:
                - $ref: '#/components/schemas/BadRequestApiError'
                - $ref: '#/components/schemas/MethodArgumentNotValidError'
                - $ref: '#/components/schemas/MethodArgumentTypeMismatchError'
                - $ref: '#/components/schemas/ConstraintViolationError'
                - $ref: '#/components/schemas/CustomValidationApiError'
                - $ref: '#/components/schemas/OperationNotSupportedApiFieldError'
                - $ref: '#/components/schemas/MissingHeaderApiError'
              examples:
                Bad request example:
                  summary: Bad request example
                  description: Example of bad request in case validation error.
                  value:
                    status: BAD_REQUEST
                    message: Validation failed for argument example_argument
                    violations: []
        '402':
          description: Exhaustion of the plan or limitations related to non-payment
        '403':
          description: Forbidden
          content:
            application/vnd.authologic.v1.1+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              examples:
                Forbidden call response example:
                  summary: Forbidden example
                  description: Example of forbidden call.
                  value:
                    status: FORBIDDEN
                    message: 'Permission denied for strategy: `public:b`.'
                    violations: []
        '500':
          description: Server side error
  /api/conversations/{conversationId}/headless/{next}:
    post:
      tags:
      - Enterprise Integration
      summary: Send the information obtained from the user during the identity verification process
      description: '

        Takes the information from the user and calculates the next step that should be rendered to the user.


        Detailed description of returned attributes:


        | Parameter | Example | Description |

        | --------- | ------- | ----------- |

        | component | `GLOBAL/ACCEPTED` | Name of method related with current step and expected action related to UI in verification
        process. |

        | next | `fd78cf43-12a7...` | Id of the page to which the user information should be submitted. Information is sent
        via the method `POST /api/conversations/{conversationId}/headless/{next}`. |

        | args | parameter name list | List of parameters that should be displayed to the user. |

        | errors | map with field name and error description | A map specifying incorrectly entered form fields and a description
        of the associated error. |

        | errors.field | parameter name sent in `body` attribute, validated and marked as incorrect | Value specifying incorrectly
        entered form field. |

        | errors.code  | error code related to the field described in `errors.field` attribute | Value describing the error
        associated to the form field. |

        '
      operationId: nextStep
      parameters:
      - name: conversationId
        in: path
        description: Conversation ID
        required: true
        schema:
          type: string
      - name: next
        in: path
        description: Next step ID
        required: true
        schema:
          type: string
      - name: X-User-IP
        in: header
        description: User IP Address
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeadlessNextPageRequest'
        required: true
      responses:
        '200':
          description: Information available
          content:
            application/vnd.authologic.v1.1+json:
              schema:
                $ref: '#/components/schemas/HeadlessPage'
        '400':
          description: Bad Request
          content:
            application/vnd.authologic.v1.1+json:
              schema:
                type: string
                oneOf:
                - $ref: '#/components/schemas/BadRequestApiError'
                - $ref: '#/components/schemas/MethodArgumentNotValidError'
                - $ref: '#/components/schemas/MethodArgumentTypeMismatchError'
                - $ref: '#/components/schemas/ConstraintViolationError'
                - $ref: '#/components/schemas/CustomValidationApiError'
                - $ref: '#/components/schemas/OperationNotSupportedApiFieldError'
                - $ref: '#/components/schemas/MissingHeaderApiError'
              example:
                status: BAD_REQUEST
                message: 'JSON body has an illegal format [Line: 10, Column: 12]: Unexpected character (''"'' (code 34)):
                  was expecting Array entries.'
                violations: []
        '402':
          description: Exhaustion of the plan or limitations related to non-payment
        '403':
          description: Permission denied
          content:
            application/vnd.authologic.v1.1+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: FORBIDDEN
                message: 'Permission denied for strategy: `public:global`.'
                violations: []
        '404':
          description: Conversation not found
          content:
            application/vnd.authologic.v1.1+json:
              schema:
                $ref: '#/components/schemas/ApiError'
              example:
                status: NOT_FOUND
                message: Item not found
                violations: []
        '500':
          description: Server side error
  /api/conversations/{conversationId}:
    get:
      tags:
      - Conversation
      summary: Retrieving up-to-date data as defined by the user identity verification process
      description: "\n::warning\nIn practice, instead of this method you should use the callback mechanism described <a href=\"\
        https://developer.authologic.com/docs/developer-documentation/integration-callbacks\">here</a>.\n::\n\nReturns information\
        \ about how the identity validation process is performed for the given conversation ID.\nIn the case of using the\
        \ callback mechanism, the use of this method is optional - data needed\nare sent automatically when they change.\n\
        \n## Detailed Description of the Reply Contents\n\n| Parameter | Example                                         \
        \                              | Description                                                                     \
        \                                                                                                                \
        \                                                                                           |\n|-----------|-------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n\
        | id | `e0c0b3cc-8238-414f-9940-9f14bd1b8693`                                          | Conversation ID.        \
        \                                                                                                                \
        \                                                                                                                \
        \                                   |\n| userKey | `7dfb9ded-c38f-49ae-95e2-307283a0b1f6`                        \
        \                  | User ID on your system.                                                                     \
        \                                                                                                                \
        \                                                                               |\n| url | `https://sandbox.authologic.com/c/c12c1adc-3ff0-4d32-b95c-c593135c903e`\
        \         | A unique web address to which the user should be redirected to verify his identity.                  \
        \                                                                                                                \
        \                                                                      |\n| status | `FINISHED`                  \
        \                                                    | Conversation status: `CREATED` - ready conversation, `IN_PROGRESS`\
        \ - query data being specified, `FINISHED` - query is complete,  `CANCELED` - user aborted, `EXPIRED` - conversation\
        \ expired     |\n| result | -                                                                             | Structure\
        \ describing the information found                                                                               \
        \                                                                                                                \
        \                                                  |\n| result.identity | -                                      \
        \                                       | Structure describing the result of the identity check                  \
        \                                                                                                                \
        \                                                                                                    |\n| result.identity.status\
        \ |                                                                               | Identity validation effect: `IN_PROGRESS`\
        \ - checks in progress, `FINISHED` - checks from query complete, `PARTIAL` - checks completed but only part of the\
        \ data could be determined, `FAILED` - checks completed but no data could be determined.                         \
        \                 |\n| result.identity.user | (see example in `verify.user` from `/api/conversations`)           \
        \           | User information                                                                                   \
        \                                                                                                                \
        \                                                                        |\n| result.identity.errors | `[\"SCAN_DOCUMENT_NOT_DETECTED\"\
        ]`                                                | Information about the causes of errors. The content depends on\
        \ the specific method of verification                                                                            \
        \                                                                                                             |\n\
        | result.identity.checks | -                                                                             | A list\
        \ of additional validations performed on user data                                                               \
        \                                                                                                                \
        \                                                     |\n| result.aml | -                                        \
        \                                     | Structure describing the result of user checking on AML lists            \
        \                                                                                                                \
        \                                                                                                  |\n| result.aml.status\
        \ |                                                                               | User checking effect. Same as\
        \ the `result.identity.status` field                                                                             \
        \                                                                                                                \
        \                              |\n| result.aml.found | `[\"PEP\", \"SANCTIONS\", \"ADVERSE_MEDIA\", \"SIP\", \"OTHER\"\
        ]`                         | A table informing about the AML lists on which user data was found.                 \
        \                                                                                                                \
        \                                                                                       |\n| result.aml.subscription\
        \ | -                                                                             | Structure that informs that the\
        \ AMLs to be checked are periodic                                                                                \
        \                                                                                                                \
        \                            |\n| result.aml.subscription.active | `true`                                        \
        \                                  | Structure that informs about active periodic AML checking                   \
        \                                                                                                                \
        \                                                                                               |\n| result.aml.subscription.lastChanged\
        \ | `\"2020-09-17T11:18:21.999Z\"`                                                    | Date when the user's information\
        \ on the AMLs was last changed                                                                                   \
        \                                                                                                                \
        \                           |\n| result.verify | -                                                               \
        \              | Structure describing the result of comparing the data obtained from the identity verification process\
        \                                                                                                                \
        \                                                                      |\n| result.verify.status |               \
        \                                                                | Identity validation effect: `IN_PROGRESS` - checks\
        \ in progress, `FINISHED` - checks from query complete, `PARTIAL` - checks completed but only part of the data could\
        \ be determined, `FAILED` - checks completed but no data could be determined.                                    \
        \      |\n| result.verify.reliability | `0.66667`                                                                \
        \       | A number specifying the similarity of the data obtained from the identity check process to the data provided\
        \ in the query, where `0` means different data and `1.0` means identical data. Due to the differences in the format,\
        \ data recording the value can be any value between 0 and 1. |\n| result.verify.details | -                      \
        \                                                       | Details of the individual data comparison storing the name\
        \ of the field being compared and a number indicating the similarity of the data.                                \
        \                                                                                                                \
        \ |\n| result.auth | -                                                                             | Structure describing\
        \ the result of user authentication                                                                              \
        \                                                                                                                \
        \                                       |\n| result.auth.status |                                                \
        \                               | Authentication status: `IN_PROGRESS` - checks in progress, `FINISHED` - checks from\
        \ query complete, `FAILED` - checks completed but no data could be determined.                                   \
        \                                                                                         |\n| result.auth.token |\
        \ `a7d5d522-5308-4ec9-9789-53b4ec6d47ae`                                          | A unique user ID associated with\
        \ a given login method. Going through the login process again with the given method will always return the same token.\
        \                                                                                                                \
        \                      |\n| result.auth.challenge | `403ad98c-c5fd-4991-a365-12ec70a93932`                       \
        \                   | A unique equivalent of the user login associated with a given login method. Used in methods\
        \ that cannot determine who is authenticating and need this information to run the process.                      \
        \                                                                                |\n| result.bankTransactions | -\
        \                                                                             | Structure describing the result of\
        \ downloading transactions                                                                                       \
        \                                                                                                                \
        \                         |\n| result.bankTransactions.status |                                                  \
        \                             | Effect of downloading transactions. Same as the `result.identity.status`         \
        \                                                                                                                \
        \                                                                                          |\n| result.affordability\
        \ | -                                                                             | Structure describing the result\
        \ of the identity check                                                                                          \
        \                                                                                                                \
        \                            |\n| result.affordability.status |                                                  \
        \                             | Affordability assessment validation effect: `IN_PROGRESS` - checks in progress, `FINISHED`\
        \ - checks from query complete, `FAILED` - checks completed but no data could be determined.                     \
        \                     |\n| result.affordability.errors | `[\"PROVIDER_UNAVAILABLE\"]`                            \
        \                    | Information about the causes of errors.                                                   \
        \                                                                                                                \
        \                 |\n| result.databaseVerification | -                                                           \
        \                  | Structure describing the result of the database verification check                          \
        \                                                                                                                \
        \                                                                                            |\n| result.databaseVerification.status\
        \ |                                                                        | Database verification effect: `IN_PROGRESS`\
        \ - checks in progress, `FINISHED` - checks from query complete, `PARTIAL` - checks completed but only part of the\
        \ data could be determined, `FAILED` - the checks have been completed, but none of the databases were successfully\
        \ verified.                                          |\n| info | -                                               \
        \                              | Optional information containing an array describing the data sources used in the\
        \ conversation.                                                                                                  \
        \                                                                                           |\n| info.country | `PL`\
        \                                                                            | Selected/used country in ISO 3166-1\
        \ alpha-2 format                                                                                                 \
        \                                                                                                                \
        \                        |\n| method | `PSD2`                                                                    \
        \      | Data source used specifying the verification method or data source used.                                \
        \                                                                                                            

# --- truncated at 32 KB (190 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/authologic/refs/heads/main/openapi/authologic-customer-api-openapi.yml