{"id":18656834,"url":"https://github.com/zendesk/basecrm-java","last_synced_at":"2025-06-10T18:06:24.975Z","repository":{"id":31434819,"uuid":"34998423","full_name":"zendesk/basecrm-java","owner":"zendesk","description":"BaseCRM API Client for Java","archived":false,"fork":false,"pushed_at":"2023-04-09T15:12:55.000Z","size":456,"stargazers_count":11,"open_issues_count":3,"forks_count":9,"subscribers_count":89,"default_branch":"master","last_synced_at":"2025-03-25T16:55:30.369Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zendesk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-05-03T19:45:34.000Z","updated_at":"2023-12-19T17:37:43.000Z","dependencies_parsed_at":"2024-11-07T07:41:42.979Z","dependency_job_id":null,"html_url":"https://github.com/zendesk/basecrm-java","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fbasecrm-java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fbasecrm-java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fbasecrm-java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fbasecrm-java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zendesk","download_url":"https://codeload.github.com/zendesk/basecrm-java/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248458453,"owners_count":21107081,"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":[],"created_at":"2024-11-07T07:25:29.597Z","updated_at":"2025-04-11T18:31:22.548Z","avatar_url":"https://github.com/zendesk.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# basecrm-java\n\nBaseCRM Official API V2 library client for Java (1.6+)\n\n## Installation\n\nThe following instruction assume you have [Gradle Build System](http://gradle.org/) installed.\n\nThe library is available via [Maven central](https://search.maven.org/). To install, add the following content to your `build.gradle` file:\n\n```groovy\nrepositories {\n    mavenCentral()\n}\n\ndependencies {\n  compile \"com.getbase:basecrm-java:1.5.2\"\n}\n```\n\n## Usage\n\n```java\nimport com.getbase.*;\n\n// Then we instantiate a client (as shown below)\n```\n\n### Build a client\n__Using this api without authentication gives an error__\n\n```java\nClient client = new Client(new Configuration.Builder()\n                .accessToken(System.getenv(\"BASECRM_ACCESS_TOKEN\"))\n                .verbose()\n                .build());\n```\n\n### Client Options\n\nThe following builder options are available while instantiating a client:\n\n * __accessToken__: Personal access token\n * __baseUrl__: Base url for the api. Default: `https://api.getbase.com`\n * __userAgent__: Default user-agent for all requests. Default: `BaseCRM/V2 Java/1.5.2`\n * __timeout__: Request timeout. Default: `30` seconds\n * __verbose__: Verbose/debug mode. Default: `false`\n * __verifySSL__: Whether to skip SSL verification or not. Default: `true`\n\n### Architecture\n\nThe library follows few architectural principles you should understand before digging deeper.\n1. Interactions with resources are done via service objects.\n2. Service objects are exposed as methods on client instances.\n3. Service objects expose resource-oriented actions.\n4. Actions return Plain Old Java Objects.\n\nFor example, to interact with deals API you will use `com.getbase.services.DealsService`, which you can get if you call:\n\n```java\nclient.deals(); // =\u003e com.getbase.services.DealsService\n```\n\nWhen you want to list resources you will use `#list` method which returns a `java.util.List` of resources.\nYou can specify search criteria either by using `SearchCriteria` builder or by passing `java.util.Map`.\nNotice that every single service which supports resource listing action, exposes it's own `SearchCriteria`:\n\n```java\nimport com.getbase.services.LeadsService;\n\nclient.leads().list(new LeadsService.SearchCriteria()\n                .page(1)\n                .perPage(100))\n                .stream()\n                .forEach(System.out::println);\n```\n\nTo find a resource by it's unique identifier use `#get` method:\n\n```java\nimport com.getbase.models.Deal;\n\nDeal deal = client.deals().get(id);\n```\n\nWhen you'd like to create a resource, or update it's attributes you want to use either `#create` or `#update` methods. Both of them can take either `java.util.Map` or a model class e.g. `com.getbase.models.Deal` instance. For example if you want to create a new deal you will call:\n\n```java\nimport com.getbase.models.*;\nimport com.getbase.services.*;\n\nContact coffeeShop = client.contacts().list(new ContactsService.SearchCriteria()\n                          .page(1)\n                          .perPage(1)\n                          .name(\"Coffee Shop\"))\n                          .get(0);\n\nDeal redesign = new Deal();\nredesign.setContactId(coffeeShop.getId());\nredesign.setName(\"Website redesign\");\nDeal newDeal  = client.deals().create(redesign);\n\nnewDeal.setValue(new BigDecimal(\"1000.00\"));\nnewDeal.setCurrency(\"USD\");\nclient.deals().update(newDeal);\n```\n\nTo destroy a resource use `#delete` method:\n\n```java\nboolean deleted = client.deals().delete(id);\n```\n\nThere other non-CRUD operations supported as well. Please contact corresponding service files for in-depth documentation.\n\n## Sync API\n\nThe following sample code shows how to perform a full synchronization flow using high-level wrapper.\n\nFirst of all you need an instance of `com.getbase.Client`. High-level `com.getbase.sync.Sync` wrapper uses `com.getbase.sync.SyncService` to interact with the Sync API.\nIn addition to the client instance, you must provide a device's UUID within `deviceUUID` parameter. The device's UUID must not change between synchronization session, otherwise the sync service will not recognize the device and will send all the data again.\n\n```java\nimport com.getbase.*;\nimport com.getbase.sync.*;\n\nClient client = new Client(new Configuration.Builder()\n                .accessToken(System.getenv(\"BASECRM_ACCESS_TOKEN\"))\n                .build());\n\nString deviceUUID = System.getenv(\"BASECRM_DEVICE_UUID\");\nSync sync = new Sync(client, deviceUUID);\n```\n\nNow you have two options. Either subscribe to stream of all resources using a single observer, or subscribe to each resource separately and call `fetch` without arguments.\n\n```java\nimport com.getbase.models.*;\n\nsync.subscribe(Lead.class, (meta, lead) -\u003e true)\n    .subscribe(Contact.class, (meta, contact) -\u003e true)\n    .fetch();\n```\n\nNotice that, when you return `true` from the predicate, the wrapper will eventually ack the data.\n\n## Logging\nBaseCRM client uses Simple Logging Facade for Java (SLF4J) to track some diagnostic information. SLF4J is a logging facade that can work with various logging frameworks, such as java.util.logging, logback and log4j. BaseCRM client does not impose any particular logging framework and lets end user to plug-in desired framework at the deployment time. To learn how to provide logging binding refer to SLF4J [manual](http://www.slf4j.org/manual.html#swapping).\n\nNote that client verbose traces have also been redirected to SLF4J to allow common log configuration. However, this means you will not be able to see these logs any more unless you provide logger binding as described above.\n\n## Resources and actions\n\nDocumentation for every action can be found in corresponding service files under `src/main/java/com/getbase/services/` directory.\n\n### Account\n\n```java\nclient.accounts(); // =\u003e com.getbase.services.AccountsService\n```\n\nActions:\n* Retrieve account details - `client.accounts().self()`\n\n### AssociatedContact\n\n```java\nclient.associatedContacts(); // =\u003e com.getbase.services.AssociatedContactsService\n```\n\nActions:\n* Retrieve deal's associated contacts - `client.associatedContacts().list()`\n* Create an associated contact - `client.associatedContacts().create()`\n* Remove an associated contact - `client.associatedContacts().delete()`\n\n### Call\n\n```java\nclient.calls(); // =\u003e com.getbase.services.CallsService\n```\n\nActions:\n* Retrieve all calls - `client.calls().list()`\n* Create a call - `client.calls().create()`\n* Retrieve a single call - `client.calls().get()`\n* Update a call - `client.calls().update()`\n* Delete a call - `client.calls().delete()`\n\n### Call Outcome\n\n```java\nclient.callOutcomes(); // =\u003e com.getbase.services.CallOutcomesService\n```\n\nActions:\n* Retrieve all call outcomes - `client.callOutcomes().list()`\n\n### Collaboration\n\n```java\nclient.collaborations(); // =\u003e com.getbase.services.CollaborationsService\n```\n\nActions:\n* Retrieve all collaborations - `client.collaborations().list()`\n* Create a collaboration - `client.collaborations().create()`\n* Retrieve a single collaboration - `client.collaborations().get()`\n* Delete a collaboration - `client.collaborations().delete()`\n\n### Contact\n\n```java\nclient.contacts(); // =\u003e com.getbase.services.ContactsService\n```\n\nActions:\n* Retrieve all contacts - `client.contacts().list()`\n* Create a contact - `client.contacts().create()`\n* Retrieve a single contact - `client.contacts().get()`\n* Update a contact - `client.contacts().update()`\n* Delete a contact - `client.contacts().delete()`\n\n### Deal\n\n```java\nclient.deals(); // =\u003e com.getbase.services.DealsService\n```\n\nActions:\n* Retrieve all deals - `client.deals().list()`\n* Create a deal - `client.deals().create()`\n* Retrieve a single deal - `client.deals().get()`\n* Update a deal - `client.deals().update()`\n* Delete a deal - `client.deals().delete()`\n\n### DealUnqualifiedReason\n\n```java\nclient.dealUnqualifiedReasons(); // =\u003e com.getbase.services.DealUnqualifiedReasonsService\n```\n\nActions:\n* Retrieve all deal unqualified reasons - `client.dealUnqualifiedReasons().list()`\n* Create a deal unqualified reason - `client.dealUnqualifiedReasons().create()`\n* Retrieve a single deal unqualified reason - `client.dealUnqualifiedReasons().get()`\n* Update a deal unqualified reason - `client.dealUnqualifiedReasons().update()`\n* Delete a deal unqualified reason - `client.dealUnqualifiedReasons().delete()`\n\n### Lead\n\n```java\nclient.leads(); // =\u003e com.getbase.services.LeadsService\n```\n\nActions:\n* Retrieve all leads - `client.leads().list()`\n* Create a lead - `client.leads().create()`\n* Retrieve a single lead - `client.leads().get()`\n* Update a lead - `client.leads().update()`\n* Delete a lead - `client.leads().delete()`\n\n### LeadUnqualifiedReason\n\n```java\nclient.leadUnqualifiedReasons(); // =\u003e com.getbase.services.LeadUnqualifiedReasonsService\n```\n\nActions:\n* Retrieve all lead unqualified reasons - `client.leadUnqualifiedReasons().list()`\n\n### LineItem\n\n```java\nclient.lineItems(); // =\u003e com.getbase.services.LineItemsService\n```\n\nActions:\n* Retrieve order's line items - `client.lineItems().list()`\n* Create a line item - `client.lineItems().create()`\n* Retrieve a single line item - `client.lineItems().get()`\n* Delete a line item - `client.lineItems().delete()`\n\n### LossReason\n\n```java\nclient.lossReasons(); // =\u003e com.getbase.services.LossReasonsService\n```\n\nActions:\n* Retrieve all reasons - `client.lossReasons().list()`\n* Create a loss reason - `client.lossReasons().create()`\n* Retrieve a single reason - `client.lossReasons().get()`\n* Update a loss reason - `client.lossReasons().update()`\n* Delete a reason - `client.lossReasons().delete()`\n\n### Note\n\n```java\nclient.notes(); // =\u003e com.getbase.services.NotesService\n```\n\nActions:\n* Retrieve all notes - `client.notes().list()`\n* Create a note - `client.notes().create()`\n* Retrieve a single note - `client.notes().get()`\n* Update a note - `client.notes().update()`\n* Delete a note - `client.notes().delete()`\n\n### Order\n\n```java\nclient.orders(); // =\u003e com.getbase.services.OrdersService\n```\n\nActions:\n* Retrieve all orders - `client.orders().list()`\n* Create an order - `client.orders().create()`\n* Retrieve a single order - `client.orders().get()`\n* Update an order - `client.orders().update()`\n* Delete an order - `client.orders().delete()`\n\n### Pipeline\n\n```java\nclient.pipelines(); // =\u003e com.getbase.services.PipelinesService\n```\n\nActions:\n* Retrieve all pipelines - `client.pipelines().list()`\n\n### Product\n\n```java\nclient.products(); // =\u003e com.getbase.services.ProductsService\n```\n\nActions:\n* Retrieve all products - `client.products().list()`\n* Create a product - `client.products().create()`\n* Retrieve a single product - `client.products().get()`\n* Update a product - `client.products().update()`\n* Delete a product - `client.products().delete()`\n\n### Source\n\n```java\nclient.sources(); // =\u003e com.getbase.services.SourcesService\n```\n\nActions:\n* Retrieve all sources - `client.sources().list()`\n* Create a source - `client.sources().create()`\n* Retrieve a single source - `client.sources().get()`\n* Update a source - `client.sources().update()`\n* Delete a source - `client.sources().delete()`\n\n### Lead Source\n\n```java\nclient.leadSources(); // =\u003e com.getbase.services.LeadSourcesService\n```\n\nActions:\n* Retrieve all lead sources - `client.leadSources().list()`\n* Create a lead source - `client.leadSources().create()`\n* Retrieve a single lead source - `client.leadSources().get()`\n* Update a lead source - `client.leadSources().update()`\n* Delete a lead source - `client.leadSources().delete()`\n\n### Stage\n\n```java\nclient.stages(); // =\u003e com.getbase.services.StagesService\n```\n\nActions:\n* Retrieve all stages - `client.stages().list()`\n\n### Tag\n\n```java\nclient.tags(); // =\u003e com.getbase.services.TagsService\n```\n\nActions:\n* Retrieve all tags - `client.tags().list()`\n* Create a tag - `client.tags().create()`\n* Retrieve a single tag - `client.tags().get()`\n* Update a tag - `client.tags().update()`\n* Delete a tag - `client.tags().delete()`\n\n### Task\n\n```java\nclient.tasks(); // =\u003e com.getbase.services.TasksService\n```\n\nActions:\n* Retrieve all tasks - `client.tasks().list()`\n* Create a task - `client.tasks().create()`\n* Retrieve a single task - `client.tasks().get()`\n* Update a task - `client.tasks().update()`\n* Delete a task - `client.tasks().delete()`\n\n### TextMessage\n\n```java\nclient.textMessages(); // =\u003e com.getbase.services.TextMessagesService\n```\n\nActions:\n* Retrieve text messages - `client.textMessages().list()`\n* Retrieve a single text message - `client.textMessages().get()`\n\n### User\n\n```java\nclient.users(); // =\u003e com.getbase.services.UsersService\n```\n\nActions:\n* Retrieve all users - `client.users().list()`\n* Retrieve a single user - `client.users().get()`\n* Retrieve an authenticating user - `client.users().self()`\n\n### Visit\n\n```java\nclient.visits(); // =\u003e com.getbase.services.VisitsService\n```\n\nActions:\n* Retrieve visits - `client.visits().list()`\n\n### VisitOutcome\n\n```java\nclient.visitOutcomes(); // =\u003e com.getbase.services.VisitOutcomesService\n```\n\nActions:\n* Retrieve visit outcomes - `client.visitOutcomes().list()`\n\n## Advanced Topic - Sync session sharing\nFor more advanced use cases when user wants to make data synchronization faster using multiple threads or processes (or uses micro-services instances) it is possible to share a single session between Sync instances.\nTo do that user can implement he's own `com.getbase.sync.SessionManager` and pass it to a Sync instance.\n\n```java\nclass MySessionManager extends SessionManager {\n\n    private MySessionRepository repository;\n\n    MySessionManager(MySessionRepository repository) {\n        this.repository = repository;\n    }\n\n    public Session getSession(String deviceUUID) {\n        return repository.findByDevice(deviceUUID);\n    }\n\n    public void setSession(String deviceUUID, Session session) {\n        repository.save(deviceUUID, session);\n    }\n\n    public void clearSession(String deviceUUID) {\n        repository.delete(deviceUUID);\n    }\n\n}\n```\n\nHere is an example how to set custom SessionManager:\n\n```java\nSync sync = new Sync(client, deviceUUID).setSessionManager(mySessionManager);\n```\n\n## Advanced Topic - Instrumenting HTTP Client\nBase API client uses Jersey HTTP Client that can be instrumented using [client filters mechanism](https://jersey.java.net/documentation/latest/filters-and-interceptors.html#d0e9771). This might be helpful if for example you want to publish performance metrics for every request, etc. In order to instrument a client or provide some additional configuration you need to implement `com.getbase.http.jersey.Builer` interface and pass it when constructing `com.getbase.http.jersey.HttpClient`.\n\nHere is an example of client filter that publishes performance metrics:\n```java\npublic class RequestMetricsFilter implements ClientRequestFilter, ClientResponseFilter {\n\n    private static final String TIMER_CONTEXT_PROPERTY_NAME = \"RequestMetricsFilter.timer\";\n\n    private final MetricNamingStrategy naming;\n\n    private final MetricRegistry metricRegistry;\n\n    public RequestMetricsFilter(MetricNamingStrategy naming, MetricRegistry metricRegistry) {\n        this.naming = naming;\n        this.metricRegistry = metricRegistry;\n    }\n\n    @Override\n    public void filter(ClientRequestContext requestContext) throws IOException {\n        final String name = naming.from(Client.class, requestContext.getUri(), requestContext.getMethod());\n        final Timer.Context timer = metricRegistry.timer(name).time();\n        requestContext.setProperty(TIMER_CONTEXT_PROPERTY_NAME, timer);\n    }\n\n    @Override\n    public void filter(ClientRequestContext requestContext, ClientResponseContext responseContext) throws IOException {\n        final Object timer = requestContext.getProperty(TIMER_CONTEXT_PROPERTY_NAME);\n        if (timer != null) {\n            final Timer.Context timerContext = (Timer.Context) timer;\n            timerContext.stop();\n            requestContext.removeProperty(TIMER_CONTEXT_PROPERTY_NAME);\n        }\n    }\n\n}\n```\n\nThen you need to register this filter in Jersey `ClientConfig` in your `Builder.build` method:\n```java\npublic class InstrumentedHttpClientBuilder implements Builder {\n\n    @Override\n    public Client build(Configuration config) {\n        ClientConfig clientConfig = new ClientConfig();\n\n        clientConfig.register(requestMetricsFilter);\n\n        \\\\do additional client config here\n\n        return newClient(clientConfig);\n    }\n}\n```\n\nFinally you need to pass your `Builder` when constructing a `Client`.\n```java\n final HttpClient httpClient = new HttpClient(config, new InstrumentedHttpClientBuilder(requestMetricsFilter));\n Client client = new Client(config, httpClient);\n```\n\n## Bug Reports\nReport [here](https://github.com/basecrm/basecrm-java/issues).\n\n## Copyright and license\n\nCopyright 2015 Zendesk\n\nLicensed under the [Apache License, Version 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzendesk%2Fbasecrm-java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzendesk%2Fbasecrm-java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzendesk%2Fbasecrm-java/lists"}