{"id":23698069,"url":"https://github.com/inloco/incognia-api-java","last_synced_at":"2025-07-20T08:05:27.018Z","repository":{"id":37555262,"uuid":"369309011","full_name":"inloco/incognia-api-java","owner":"inloco","description":"Java client library for Incognia's API","archived":false,"fork":false,"pushed_at":"2025-07-08T22:34:22.000Z","size":564,"stargazers_count":5,"open_issues_count":17,"forks_count":4,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-07-08T23:33:34.874Z","etag":null,"topics":["java"],"latest_commit_sha":null,"homepage":"https://www.incognia.com/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inloco.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-05-20T18:54:15.000Z","updated_at":"2025-07-08T22:34:26.000Z","dependencies_parsed_at":"2023-02-16T15:01:04.267Z","dependency_job_id":"9a0a493a-c219-41d5-8c7e-53ce28eadb0e","html_url":"https://github.com/inloco/incognia-api-java","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/inloco/incognia-api-java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inloco%2Fincognia-api-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inloco%2Fincognia-api-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inloco%2Fincognia-api-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inloco%2Fincognia-api-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inloco","download_url":"https://codeload.github.com/inloco/incognia-api-java/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inloco%2Fincognia-api-java/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266087790,"owners_count":23874519,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["java"],"created_at":"2024-12-30T07:13:29.988Z","updated_at":"2025-07-20T08:05:27.003Z","avatar_url":"https://github.com/inloco.png","language":"Java","readme":"# Incognia API Java Client\n![test workflow](https://github.com/inloco/incognia-api-java/actions/workflows/test.yaml/badge.svg)\n\nJava lightweight client library for [Incognia APIs](https://dash.incognia.com/api-reference).\n\n## Installation\n\nIncognia API Java Client is available on Incognia's Maven Repository. We provide 2 artifact ids: `incognia-api-client` and `incognia-api-client-shaded`.\n`incognia-api-client-shaded` includes all of our dependencies shaded into a single jar, so you don't need to worry about dependency conflicts.\n\n### Maven\nAdd our maven repository\n```xml\n\u003crepository\u003e \n     \u003cid\u003eincognia\u003c/id\u003e\n     \u003curl\u003ehttps://repo.incognia.com/java\u003c/url\u003e\n\u003c/repository\u003e\n```\n\nAnd then add the artifact `incognia-api-client` **or** `incognia-api-client-shaded` as a dependency:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.incognia\u003c/groupId\u003e\n  \u003cartifactId\u003eincognia-api-client\u003c/artifactId\u003e\n  \u003cversion\u003e3.8.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.incognia\u003c/groupId\u003e\n  \u003cartifactId\u003eincognia-api-client-shaded\u003c/artifactId\u003e\n  \u003cversion\u003e3.8.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n### Gradle\nAdd our maven repository\n```gradle\nrepositories {\n    maven {\n        url 'https://repo.incognia.com/java'\n    }\n}\n```\n\nAnd then add the dependency\n```gradle\ndependencies {\n     implementation 'com.incognia:incognia-api-client:3.8.0'\n}\n```\nOR\n```gradle\ndependencies {\n     implementation 'com.incognia:incognia-api-client-shaded:3.8.0'\n}\n```\n\nWe support Java 8+.\n\n## Usage\n\n### Configuration\n\nBefore calling the API methods, you need to create an instance of the `IncogniaAPI` class.\n\n```java\nIncogniaAPI api = IncogniaAPI.init(\"your-client-id\", \"your-client-secret\");\n```\n\nThis will create a instance of the IncogniaAPI class, which will handle token renewal automatically. You should reuse this instance throughout your application.\n\nThe IncogniaAPI class implements the Multiton design pattern by maintaining a single instance per unique (client id, client secret) pair.\n\nThe library also allow the users to configure the call timeout themselves. This will give them more control over the expected time response. This can be done by calling the init passing the CustomOptions object as a parameter.\n\n\n```java\nIncogniaAPI api = IncogniaAPI.init(\n    \"your-client-id\",\n    \"your-client-secret\",\n    CustomOptions.builder()\n    .timeoutMillis(2000L)\n    .keepAliveSeconds(3000)\n    .maxConnections(5)\n    .build()\n);\n```\n\nIf no parameter is passed the library will use the default timeout of 10 seconds, 5 minutes of keep alive and 5 max connections.\n\nAfter calling `init`, you can get the created instance by simply calling `IncogniaAPI.instance()` if only one instance has been created, \nor by calling `IncogniaAPI.instance(\"your-client-id\", \"your-client-secret\")` to specify which instance should be returned.\n\nIf you need to use more than one `clientId`/`clientSecret`, it is recommended to use **only** the \n`IncogniaAPI.instance(\"your-client-id\", \"your-client-secret\")` to get already created instances.\n\n#### Dependency Injection integration examples\n\nIf you use a dependency injection framework, you can create a singleton bean for the `IncogniaAPI` class. Below are some examples using common java frameworks:\n\nSpring Boot:\n```java\n@Configuration\npublic class IncogniaAPIConfig {\n    @Value(\"${incognia.client-id}\")// change this to your property name\n    private String clientId;\n    \n    @Value(\"${incognia.client-secret}\") //change this to your property name\n    private String clientSecret;\n    \n    @Bean\n    @Scope(value = ConfigurableBeanFactory.SCOPE_SINGLETON)\n    public IncogniaAPI incogniaAPI() {\n        return IncogniaAPI.init(clientId, clientSecret);\n    }\n}\n```\n\nMicronaut:\n```java\n@Factory\npublic class IncogniaAPIFactory {\n    @Singleton\n    //change the @Value to your property name\n    public IncogniaAPI incogniaAPI(@Value(\"${incognia.client-id}\") String clientId,\n        @Value(\"${incognia.client-secret}\") String clientSecret) {\n        return IncogniaAPI.init(clientId, clientSecret);\n    }\n}\n```\n\n### Incognia API\n\nThe implementation is based on the [Incognia API Reference](https://dash.incognia.com/api-reference).\n\n#### Authentication\n\nAuthentication is done transparently, so you don't need to worry about it.\n\nIf you are curious about how we handle it, you can check the `TokenAwareNetworkingClient` class\n\n#### Registering Signup\n\nThis method registers a new signup for the given request token and address, returning a `SignupAssessment`, containing the risk assessment and supporting evidence:\n\n```java\nIncogniaAPI api = IncogniaAPI.init(\"client-id\", \"client-secret\");\ntry {\n     Address address =\n        Address.builder()\n            .structuredAddress(\n                StructuredAddress.builder()\n                    .countryCode(\"US\")\n                    .countryName(\"United States of America\")\n                    .locale(\"en-US\")\n                    .state(\"NY\")\n                    .city(\"New York City\")\n                    .borough(\"Manhattan\")\n                    .neighborhood(\"Midtown\")\n                    .street(\"W 34th St.\")\n                    .number(\"20\")\n                    .complements(\"Floor 2\")\n                    .postalCode(\"10001\")\n                    .build())\n            .coordinates(new Coordinates(40.74836007062138, -73.98509720487937))\n            .build();\n    RegisterSignupRequest signupRequest = RegisterSignupRequest.builder()\n        .address(address)\n        .requestToken(\"request token\")\n        .build();\n     SignupAssessment assessment = api.registerSignup(signupRequest);\n} catch (IncogniaAPIException e) {\n     //Some api error happened (invalid data, invalid credentials)\n} catch (IncogniaException e) {\n     //Something unexpected happened\n}\n```\n\nIt's also possible to register a signup without an address:\n\n```java\nIncogniaAPI api = IncogniaAPI.init(\"client-id\", \"client-secret\");\ntry {\n    RegisterSignupRequest signupRequest = RegisterSignupRequest.builder()\n        .requestToken(\"request token\")\n        .build();\n     SignupAssessment assessment = api.registerSignup(signupRequest);\n} catch (IncogniaAPIException e) {\n     //Some api error happened (invalid data, invalid credentials)\n} catch (IncogniaException e) {\n     //Something unexpected happened\n}\n```\n\n#### Registering Web Signup\n\nThis method registers a new web signup for the given request token, returning a `SignupAssessment`, containing the risk assessment and supporting evidence:\n\n```java\nIncogniaAPI api = IncogniaAPI.init(\"client-id\", \"client-secret\");\ntry {\n    RegisterWebSignupRequest webSignupRequest = RegisterWebSignupRequest.builder()\n        .requestToken(\"request token\")\n        .build();\n     SignupAssessment assessment = api.registerWebSignup(webSignupRequest);\n} catch (IncogniaAPIException e) {\n     //Some api error happened (invalid data, invalid credentials)\n} catch (IncogniaException e) {\n     //Something unexpected happened\n}\n```\n\n#### Registering Login\n\nThis method registers a new login for the given request token and account, returning a `TransactionAssessment`, containing the risk assessment and supporting evidence.\nThis method also includes some overloads that do not require optional parameters, like `externalId`.\n\n```java\nIncogniaAPI api = IncogniaAPI.init(\"client-id\", \"client-secret\");\ntry {\n     RegisterLoginRequest registerLoginRequest =\n        RegisterLoginRequest.builder()\n          .requestToken(\"request token\")\n          .accountId(\"account id\")\n          .externalId(\"external id\")\n          .evaluateTransaction(true) // can be omitted as it uses true as the default value\n          .customProperties(Map.of(\n            \"custom-property-key\", \"custom-property-value\",\n            \"custom-double-property-key\", 1.0))\n          .build();\n     TransactionAssessment assessment = api.registerLogin(registerLoginRequest);\n} catch (IncogniaAPIException e) {\n     //Some api error happened (invalid data, invalid credentials)\n} catch (IncogniaException e) {\n     //Something unexpected happened\n}\n```\n\n#### Registering Web Login\n\nThis method registers a new web login for the given request token and account, returning a `TransactionAssessment`, containing the risk assessment and supporting evidence.\n\n```java\nIncogniaAPI api = IncogniaAPI.init(\"client-id\", \"client-secret\");\ntry {\n     RegisterWebLoginRequest webLoginRequest =\n        RegisterWebLoginRequest.builder()\n          .accountId(\"account id\")\n          .externalId(\"external id\")\n          .requestToken(\"request-token\")\n          .evaluateTransaction(true) // can be omitted as it uses true as the default value\n          .build();\n     TransactionAssessment assessment = api.registerWebLogin(webLoginRequest);\n} catch (IncogniaAPIException e) {\n     //Some api error happened (invalid data, invalid credentials)\n} catch (IncogniaException e) {\n     //Something unexpected happened\n}\n```\n\n#### Registering Payment\n\nThis method registers a new payment for the given request token and account, returning a `TransactionAssessment`, containing the risk assessment and supporting evidence.\nThis method also includes some overloads that do not require optional parameters, like `externalId` and `addresses`.\n\n```java\nIncogniaAPI api = IncogniaAPI.init(\"client-id\", \"client-secret\");\ntry {\n     Address address = Address address =\n        Address.builder()\n            .structuredAddress(\n                StructuredAddress.builder()\n                    .countryCode(\"US\")\n                    .countryName(\"United States of America\")\n                    .locale(\"en-US\")\n                    .state(\"NY\")\n                    .city(\"New York City\")\n                    .borough(\"Manhattan\")\n                    .neighborhood(\"Midtown\")\n                    .street(\"W 34th St.\")\n                    .number(\"20\")\n                    .complements(\"Floor 2\")\n                    .postalCode(\"10001\")\n                    .build())\n            .coordinates(new Coordinates(40.74836007062138, -73.98509720487937))\n            .build();\n     \n     Map\u003cAddressType, Address\u003e addresses = Map.of(\n         AddressType.SHIPPING, address\n         AddressType.BILLING, address);\n     \n     List\u003cPaymentMethod\u003e paymentMethods = new ArrayList\u003c\u003e();\n        paymentMethods.add(\n            PaymentMethod.builder()\n                .creditCardInfo(\n                    CardInfo.builder()\n                        .bin(\"123456\")\n                        .expiryMonth(\"10\")\n                        .expiryYear(\"2028\")\n                        .lastFourDigits(\"4321\")\n                        .build())\n                .type(PaymentType.CREDIT_CARD)\n                .build());\n        \n     RegisterPaymentRequest registerPaymentRequest =\n         RegisterPaymentRequest.builder()\n             .requestToken( \"request-token\")\n             .accountId(\"account-id\")\n             .externalId(\"external-id\")\n             .addresses(addresses)\n             .evaluateTransaction(true) // can be omitted as it uses true as the default value\n             .paymentValue(PaymentValue.builder().currency(\"BRL\").amount(10.0).build())\n             .paymentMethods(paymentMethods)\n             .build();\n    \n     TransactionAssessment assessment = api.registerPayment(registerPaymentRequest);\n} catch (IncogniaAPIException e) {\n     //Some api error happened (invalid data, invalid credentials)\n} catch (IncogniaException e) {\n     //Something unexpected happened\n}\n```\n\n### Registering Payment or Login without evaluating its risk assessment\n\nTurning off the risk assessment evaluation allows you to register a new transaction (Login or Payment), but the response (`TransactionAssessment`) will be empty. For instance, if you're using the risk assessment only for some payment transactions, you should still register all the other ones: this will avoid any bias on the risk assessment computation.\n\nTo register a login or a payment without evaluating its risk assessment, you should use the `evaluateTransaction` boolean set to false\n\nExample:\n\n\n```java\nRegisterLoginRequest registerLoginRequest =\n        RegisterLoginRequest.builder()\n          .requestToken(\"request token\")\n          .accountId(\"account id\")\n          .externalId(\"external id\")\n          .evaluateTransaction(false)\n          .build();\n```\nWould return an empty risk assessment response:\n\n``{}``\n\n#### Sending Feedback\n\nThis method registers a feedback event for the given identifiers (represented in `FeedbackIdentifiers`) related to a signup, login or payment.\n\n```java\nIncogniaAPI api = IncogniaAPI.init(\"client-id\", \"client-secret\");\ntry {\n    Instant timestamp = Instant.now();\n    client.registerFeedback(\n       FeedbackEvent.ACCOUNT_TAKEOVER,\n       timestamp,\n       FeedbackIdentifiers.builder()\n           .requestToken(\"request-token\")\n           .accountId(\"account-id\")\n           .externalId(\"external-id\")\n           .signupId(\"c9ac2803-c868-4b7a-8323-8a6b96298ebe\")\n           .build();\n} catch (IncogniaAPIException e) {\n     //Some api error happened (invalid data, invalid credentials)\n} catch (IncogniaException e) {\n     //Something unexpected happened\n}\n```\n\n## Evidences\n\nEvery assessment response (`TransactionAssessment` and `SignupAssessment`) includes supporting evidence in a generic `Map\u003cString, Object\u003e`.\nYou can find all available evidence [here](https://docs.incognia.com/apis/understanding-assessment-evidence#risk-assessment-evidence).\n\n## Exception handling\n\nEvery method call can throw `IncogniaAPIException` and `IncogniaException`.\n\n`IncogniaAPIException` is thrown when the API returned an unexpected http status code. You can retrieve it by calling the `getStatusCode` method in the exception,\nalong with the `getPayload` method, which returns the api response payload, which might include additional details.\n\n`IncogniaException` represents unknown errors, like serialization/deserialization errors.\n\n## How to Contribute\n\nIf you have found a bug or if you have a feature request, please report them at this repository issues section.\n\n## What is Incognia?\n\nIncognia is a location identity platform for mobile apps that enables:\n\n- Real-time address verification for onboarding\n- Frictionless authentication\n- Real-time transaction verification\n\n## License\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finloco%2Fincognia-api-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finloco%2Fincognia-api-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finloco%2Fincognia-api-java/lists"}